@cosmicdrift/kumiko-dev-server 0.288.0 → 0.290.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.288.0",
+  "version": "0.290.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,9 +59,10 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.288.0",
-    "@cosmicdrift/kumiko-framework": "0.288.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.288.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.290.0",
+    "@cosmicdrift/kumiko-framework": "0.290.0",
+    "@cosmicdrift/kumiko-headless": "0.290.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.290.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

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

@@ -509,6 +509,83 @@ describe("createKumikoServer — hot-reload broadcast", () => {
   });
 });
 
+// kumiko-framework#3026: runDevApp gains resolvePageHead parity with
+// runProdApp — both now call the same @cosmicdrift/kumiko-headless/apex
+// resolveAndInjectPageHead, so a resolver produces the same tags in the
+// same order under dev as under prod (see run-prod-app-static-files.test.ts's
+// "resolver meta → og-tags appear" case for the prod-side equivalent). The
+// real 300ms-timeout path is covered once, in headless's own unit test for
+// resolveAndInjectPageHead (same shared function) — no need to re-run a slow
+// timeout wait here too.
+describe("createKumikoServer resolvePageHead", () => {
+  test("resolver meta → head tags injected, same tags + order as runProdApp", async () => {
+    handle = await createKumikoServer({
+      features: [probeFeature],
+      port: 0,
+      installSignalHandlers: false,
+      resolvePageHead: async () => ({
+        title: "Vehicle X",
+        description: "A car",
+        ogImage: "https://x/i.png",
+      }),
+    });
+    const res = await handle.fetch(new Request("http://localhost/"));
+    expect(res.status).toBe(200);
+    const body = await res.text();
+    expect(body).not.toContain("<title>Kumiko</title>");
+    expect((body.match(/kumiko-page-head/g) ?? []).length).toBe(1);
+    expect(body).toContain("<title>Vehicle X</title>");
+    expect(body).toContain('<meta name="description" content="A car" />');
+    expect(body).toContain('<meta property="og:title" content="Vehicle X" />');
+    expect(body).toContain('<meta property="og:description" content="A car" />');
+    expect(body).toContain('<meta property="og:image" content="https://x/i.png" />');
+
+    const titleIdx = body.indexOf("<title>Vehicle X</title>");
+    const descIdx = body.indexOf('<meta name="description"');
+    const ogTitleIdx = body.indexOf('<meta property="og:title"');
+    const ogDescIdx = body.indexOf('<meta property="og:description"');
+    const ogImageIdx = body.indexOf('<meta property="og:image"');
+    expect(titleIdx).toBeLessThan(descIdx);
+    expect(descIdx).toBeLessThan(ogTitleIdx);
+    expect(ogTitleIdx).toBeLessThan(ogDescIdx);
+    expect(ogDescIdx).toBeLessThan(ogImageIdx);
+  });
+
+  test("resolver throws → 200 with the unchanged default shell, not a 500", async () => {
+    handle = await createKumikoServer({
+      features: [probeFeature],
+      port: 0,
+      installSignalHandlers: false,
+      resolvePageHead: async () => {
+        throw new Error("boom");
+      },
+    });
+    const res = await handle.fetch(new Request("http://localhost/"));
+    expect(res.status).toBe(200);
+    const body = await res.text();
+    expect(body).not.toContain("kumiko-page-head");
+    expect(body).toMatch(/<div id="root">/);
+  });
+
+  test("resolver returns null → 200 with the unchanged default shell", async () => {
+    handle = await createKumikoServer({
+      features: [probeFeature],
+      port: 0,
+      installSignalHandlers: false,
+      resolvePageHead: async () => null,
+    });
+    const res = await handle.fetch(new Request("http://localhost/"));
+    expect(res.status).toBe(200);
+    expect(await res.text()).not.toContain("kumiko-page-head");
+  });
+
+  test("no resolvePageHead configured → no page-head marker in the response", async () => {
+    const h = await boot();
+    const res = await h.fetch(new Request("http://localhost/"));
+    expect(await res.text()).not.toContain("kumiko-page-head");
+  });
+});
+
 // kumiko-framework#2435: tryHonoFirst used to decide "no route matched"
 // purely from the status code — a matched httpRoute answering 404 on
 // purpose (e.g. default-deny reads) was indistinguishable from an

