@cosmicdrift/kumiko-dev-server 0.55.1 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.55.1",
+  "version": "0.56.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>",
@@ -46,8 +46,8 @@
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.50.0",
-    "@cosmicdrift/kumiko-framework": "0.50.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.55.1",
+    "@cosmicdrift/kumiko-framework": "0.55.1",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/codegen/__tests__/render-codegen.test.ts

@@ -2,7 +2,12 @@ import { describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { renderDefineFile, renderInlineSchemasFile, renderTypesAugmentation } from "../render";
+import {
+  renderDefineFile,
+  renderInlineSchemasFile,
+  renderTypesAugmentation,
+  renderWriteHandlerTypes,
+} from "../render";
 import type { ScannedEvent } from "../scan-events";
 
 describe("renderTypesAugmentation", () => {
@@ -69,4 +74,19 @@ describe("renderDefineFile", () => {
     expect(out).toContain("defineWriteHandler");
     expect(out).toContain("types.generated.d.ts");
   });
+
+  test("emits createTypedDispatcher when handler QNs provided", () => {
+    const out = renderDefineFile(["tenant:write:create", "tenant:write:update"]);
+    expect(out).toContain("export type TypedDispatcher");
+    expect(out).toContain("export function createTypedDispatcher");
+    expect(out).toContain('export type { WriteHandlerQn } from "./types.generated"');
+  });
+});
+
+describe("renderWriteHandlerTypes", () => {
+  test("emits union type lines", () => {
+    const out = renderWriteHandlerTypes(["tenant:write:create"]);
+    expect(out).toContain("export type WriteHandlerQn =");
+    expect(out).toContain('| "tenant:write:create"');
+  });
 });

package/src/codegen/__tests__/run-codegen.test.ts

@@ -287,6 +287,37 @@ export default defineFeature("dup", (r) => {
     expect(w).toBeDefined();
   });
 
+  test("emits WriteHandlerQn union and TypedDispatcher when handlerQns passed", () => {
+    const appRoot = makeAppDir();
+    write(
+      appRoot,
+      "src/feature/events.ts",
+      `import { z } from "zod";\nexport const sSchema = z.object({ id: z.string() });\n`,
+    );
+    write(
+      appRoot,
+      "src/feature/feature.ts",
+      `import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { sSchema } from "./events";
+export default defineFeature("typed", (r) => {
+  r.defineEvent("only", sSchema);
+});
+`,
+    );
+
+    const result = runCodegen({
+      appRoot,
+      handlerQns: ["typed:write:create"],
+    });
+    expect(result.skipped).toBe(false);
+
+    const types = readFileSync(join(appRoot, ".kumiko", "types.generated.d.ts"), "utf-8");
+    expect(types).toContain('| "typed:write:create"');
+
+    const define = readFileSync(join(appRoot, ".kumiko", "define.ts"), "utf-8");
+    expect(define).toContain("createTypedDispatcher");
+  });
+
   test("idempotent — second run does not re-write files", () => {
     const appRoot = makeAppDir();
     write(

package/src/codegen/index.ts

@@ -2,6 +2,7 @@ export {
   renderDefineFile,
   renderInlineSchemasFile,
   renderTypesAugmentation,
+  renderWriteHandlerTypes,
 } from "./render";
 export { type CodegenOptions, type CodegenResult, runCodegen } from "./run-codegen";
 export {

package/src/codegen/render.ts

@@ -169,7 +169,35 @@ export function renderInlineSchemasFile(
  * the import back to "@cosmicdrift/kumiko-framework/engine" and you're back on the
  * loose default. Migration is reversible, no behavioural surface change.
  */
-export function renderDefineFile(): string {
+export function renderDefineFile(handlerQns: readonly string[] = []): string {
+  const typedDispatcherBlock =
+    handlerQns.length > 0
+      ? [
+          "",
+          `import type { Dispatcher, WriteOpts, WriteResult } from "@cosmicdrift/kumiko-headless";`,
+          "",
+          `export type { WriteHandlerQn } from "./types.generated";`,
+          "",
+          `/** Dispatcher with write() narrowed to registered handler QNs. */`,
+          `export type TypedDispatcher = Omit<Dispatcher, "write"> & {`,
+          `  write<TData = unknown>(`,
+          `    type: WriteHandlerQn,`,
+          `    payload: unknown,`,
+          `    opts?: WriteOpts,`,
+          `  ): Promise<WriteResult<TData>>;`,
+          `};`,
+          "",
+          `/** Wrap any Dispatcher so write() only accepts registered QNs at compile time. */`,
+          `export function createTypedDispatcher(dispatcher: Dispatcher): TypedDispatcher {`,
+          `  return {`,
+          `    ...dispatcher,`,
+          `    write: (type, payload, opts) => dispatcher.write(type, payload, opts),`,
+          `  };`,
+          `}`,
+          "",
+        ].join("\n")
+      : "";
+
   const body = [
     HEADER,
     "",
@@ -228,8 +256,26 @@ export function renderDefineFile(): string {
     `): QueryHandlerDefinition<TName, TSchema, TResult, KumikoEventTypeMap> {`,
     `  return fwDefineQueryHandler<TName, TSchema, TResult, KumikoEventTypeMap>(def);`,
     `}`,
-    "",
+    typedDispatcherBlock,
   ].join("\n");
 
   return body;
 }
+
+/**
+ * Render `WriteHandlerQn` type lines — exports a union of all registered
+ * write handler QNs so custom-screen code can type-check dispatcher.write
+ * calls at compile time:
+ *
+ *   ```ts
+ *   import type { WriteHandlerQn } from "@app/define";
+ *   dispatcher.write<WriteHandlerQn>("tenant:write:create", payload);  // ✓
+ *   dispatcher.write<WriteHandlerQn>("tenant:write:creat", payload);   // ✗ TS error
+ *   ```
+ */
+export function renderWriteHandlerTypes(handlerQns: readonly string[]): string {
+  if (handlerQns.length === 0) return "";
+
+  const lines = handlerQns.map((qn) => `  | "${qn}"`);
+  return ["", `export type WriteHandlerQn =`, ...lines, ";", ""].join("\n");
+}

package/src/codegen/run-codegen.ts

@@ -16,12 +16,22 @@
 
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { renderDefineFile, renderInlineSchemasFile, renderTypesAugmentation } from "./render";
+import {
+  renderDefineFile,
+  renderInlineSchemasFile,
+  renderTypesAugmentation,
+  renderWriteHandlerTypes,
+} from "./render";
 import { type ScanWarning, scanEvents } from "./scan-events";
 
 export type CodegenOptions = {
   /** App-Root — `<appRoot>/.kumiko/` ist der Output-Ordner. */
   readonly appRoot: string;
+  /** Optional: alle registrierten Write-Handler-QNs. Wenn nicht gesetzt,
+   *  versucht der Codegen `feature-manifest.json` im appRoot zu lesen.
+   *  Die Dev-Server-Integration übergibt die QNs direkt aus der gebooteten
+   *  Registry — CLI ruft sie aus dem Manifest. */
+  readonly handlerQns?: readonly string[];
 };
 
 export type CodegenResult = {
@@ -67,7 +77,8 @@ export function runCodegen(opts: CodegenOptions): CodegenResult {
   mkdirSync(outputDir, { recursive: true });
 
   const typesContent = renderTypesAugmentation(scan.events, outputDir);
-  const defineContent = renderDefineFile();
+  const handlerQns = opts.handlerQns ?? readHandlerQnsFromManifest(opts.appRoot);
+  const defineContent = renderDefineFile(handlerQns);
   const schemasContent = renderInlineSchemasFile(scan.events, opts.appRoot);
   // package.json — turns `.kumiko/` into a real installable package
   // named `@app/define`. Apps that declare
@@ -77,7 +88,13 @@ export function runCodegen(opts: CodegenOptions): CodegenResult {
   // is required — yarn classic v1 ignored deps in versionless workspaces.
   const packageJsonContent = renderKumikoPackageJson();
 
-  const didWriteTypes = writeIfChanged(typesPath, typesContent);
+  // WriteHandlerQn-Union an den types-Content anhängen (optional). Der
+  // Dev-Server übergibt handlerQns aus der lebenden Registry (genauer);
+  // der CLI-Fallback liest das feature-manifest.json falls vorhanden.
+  const finalTypesContent =
+    handlerQns.length > 0 ? `${typesContent}${renderWriteHandlerTypes(handlerQns)}` : typesContent;
+
+  const didWriteTypes = writeIfChanged(typesPath, finalTypesContent);
   const didWriteDefine = writeIfChanged(definePath, defineContent);
   writeIfChanged(packageJsonPath, packageJsonContent);
   const didWriteSchemas =
@@ -155,3 +172,27 @@ function removeIfExists(path: string): boolean {
   rmSync(path, { force: true });
   return true;
 }
+
+/**
+ * Fallback: liest `feature-manifest.json` aus dem appRoot und extrahiert
+ * alle Write-Handler-QNs. Fehlende/stale Manifeste sind kein Fehler —
+ * dann wird schlicht keine `WriteHandlerQn`-Union generiert (CLI ohne
+ * Manifest oder CI-Setup ohne Manifest-Generator).
+ */
+function readHandlerQnsFromManifest(appRoot: string): readonly string[] {
+  try {
+    const manifestPath = join(appRoot, "feature-manifest.json");
+    const raw = readFileSync(manifestPath, "utf-8");
+    const manifest = JSON.parse(raw) as {
+      readonly features: ReadonlyArray<{ readonly writeHandlers?: readonly string[] }>;
+    };
+    const qns: string[] = [];
+    for (const f of manifest.features) {
+      if (f.writeHandlers) qns.push(...f.writeHandlers);
+    }
+    qns.sort();
+    return qns;
+  } catch {
+    return [];
+  }
+}

package/src/codegen/watch.ts

@@ -21,6 +21,12 @@ import { runCodegen } from "./run-codegen";
 export type WatchOptions = {
   /** App-Wurzel — gleiche Bedeutung wie für `runCodegen`. */
   readonly appRoot: string;
+  /** Optional: alle registrierten Write-Handler-QNs. Durchgereicht an
+   *  `runCodegen` für die Generierung der `WriteHandlerQn`-Union.
+   *  Der Dev-Server extrahiert sie beim Boot aus den Features und
+   *  reicht sie hier rein — der Watcher reicht sie bei jedem Re-Run
+   *  an `runCodegen` weiter, damit der generated-Type nicht verschwindet. */
+  readonly handlerQns?: readonly string[];
   /** Wartet diese Millisekunden zusätzliche Events ab, bevor codegen
    *  einmal fährt. 50ms catched typische save-bursts (Editor-Saves
    *  feuern oft 2-3 Events: temp-file → rename → cleanup), bleibt aber
@@ -58,7 +64,10 @@ export function watchAndRegenerate(opts: WatchOptions): WatchHandle {
 
   const fire = () => {
     try {
-      const result = runCodegen({ appRoot: opts.appRoot });
+      const result = runCodegen({
+        appRoot: opts.appRoot,
+        ...(opts.handlerQns !== undefined && { handlerQns: opts.handlerQns }),
+      });
       if (opts.onResult) {
         opts.onResult(result);
       } else {

package/src/create-kumiko-server.ts

@@ -48,11 +48,11 @@ const hasBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
 // and only resolve the type when Bun is actually around.
 type BunServer = typeof Bun extends undefined ? unknown : ReturnType<typeof Bun.serve>;
 
-// biome-ignore lint/suspicious/noConsole: dev-server status logging
 // @wrapper-known semantic-alias
+// biome-ignore lint/suspicious/noConsole: dev-server status logging
 const logInfo = (msg: string): void => console.log(msg);
-// biome-ignore lint/suspicious/noConsole: dev-server error logging
 // @wrapper-known semantic-alias
+// biome-ignore lint/suspicious/noConsole: dev-server error logging
 const logError = (...args: unknown[]): void => console.error(...args);
 
 /** Multi-Entry-Mode für Apps die mehrere getrennte Bundles ausliefern

package/src/run-dev-app.ts

@@ -29,6 +29,7 @@ import {
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import type { SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
 import {
+  collectWriteHandlerQns,
   createRegistry,
   type EffectiveFeaturesResolver,
   type FeatureDefinition,
@@ -37,6 +38,7 @@ import {
   type SessionUser,
   type TenantId,
   type TierResolverPlugin,
+  validateAppCustomScreenWriteQns,
   validateBoot,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
@@ -191,6 +193,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // CrashLoopBackOff sterben ließ (#359). Wirft synchron, bevor ein
   // Socket oder Watcher (codegen-Write) aufgeht.
   validateBoot(features);
+  validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
 
   // Codegen + File-Watcher — schreibt `<appRoot>/.kumiko/types.generated.d.ts`
   // + `define.ts` aus den r.defineEvent-Aufrufen der App, einmal beim
@@ -202,7 +205,11 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // Watcher läuft solange der Dev-Server lebt; close() bei Shutdown
   // wird über das createKumikoServer-Handle implizit erledigt (Bun's
   // process-exit räumt fs.watch-handles auf).
-  watchAndRegenerate({ appRoot: process.cwd() });
+  // Sammelt alle Write-Handler-QNs für den Codegen — damit
+  // `types.generated.d.ts` eine `WriteHandlerQn`-Union exportieren
+  // kann, die dispatcher.write-Aufrufe client-seitig typisiert.
+  const handlerQns = collectWriteHandlerQns(features);
+  watchAndRegenerate({ appRoot: process.cwd(), handlerQns: [...handlerQns] });
 
   // Sprint-8a Tier-Composition auto-wire: scan features for a
   // tenantTierResolver-extension. If found AND user didn't supply own

package/src/run-prod-app.ts

@@ -47,12 +47,14 @@ import { createSseBroker, type SseBroker } from "@cosmicdrift/kumiko-framework/a
 import { createDbConnection, type DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import {
   buildAppSchema,
+  collectWriteHandlerQns,
   createRegistry,
   type EffectiveFeaturesResolver,
   type FeatureDefinition,
   findTierResolverUsage,
   type TenantId,
   type TierResolverPlugin,
+  validateAppCustomScreenWriteQns,
   validateBoot,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -592,6 +594,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   });
 
   validateBoot(features);
+  validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
   const registry = createRegistry(features);
 
   // C1 boot-mode exit: validators ran + registry built; no DB/Redis client