@cosmicdrift/kumiko-dev-server 0.297.0 → 0.299.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.297.0",
+  "version": "0.299.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -59,10 +59,10 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.297.0",
-    "@cosmicdrift/kumiko-framework": "0.297.0",
-    "@cosmicdrift/kumiko-headless": "0.297.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.297.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.299.0",
+    "@cosmicdrift/kumiko-framework": "0.299.0",
+    "@cosmicdrift/kumiko-headless": "0.299.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.299.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

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

@@ -2,18 +2,25 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { NO_ROUTE_MATCH_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
+import {
+  ExtraRouteRejection,
+  NO_ROUTE_MATCH_HEADER_NAME,
+  signatureRoute,
+} from "@cosmicdrift/kumiko-framework/api";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   createBooleanField,
   createEntity,
   createTextField,
   defineFeature,
+  type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
 import { z } from "zod";
 import { createKumikoServer, type KumikoServerHandle } from "../create-kumiko-server";
 
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+
 // Integration-Test: bootet createKumikoServer mit echtem Postgres,
 // echtem Redis, echter Kumiko-Pipeline. Treibt den fetch-Handler
 // direkt an (nicht über Bun.serve + Socket), weil vitest unter Node
@@ -30,8 +37,16 @@ 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
+  // Anonymous query for hostDispatch's deps.systemQuery — proves the
+  // dev path gets the same anonymous-role dispatch-deps shape as prod.
+  r.queryHandler({
+    name: "ping",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    handler: async () => ({ pong: true }),
+  });
+  // SystemAdmin-gated write — Ziel der entry:"signature" / `wire`-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",
@@ -320,35 +335,77 @@ describe("createKumikoServer (Multi-Entry)", () => {
     );
     expect(res.status).toBe(404);
   });
+
+  test("hostDispatch: async fn erhält deps.systemQuery, 'not-found' → 404 (kumiko-framework#3050 dev-Pendant)", async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "kumiko-multi-it-"));
+    const publicEntry = join(tmpDir, "client-public.tsx");
+    writeFileSync(publicEntry, "// public");
+    let systemQueryPonged = false;
+
+    handle = await createKumikoServer({
+      features: [probeFeature],
+      port: 0,
+      installSignalHandlers: false,
+      clientEntries: [{ name: "public", sourceFile: publicEntry }],
+      _buildBundle: async () => ({ js: "// PUBLIC-BUNDLE", map: "" }),
+      hostDispatch: async (_req, deps) => {
+        const result = await deps.systemQuery("dev-server-probe:query:ping", {}, TENANT_ID);
+        systemQueryPonged = (result as { pong: boolean }).pong === true; // @cast-boundary engine-payload
+        return { kind: "not-found" };
+      },
+    });
+
+    const res = await handle.fetch(new Request("http://localhost/"));
+    expect(res.status).toBe(404);
+    expect(systemQueryPonged).toBe(true);
+  });
 });
 