package/src/changes.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "runDevApp gains resolvePageHead for dev/e2e parity with runProdApp",
+    "detail": "RunDevAppOptions/CreateKumikoServerOptions gain resolvePageHead, same PageHeadResolver signature as RunProdAppOptions. Applied to every templated HTML response (default single-entry shell and a host-dispatched \"html\" entry) via the shared @cosmicdrift/kumiko-headless/apex resolveAndInjectPageHead — same 300ms timeout, same error/null/timeout-falls-back-to-unchanged-200-shell semantics as prod (kumiko-framework#3026). The dev-only static-html hostDispatch kind (raw file passthrough, no bundle/schema injection either) is unaffected. No behavior change for apps that don't set resolvePageHead."
+  }
+]

package/src/create-kumiko-server.ts

@@ -20,8 +20,17 @@ import { readFile, realpath, watch } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { resolveAnonymousAccessFromRegistry } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
-import { type AuthRoutesConfig, generateToken } from "@cosmicdrift/kumiko-framework/api";
-import { buildAppSchema, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type AuthRoutesConfig,
+  buildRequestContextDataFromRequest,
+  generateToken,
+  requestContext,
+} from "@cosmicdrift/kumiko-framework/api";
+import {
+  buildAppSchema,
+  createAnonymousUser,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   pushEntityProjectionTables,
@@ -30,6 +39,11 @@ import {
   type TestStackOptions,
   TestUsers,
 } from "@cosmicdrift/kumiko-framework/stack";
+import {
+  type PageHeadResolver,
+  type PageHeadSystemQuery,
+  resolveAndInjectPageHead,
+} from "@cosmicdrift/kumiko-headless/apex";
 import { startDevJobRunners } from "@cosmicdrift/kumiko-server-runtime/boot/job-run-logger";
 import { buildBunServeOptions } from "@cosmicdrift/kumiko-server-runtime/bun-serve-options";
 import {
@@ -209,6 +223,16 @@ export type CreateKumikoServerOptions = {
    *  /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;
+  /** Per-request head-metadata resolver (Open-Graph/title/description) —
+   *  same option, same `PageHeadResolver` signature, and same shared
+   *  resolve+inject call (`resolveAndInjectPageHead`) as `runProdApp`'s
+   *  `resolvePageHead`, so dev and e2e exercise the exact code prod does
+   *  (kumiko-framework#3026). Consulted for every templated HTML response
+   *  (the default single-entry shell and a host-dispatched `"html"` entry),
+   *  right before it's served. On error, `null`, or a timeout, the shell
+   *  ships unchanged with status 200 — never a 500. `systemQuery` inside
+   *  the resolver runs as the anonymous role, same as prod. */
+  readonly resolvePageHead?: PageHeadResolver;
 };
 
 export type KumikoServerHandle = {
@@ -918,7 +942,15 @@ export async function createKumikoServer(
   // bestimmt nachdem er hostDispatch evaluiert hat. Ohne hostDispatch
   // ist es immer "client" mit Schema-Inject true (Single-Entry-Default
   // damit der Client TypeScript-Schemas findet).
-  const htmlResponse = async (entryName: string, doInjectSchema: boolean): Promise<Response> => {
+  //
+  // 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).
+  const htmlResponse = async (
+    entryName: string,
+    doInjectSchema: boolean,
+    req: Request,
+  ): Promise<Response> => {
     const template = htmlTemplates.get(entryName) ?? defaultTemplate;
     const headers = new Headers();
     headers.set("Content-Type", "text/html; charset=utf-8");
@@ -931,6 +963,19 @@ export async function createKumikoServer(
     let html = injectReload(template);
     if (stylesheetPath !== undefined) html = injectStylesheet(html);
     if (doInjectSchema) html = injectSchema(html, appSchemaJson);
+    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,
+      });
+    }
     return new Response(html, { headers });
   };
 
@@ -1058,9 +1103,9 @@ export async function createKumikoServer(
             headers: { "Content-Type": "text/html; charset=utf-8" },
           });
         }
-        return htmlResponse(dispatch.entryName, dispatch.injectSchema ?? true);
+        return htmlResponse(dispatch.entryName, dispatch.injectSchema ?? true, req);
       }
-      return htmlResponse("client", true);
+      return htmlResponse("client", true, req);
     }
 
     // Static assets under public/ — see tryServePublicAsset's own comment

package/src/run-dev-app.ts

@@ -45,10 +45,6 @@ import {
   SESSIONS_FEATURE,
 } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
-import {
-  resolveTenantLifecycleGate,
-  TENANT_LIFECYCLE_FEATURE,
-} from "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle";
 import type { SessionMetadata, TokenVerifier } from "@cosmicdrift/kumiko-framework/api";
 import { createInMemoryLoginRateLimiter } from "@cosmicdrift/kumiko-framework/api";
 import {
@@ -56,7 +52,6 @@ import {
   configurePiiSubjectKms,
   type KmsAdapter,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
 import {
   collectWriteHandlerQns,
@@ -74,6 +69,7 @@ import {
 import type { EnvelopeCipher, MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
 import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
+import type { PageHeadResolver } from "@cosmicdrift/kumiko-headless/apex";
 import { applyBootSeeds } from "@cosmicdrift/kumiko-server-runtime/boot/apply-boot-seeds";
 import { resolveBootCrypto } from "@cosmicdrift/kumiko-server-runtime/boot/boot-crypto";
 import {
@@ -187,6 +183,11 @@ export type RunDevAppOptions = {
    *  geforderten — sonst weiß der Server nicht welche HTML er liefern
    *  soll. */
   readonly hostDispatch?: CreateKumikoServerOptions["hostDispatch"];
+  /** Per-request head-metadata resolver — same option, same signature as
+   *  `runProdApp`'s `resolvePageHead`, so `bun dev` and every e2e that boots
+   *  through `runDevApp` show the same resolved head prod does. See
+   *  `CreateKumikoServerOptions.resolvePageHead` for the full contract. */
+  readonly resolvePageHead?: PageHeadResolver;
   /** CSS-Entry. Default: package-export `@cosmicdrift/kumiko-renderer-web/styles.css`
    *  wenn ein client-Entry gesetzt ist. `false` deaktiviert die CSS-Pipeline. */
   readonly stylesheet?: string | false;
@@ -431,10 +432,8 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // needs the real db+registry (only concrete after setupTestStack). Wired
   // whenever a provider feature (personal-access-tokens today) is mounted.
   let tokenVerifier: TokenVerifier | undefined;
-  let lifecycleDb: DbConnection | undefined;
   const patFeature = features.find((f) => f.name === PAT_FEATURE);
   const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
-  const tenantLifecycleFeature = features.find((f) => f.name === TENANT_LIFECYCLE_FEATURE);
   const patAuthFragment = patFeature
     ? {
         tokenVerifier: (rawToken: string) => {
@@ -450,18 +449,6 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
       }
     : {};
 
-  const tenantLifecycleAuthFragment = tenantLifecycleFeature
-    ? {
-        resolveTenantLifecycleStatus: async (tenantId: string) => {
-          if (!lifecycleDb) {
-            throw new Error("[runDevApp] tenant-lifecycle gate accessed before onAfterSetup");
-          }
-          const gate = await resolveTenantLifecycleGate(lifecycleDb, tenantId);
-          return gate ? { status: gate.status } : null;
-        },
-      }
-    : {};
-
   // Parity with runProdApp (#1372 review): gate on sessionStore provider, not
   // the sessions feature name — a custom provider must also wire auth
   // callbacks. sessionStoreProviderMounted computed above via the registry
@@ -482,6 +469,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(options.clientEntry !== undefined && { clientEntry: options.clientEntry }),
     ...(options.clientEntries !== undefined && { clientEntries: options.clientEntries }),
     ...(options.hostDispatch !== undefined && { hostDispatch: options.hostDispatch }),
+    ...(options.resolvePageHead !== undefined && { resolvePageHead: options.resolvePageHead }),
     ...(options.stylesheet !== undefined && { stylesheet: options.stylesheet }),
     ...(options.htmlPath !== undefined && { htmlPath: options.htmlPath }),
     ...(options.port !== undefined && { port: options.port }),
@@ -518,7 +506,6 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
         }),
         ...sessionAuthFragment,
         ...patAuthFragment,
-        ...tenantLifecycleAuthFragment,
         ...(mfaFeature && {
           mfaVerifyHandler: AuthMfaHandlers.verify,
           mfaPreauthEnableStartHandler: AuthMfaHandlers.enableStartPreauth,
@@ -558,7 +545,6 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
       },
     }),
     onAfterSetup: async (stack) => {
-      lifecycleDb = stack.db;
       // Sprint-8a: build tier-resolver BEFORE any seeds so seeds can rely
       // on the resolver being live (e.g. seed that writes a SystemAdmin's
       // tier-assignment can immediately read tier-cuts).