@cosmicdrift/kumiko-dev-server 0.288.0 → 0.289.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.288.0",
+  "version": "0.289.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.289.0",
+    "@cosmicdrift/kumiko-framework": "0.289.0",
+    "@cosmicdrift/kumiko-headless": "0.289.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.289.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

@@ -74,6 +74,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 +188,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;
@@ -482,6 +488,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 }),