-// 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 () => {
+// 252/2: the dev path shares extra-routes-deps.ts with runProdApp —
+// here the analogous proof against createKumikoServer, with `wire` for the
+// registry/dispatchSystemWrite check and an entry:"signature" route for
+// the webhook dispatch.
+describe("createKumikoServer extraRoutes / wire deps", () => {
+  test("wire: 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) => {
+      extraRoutes: [
+        signatureRoute({
+          method: "POST",
+          path: "/webhook-probe",
+          entry: "signature",
+          verify: async (req) => {
+            if (req.headers["x-probe-signature"] !== "test-secret") {
+              throw new ExtraRouteRejection(401, { error: "bad-signature" });
+            }
+          },
+          handler: async (c, _verified, deps) => {
+            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);
+          },
+        }),
+      ],
+      wire: (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" }));
+    const res = await handle.fetch(
+      new Request("http://test/webhook-probe", {
+        method: "POST",
+        headers: { "x-probe-signature": "test-secret" },
+      }),
+    );
     expect(res.status).toBe(200);
     const body = (await res.json()) as {
       isSuccess: boolean;
@@ -369,9 +426,14 @@ describe("createKumikoServer — extraRoutes vs. onAfterSetup ordering", () => {
       features: [probeFeature],
       port: 0,
       installSignalHandlers: false,
-      extraRoutes: (app) => {
-        app.get("/probe", (c) => c.json({ ok: true }));
-      },
+      extraRoutes: [
+        {
+          method: "GET",
+          path: "/probe",
+          entry: "anonymous",
+          handler: (c) => c.json({ ok: true }),
+        },
+      ],
       onAfterSetup: async (stack) => {
         await stack.http.writeOk(
           "dev-server-probe:write:probe-write",

package/src/__tests__/scaffold-app.test.ts

@@ -1,7 +1,7 @@
 // scaffoldApp unit-tests (DX-1.0 + #352 deploy/schema scaffold).
 
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { afterAll, afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { type ScaffoldTestSetup, scaffoldApp } from "../scaffold-app";
@@ -380,12 +380,13 @@ describe("scaffoldApp", () => {
     expect(main).toContain("...kmsWiring,");
   });
 
-  test("src/run-config.ts mounts secrets + sessions + tasks + HAS_AUTH", async () => {
+  test("src/run-config.ts mounts secrets + auth-foundation + sessions + tasks + HAS_AUTH", async () => {
     const dest = join(tmp, "my-shop");
     await scaffoldApp({ name: "my-shop", destination: dest });
 
     const runConfig = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
     expect(runConfig).toContain("createSecretsFeature()");
+    expect(runConfig).toContain("authFoundationFeature");
     expect(runConfig).toContain("createSessionsFeature()");
     expect(runConfig).toContain("tasksFeature");
     expect(runConfig).toContain('from "./features/tasks"');
@@ -562,3 +563,56 @@ describe("scaffoldApp", () => {
     expect(uuidA).toBe(uuidB);
   });
 });
+
+// File-content assertions on run-config.ts can't catch a missing sessionStore
+// provider — only actually booting the generated bin/main.ts can.
+describe("generated default app actually boots (kumiko-framework#3120)", () => {
+  const FIXTURE_ROOT = join(import.meta.dir, ".tmp-fixtures");
+  const createdDirs: string[] = [];
+
+  afterAll(() => {
+    for (const d of createdDirs) {
+      try {
+        rmSync(d, { recursive: true, force: true });
+      } catch {
+        // ignore — best-effort
+      }
+    }
+  });
+
+  test("KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts exits 0 against the default scaffold", async () => {
+    mkdirSync(FIXTURE_ROOT, { recursive: true });
+    const cwd = mkdtempSync(join(FIXTURE_ROOT, "boot-"));
+    createdDirs.push(cwd);
+    const dest = join(cwd, "boot-fixture");
+
+    await scaffoldApp({ name: "boot-fixture", destination: dest });
+
+    const proc = Bun.spawn({
+      cmd: ["bun", "bin/main.ts"],
+      cwd: dest,
+      env: {
+        ...process.env,
+        KUMIKO_DRY_RUN_ENV: "boot",
+        JWT_SECRET: "a".repeat(32),
+        KUMIKO_SECRETS_MASTER_KEY_V1: Buffer.alloc(32, 7).toString("base64"),
+        DATABASE_URL: "postgres://dummy:dummy@127.0.0.1:1/dummy",
+        REDIS_URL: "redis://127.0.0.1:1",
+        PLATFORM_KEK: "",
+        SUBJECT_KEYS_DATABASE_URL: "",
+        KUMIKO_BLIND_INDEX_KEY: "",
+      },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+
+    expect(code, `stdout:\n${stdout}\nstderr:\n${stderr}`).toBe(0);
+    expect(`${stdout}${stderr}`).not.toContain("BOOT ABORTED");
+    expect(stdout).toContain("boot validation OK");
+  });
+});

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.299.0",
+    "type": "fix",
+    "title": "Scaffolded docker-compose.yml uses the correct Postgres 18 data path; default app mounts auth-foundation so it boots",
+    "migration": "No action needed for existing apps; only newly scaffolded apps are affected."
+  },
+  {
+    "version": "0.298.0",
+    "type": "breaking",
+    "title": "createKumikoServer/runDevApp take ExtraRouteDefinition[]; dev hostDispatch gets systemQuery",
+    "migration": "extraRoutes on createKumikoServer/runDevApp changes from (app, deps) => void to readonly ExtraRouteDefinition[] - see the framework core changelog entry for the route-kind/dep breakdown. wire?: (deps: SystemWireDeps) => void | Promise<void> replaces non-route setup previously done inside the old extraRoutes callback. The dev hostDispatch callback now receives a second argument { systemQuery }; a dispatch implementation reading the dev db directly switches to systemQuery."
+  },
   {
     "version": "0.291.0",
     "type": "fix",

package/src/create-kumiko-server.ts

@@ -23,6 +23,7 @@ import { resolveAnonymousAccessFromRegistry } from "@cosmicdrift/kumiko-bundled-
 import {
   type AuthRoutesConfig,
   buildRequestContextDataFromRequest,
+  type ExtraRouteDefinition,
   generateToken,
   requestContext,
 } from "@cosmicdrift/kumiko-framework/api";
@@ -47,8 +48,8 @@ import {
 import { startDevJobRunners } from "@cosmicdrift/kumiko-server-runtime/boot/job-run-logger";
 import { buildBunServeOptions } from "@cosmicdrift/kumiko-server-runtime/bun-serve-options";
 import {
-  type ExtraRoutesSystemDeps,
   makeDispatchSystemWrite,
+  type SystemWireDeps,
 } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
 import { injectSchema } from "@cosmicdrift/kumiko-server-runtime/inject-schema";
 import {
@@ -127,7 +128,10 @@ export type DevHostDispatchResult =
 
 /** Picks an entry by inspecting the incoming request. Wird von
  *  Multi-Entry-Apps gesetzt; im Single-Entry-Mode irrelevant. */
-export type DevHostDispatch = (req: Request) => DevHostDispatchResult;
+export type DevHostDispatch = (
+  req: Request,
+  deps: { readonly systemQuery: PageHeadSystemQuery },
+) => DevHostDispatchResult | Promise<DevHostDispatchResult>;
 
 export type CreateKumikoServerOptions = {
   /** Features whose entities, handlers, and screens get wired into the
@@ -217,12 +221,15 @@ export type CreateKumikoServerOptions = {
    *  tenant, …). Muss idempotent sein — im persistent-DB-Modus läuft
    *  es bei jedem Boot. */
   readonly onAfterSetup?: (stack: TestStack) => Promise<void>;
-  /** Mount-Point für app-eigene HTTP-Routes außerhalb des Dispatcher-
-   *  Systems — symmetrisch zum runProdApp.extraRoutes. Wird VOR der
-   *  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: ExtraRoutesSystemDeps) => void;
+  /** Declarative HTTP-routes outside the /api/write|query|batch pipeline —
+   *  symmetric to runProdApp.extraRoutes (kumiko-framework#3050). Mounted
+   *  inside buildServer (setupTestStack), before the Static/HTML-fallback,
+   *  so an own GET (/feed.xml, /og-image, …) wins over the dev-asset path. */
+  readonly extraRoutes?: readonly ExtraRouteDefinition[];
+  /** Hook for app-wired co-running components that need the system-write
+   *  dispatcher — runs after buildServer, before onAfterSetup (seeds), with
+   *  NO `app` (routes are declared via `extraRoutes`, not wired here). */
+  readonly wire?: (deps: SystemWireDeps) => void | Promise<void>;
   /** Per-request head-metadata resolver (Open-Graph/title/description) —
    *  same option, same `PageHeadResolver` signature, and same shared
    *  resolve+inject call (`resolveAndInjectPageHead`) as `runProdApp`'s
@@ -830,6 +837,7 @@ export async function createKumikoServer(
     ...(options.effectiveFeatures !== undefined && {
       effectiveFeatures: options.effectiveFeatures,
     }),
+    ...(options.extraRoutes !== undefined && { extraRoutes: options.extraRoutes }),
     // jobs: {} = enqueuer-only; startDevJobRunners below is the sole
     // consumer/cron-scheduler per lane, so runOnBoot/cron jobs don't double-fire.
     jobs: {},
@@ -837,16 +845,12 @@ export async function createKumikoServer(
   await createEventsTable(stack.db);
   await pushEntityProjectionTables(stack, stack.registry);
 
-  // App-eigene HTTP-Routes ans Hono-app hängen — symmetrisch zur
-  // gleichnamigen Option in runProdApp. Wird vor dem dev-fallback
-  // (HTML/JS/CSS-Serving via handleFetch unten) registriert, damit
-  // explizite Routen wie /feed.xml den Asset-Pfad schlagen.
-  //
-  // Muss VOR dem Seed laufen: ein Seed, der über stack.http dispatcht,
-  // baut Honos Matcher — danach wirft jedes weitere app.get() mit
-  // "Can not add a route since the matcher is already built".
-  if (options.extraRoutes !== undefined) {
-    options.extraRoutes(stack.app, {
+  // `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.
@@ -861,8 +865,6 @@ export async function createKumikoServer(
   // 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).
-  // Dispatching through stack.http below builds Hono's matcher — no route
-  // may be registered after this point (see extraRoutes above).
   if (options.onAfterSetup !== undefined) {
     await options.onAfterSetup(stack);
   }
@@ -943,6 +945,15 @@ export async function createKumikoServer(
   // ist es immer "client" mit Schema-Inject true (Single-Entry-Default
   // damit der Client TypeScript-Schemas findet).
   //
+  // Anonymous-role systemQuery, shared by resolvePageHead and hostDispatch —
+  // mirrors runProdApp's HostDispatchFn deps so dev/prod stay symmetric.
+  const buildDevSystemQuery =
+    (req: Request): PageHeadSystemQuery =>
+    (type, payload, tenantId) =>
+      requestContext.run(requestContext.get() ?? buildRequestContextDataFromRequest(req), () =>
+        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).
@@ -966,14 +977,10 @@ export async function createKumikoServer(
     if (options.resolvePageHead !== undefined) {
       const url = new URL(req.url);
       const host = req.headers.get("host") ?? url.host;
-      const systemQuery: PageHeadSystemQuery = (type, payload, tenantId) =>
-        requestContext.run(requestContext.get() ?? buildRequestContextDataFromRequest(req), () =>
-          stack.dispatcher.query(type, payload, createAnonymousUser(tenantId)),
-        );
       html = await resolveAndInjectPageHead(html, options.resolvePageHead, {
         path: url.pathname,
         host,
-        systemQuery,
+        systemQuery: buildDevSystemQuery(req),
       });
     }
     return new Response(html, { headers });
@@ -1085,7 +1092,7 @@ export async function createKumikoServer(
       // Discriminated-Dispatch — symmetric zu prod. Ohne hostDispatch
       // landet das im Single-Entry-Default ("client" + Schema-Inject).
       if (options.hostDispatch !== undefined) {
-        const dispatch = options.hostDispatch(req);
+        const dispatch = await options.hostDispatch(req, { systemQuery: buildDevSystemQuery(req) });
         if (dispatch.kind === "redirect") {
           return new Response(null, {
             status: dispatch.status ?? 302,

package/src/run-dev-app.ts

@@ -251,6 +251,9 @@ export type RunDevAppOptions = {
    *  Hono-app gehängt, läuft VOR dem static-asset-Pfad. Symmetrisch zur
    *  gleichnamigen Option in runProdApp. */
   readonly extraRoutes?: CreateKumikoServerOptions["extraRoutes"];
+  /** Hook for app-wired co-running components — symmetric to
+   *  runProdApp.wire (kumiko-framework#3050). */
+  readonly wire?: CreateKumikoServerOptions["wire"];
   /** Feature-toggle resolver — durchgereicht an createKumikoServer →
    *  setupTestStack. Sprint-8 Tier-Composition: per-Tenant unterschied-
    *  liche features aktiv via globalFeatureToggleRuntime. Pattern in
@@ -486,6 +489,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(options.anonymousAccess !== undefined && { anonymousAccess: options.anonymousAccess }),
     ...(options.files !== undefined && { files: options.files }),
     ...(options.extraRoutes !== undefined && { extraRoutes: options.extraRoutes }),
+    ...(options.wire !== undefined && { wire: options.wire }),
     ...(finalEffectiveFeatures !== undefined && {
       effectiveFeatures: finalEffectiveFeatures,
     }),

package/src/scaffold-app.ts

@@ -72,7 +72,7 @@ export type ScaffoldAppOptions = {
   readonly cwd?: string;
   /** npm-version-pin for @cosmicdrift/* deps. Default "*" for latest. */
   readonly frameworkVersion?: string;
-  /** Bundled-features to mount in run-config.ts. Default: secrets + sessions
+  /** Bundled-features to mount in run-config.ts. Default: secrets + auth-foundation + sessions
    *  (the historical foundation). create-kumiko-app passes the picker output
    *  here so the generated APP_FEATURES reflects the user's selection. */
   readonly features?: ReadonlyArray<ScaffoldFeatureEntry>;
@@ -386,6 +386,13 @@ const FOUNDATION_FEATURES: ReadonlyArray<ScaffoldFeatureEntry> = [
     exportName: "createSecretsFeature",
     callExpression: "createSecretsFeature()",
   },
+  // sessions' `sessionStore` extension requires auth-foundation to be mounted.
+  {
+    name: "auth-foundation",
+    importPath: "@cosmicdrift/kumiko-bundled-features/auth-foundation",
+    exportName: "authFoundationFeature",
+    callExpression: "authFoundationFeature",
+  },
   {
     name: "sessions",
     importPath: "@cosmicdrift/kumiko-bundled-features/sessions",
@@ -790,7 +797,7 @@ services:
     ports:
       - "127.0.0.1:5432:5432"
     volumes:
-      - kumiko-pg:/var/lib/postgresql/data
+      - kumiko-pg:/var/lib/postgresql
   redis:
     image: redis:7
     ports: