@cosmicdrift/kumiko-dev-server 0.247.0 → 0.249.0

package/bin/kumiko-build.ts

@@ -26,7 +26,7 @@ import {
   formatServerBuildResult,
   readExtraRuntimeExternals,
 } from "../src/build";
-import { runCodegen } from "../src/codegen";
+import { formatScanWarning, runCodegen } from "../src/codegen";
 
 const explicit = process.argv[2];
 const cwd = explicit ? resolve(process.cwd(), explicit) : process.cwd();
@@ -61,7 +61,7 @@ try {
   if (cgResult.warnings.length > 0) {
     for (const w of cgResult.warnings) {
       // biome-ignore lint/suspicious/noConsole: CLI-Output
-      console.warn(`${yellow}!${reset} [codegen] ${w.file}:${w.line} — ${w.reason}`);
+      console.warn(`${yellow}!${reset} [codegen] ${formatScanWarning(w)}`);
     }
   }
 

package/package.json

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

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

@@ -57,7 +57,8 @@ export const myFeature = defineFeature("myFeat", (r) => {
 `,
     );
 
-    const result = runCodegen({ appRoot });
+    // handlerQns: [] opts out of the #2757 manifest-fallback warning — out of scope here.
+    const result = runCodegen({ appRoot, handlerQns: [] });
 
     expect(result.eventCount).toBe(1);
     expect(result.warnings).toEqual([]);
@@ -122,7 +123,7 @@ export const myFeature = defineFeature("inlineFeat", (r) => {
 `,
     );
 
-    const result = runCodegen({ appRoot });
+    const result = runCodegen({ appRoot, handlerQns: [] });
     expect(result.eventCount).toBe(1);
     expect(result.warnings).toEqual([]);
     expect(result.didWriteSchemas).toBe(true);
@@ -169,7 +170,7 @@ export const myFeature = defineFeature("billing", (r) => {
 `,
     );
 
-    const result = runCodegen({ appRoot });
+    const result = runCodegen({ appRoot, handlerQns: [] });
     expect(result.eventCount).toBe(2);
     expect(result.warnings).toEqual([]);
 
@@ -201,7 +202,7 @@ export const myFeature = defineFeature("billing", (r) => {
 `,
     );
 
-    const result = runCodegen({ appRoot });
+    const result = runCodegen({ appRoot, handlerQns: [] });
     expect(result.eventCount).toBe(1);
     expect(result.warnings).toEqual([]);
     expect(result.didWriteSchemas).toBe(true);
@@ -522,4 +523,143 @@ export default defineFeature("pkgjson", (r) => {
       },
     });
   });
+
+  // #2757 — `kumiko-build` runs `runCodegen({ appRoot })` with no
+  // `handlerQns`. Without a `feature-manifest.json` that falls back to
+  // an empty list, which used to mean "render types.generated.d.ts and
+  // define.ts as if there were no write handlers at all" — silently
+  // deleting an already-checked-in WriteHandlerQn union / TypedDispatcher
+  // that a previous dev-server run had generated from the real registry.
+  describe("preserving the handler-derived block when handlerQns is omitted (#2757)", () => {
+    function writeSingleEventFeature(appRoot: string): void {
+      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("app", (r) => {
+  r.defineEvent("only", sSchema);
+});
+`,
+      );
+    }
+
+    test("a block generated with handlerQns survives a later run without handlerQns", () => {
+      const appRoot = makeAppDir();
+      writeSingleEventFeature(appRoot);
+
+      runCodegen({ appRoot, handlerQns: ["app:write:create"] });
+      const typesPath = join(appRoot, ".kumiko", "types.generated.d.ts");
+      const definePath = join(appRoot, ".kumiko", "define.ts");
+      expect(readFileSync(typesPath, "utf-8")).toContain('| "app:write:create"');
+      expect(readFileSync(definePath, "utf-8")).toContain("createTypedDispatcher");
+
+      // No feature-manifest.json in appRoot — this is the kumiko-build path.
+      const result = runCodegen({ appRoot });
+
+      expect(readFileSync(typesPath, "utf-8")).toContain('| "app:write:create"');
+      expect(readFileSync(definePath, "utf-8")).toContain("createTypedDispatcher");
+      expect(result.warnings.some((w) => w.message.includes("feature-manifest.json"))).toBe(true);
+      // Round-trip is byte-identical, not just "still contains the QN" — writeIfChanged
+      // must see no diff once the preserved block is reattached.
+      expect(result.didWriteTypes).toBe(false);
+      expect(result.didWriteDefine).toBe(false);
+    });
+
+    test("a block from a pre-#2757 file (no marker) survives a run without handlerQns", () => {
+      const appRoot = makeAppDir();
+      writeSingleEventFeature(appRoot);
+      // Legacy shape: what the released renderer wrote before markers existed.
+      write(
+        appRoot,
+        ".kumiko/types.generated.d.ts",
+        `export {};\n\nexport type WriteHandlerQn =\n  | "app:write:legacy"\n;\n`,
+      );
+      write(
+        appRoot,
+        ".kumiko/define.ts",
+        `export function defineQueryHandler() {}\n\nimport type { Dispatcher, WriteOpts, WriteResult } from "@cosmicdrift/kumiko-headless";\nexport function createTypedDispatcher() {}\n`,
+      );
+
+      const result = runCodegen({ appRoot });
+
+      expect(readFileSync(join(appRoot, ".kumiko", "types.generated.d.ts"), "utf-8")).toContain(
+        '| "app:write:legacy"',
+      );
+      expect(readFileSync(join(appRoot, ".kumiko", "define.ts"), "utf-8")).toContain(
+        "createTypedDispatcher",
+      );
+      expect(result.warnings.some((w) => w.message.includes("feature-manifest.json"))).toBe(true);
+    });
+
+    test("no handlerQns and no prior generated file → no block, no crash", () => {
+      const appRoot = makeAppDir();
+      writeSingleEventFeature(appRoot);
+
+      const result = runCodegen({ appRoot });
+
+      const typesPath = join(appRoot, ".kumiko", "types.generated.d.ts");
+      const definePath = join(appRoot, ".kumiko", "define.ts");
+      expect(readFileSync(typesPath, "utf-8")).not.toContain("WriteHandlerQn");
+      expect(readFileSync(definePath, "utf-8")).not.toContain("TypedDispatcher");
+      expect(result.skipped).toBe(false);
+    });
+
+    test("a preserved block is not duplicated across repeated runs without handlerQns", () => {
+      const appRoot = makeAppDir();
+      writeSingleEventFeature(appRoot);
+
+      runCodegen({ appRoot, handlerQns: ["app:write:create"] });
+      runCodegen({ appRoot });
+      runCodegen({ appRoot });
+
+      const typesPath = join(appRoot, ".kumiko", "types.generated.d.ts");
+      const definePath = join(appRoot, ".kumiko", "define.ts");
+      const typesOccurrences =
+        readFileSync(typesPath, "utf-8").split("app:write:create").length - 1;
+      const defineOccurrences =
+        readFileSync(definePath, "utf-8").split("createTypedDispatcher").length - 1;
+      expect(typesOccurrences).toBe(1);
+      expect(defineOccurrences).toBe(1);
+    });
+
+    test("a later run with handlerQns overwrites a preserved stale block", () => {
+      const appRoot = makeAppDir();
+      writeSingleEventFeature(appRoot);
+
+      runCodegen({ appRoot, handlerQns: ["app:write:create"] });
+      runCodegen({ appRoot }); // preserves app:write:create
+      runCodegen({ appRoot, handlerQns: ["app:write:update"] });
+
+      const typesPath = join(appRoot, ".kumiko", "types.generated.d.ts");
+      const typesContent = readFileSync(typesPath, "utf-8");
+      expect(typesContent).toContain('| "app:write:update"');
+      expect(typesContent).not.toContain("app:write:create");
+    });
+
+    test("the missing-manifest warning appears only when handlerQns is omitted", () => {
+      const appRoot = makeAppDir();
+      writeSingleEventFeature(appRoot);
+
+      const withoutOption = runCodegen({ appRoot });
+      expect(withoutOption.warnings.some((w) => w.message.includes("feature-manifest.json"))).toBe(
+        true,
+      );
+
+      const explicitEmpty = runCodegen({ appRoot, handlerQns: [] });
+      expect(explicitEmpty.warnings.some((w) => w.message.includes("feature-manifest.json"))).toBe(
+        false,
+      );
+
+      const explicitList = runCodegen({ appRoot, handlerQns: ["app:write:create"] });
+      expect(explicitList.warnings.some((w) => w.message.includes("feature-manifest.json"))).toBe(
+        false,
+      );
+    });
+  });
 });

package/src/codegen/index.ts

@@ -6,6 +6,7 @@ export {
 } from "./render";
 export { type CodegenOptions, type CodegenResult, runCodegen } from "./run-codegen";
 export {
+  formatScanWarning,
   qualifiedNameToConstName,
   rewriteImportPath,
   type ScannedEvent,

package/src/codegen/render.ts

@@ -26,11 +26,24 @@ import { basename, relative } from "node:path";
 import type { ScannedEvent } from "./scan-events";
 import { rewriteImportPath } from "./scan-events";
 
+/**
+ * Start-of-block markers for the two handler-derived sections that
+ * `run-codegen.ts` may need to carry forward verbatim from a previous
+ * run (when the current run has no `handlerQns` to render a fresh
+ * block from). Each marker is always the last thing its renderer
+ * emits, so a caller can locate it in a previously-written file and
+ * slice from the marker to EOF to recover the whole block.
+ */
+export const WRITE_HANDLER_QN_MARKER =
+  "// --- WriteHandlerQn (generated from live registry / feature-manifest.json) ---";
+export const TYPED_DISPATCHER_MARKER =
+  "// --- TypedDispatcher (generated from live registry / feature-manifest.json) ---";
+
 const HEADER = [
   "// =====================================================================",
   "// AUTO-GENERATED — DO NOT EDIT BY HAND",
-  "// Run `bun kumiko codegen` to regenerate (or rely on the dev-server's",
-  "// file-watcher, which calls it on every r.defineEvent change).",
+  "// Regenerated by `bun run build` (kumiko-build) or by the dev-server's",
+  "// file-watcher, which runs codegen on every r.defineEvent change.",
   "// =====================================================================",
 ].join("\n");
 
@@ -129,8 +142,9 @@ export function renderInlineSchemasFile(
     "// Schema extracts purely for type inference: this file is referenced",
     "// from types.generated.d.ts via `import type`. ts-strip elides it at",
     "// build time, so there is NO runtime duplication of the inline schemas",
-    "// in feature files. When an event schema changes: re-run `bun kumiko",
-    "// codegen` — otherwise the z.infer type drifts from the runtime schema.",
+    "// in feature files. When an event schema changes: rebuild (`bun run",
+    "// build`) or let the dev-server regenerate it — otherwise the z.infer",
+    "// type drifts from the runtime schema.",
     "",
     `import { z } from "zod";`,
     "",
@@ -174,6 +188,7 @@ export function renderDefineFile(handlerQns: readonly string[] = []): string {
     handlerQns.length > 0
       ? [
           "",
+          TYPED_DISPATCHER_MARKER,
           `import type { Dispatcher, WriteOpts, WriteResult } from "@cosmicdrift/kumiko-headless";`,
           `import type { WriteHandlerQn } from "./types.generated";`,
           "",
@@ -282,5 +297,7 @@ 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");
+  return ["", WRITE_HANDLER_QN_MARKER, `export type WriteHandlerQn =`, ...lines, ";", ""].join(
+    "\n",
+  );
 }

package/src/codegen/run-codegen.ts

@@ -1,6 +1,6 @@
-// runCodegen — Top-Level Entry-Point. Wird vom Dev-Server (auf Boot),
-// vom Build-Step (vor Bundle) und von der CLI (`bun kumiko codegen`)
-// aufgerufen.
+// runCodegen — top-level entry point. Called by the dev-server (on boot,
+// then on every watched file-change) and by `kumiko-build` (before
+// bundling).
 //
 // Lifecycle:
 //   1. Scan `<appRoot>/src/**` nach r.defineEvent.
@@ -21,6 +21,8 @@ import {
   renderInlineSchemasFile,
   renderTypesAugmentation,
   renderWriteHandlerTypes,
+  TYPED_DISPATCHER_MARKER,
+  WRITE_HANDLER_QN_MARKER,
 } from "./render";
 import { type ScanWarning, scanEvents } from "./scan-events";
 
@@ -77,7 +79,15 @@ export function runCodegen(opts: CodegenOptions): CodegenResult {
   mkdirSync(outputDir, { recursive: true });
 
   const typesContent = renderTypesAugmentation(scan.events, outputDir);
+  // `opts.handlerQns` undefined means the caller (kumiko-build) has no
+  // live feature registry to draw from and relies on the manifest
+  // fallback. That fallback can't tell "no handlers exist" apart from
+  // "the manifest doesn't exist" — both come back as an empty array —
+  // so an empty result here is a known-lossy read, not authoritative
+  // data the way run-dev-app's live registry is.
+  const usingManifestFallback = opts.handlerQns === undefined;
   const handlerQns = opts.handlerQns ?? readHandlerQnsFromManifest(opts.appRoot);
+  const hasHandlerQns = handlerQns.length > 0;
   const defineContent = renderDefineFile(handlerQns);
   const schemasContent = renderInlineSchemasFile(scan.events, opts.appRoot);
   // package.json — turns `.kumiko/` into a real installable package
@@ -91,21 +101,53 @@ export function runCodegen(opts: CodegenOptions): CodegenResult {
   // 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;
+  //
+  // Preserve only applies to the manifest-fallback path: a caller that
+  // explicitly passes `handlerQns: []` (the dev-server, when an app
+  // truly registers zero write handlers) means it — that's real data,
+  // not a missing-manifest gap, so it clears the block like before.
+  // Only the manifest fallback coming back empty is ambiguous enough to
+  // warrant carrying the previous block forward instead of dropping it.
+  const shouldPreserveStaleBlock = !hasHandlerQns && usingManifestFallback;
+  const finalTypesContent = shouldPreserveStaleBlock
+    ? withPreservedBlock(
+        typesContent,
+        typesPath,
+        WRITE_HANDLER_QN_MARKER,
+        LEGACY_WRITE_HANDLER_QN_ANCHOR,
+      )
+    : `${typesContent}${renderWriteHandlerTypes(handlerQns)}`;
+  const finalDefineContent = shouldPreserveStaleBlock
+    ? withPreservedBlock(
+        defineContent,
+        definePath,
+        TYPED_DISPATCHER_MARKER,
+        LEGACY_TYPED_DISPATCHER_ANCHOR,
+      )
+    : defineContent;
 
   const didWriteTypes = writeIfChanged(typesPath, finalTypesContent);
-  const didWriteDefine = writeIfChanged(definePath, defineContent);
+  const didWriteDefine = writeIfChanged(definePath, finalDefineContent);
   writeIfChanged(packageJsonPath, packageJsonContent);
   const didWriteSchemas =
     schemasContent !== undefined
       ? writeIfChanged(schemasPath, schemasContent)
       : removeIfExists(schemasPath);
 
+  const warnings: readonly ScanWarning[] = shouldPreserveStaleBlock
+    ? [
+        ...scan.warnings,
+        {
+          message:
+            "No feature-manifest.json found — the WriteHandlerQn/TypedDispatcher block could not be determined from here; run the dev-server to get the exact handler list.",
+        },
+      ]
+    : scan.warnings;
+
   return {
     outputDir,
     eventCount: scan.events.length,
-    warnings: scan.warnings,
+    warnings,
     didWriteTypes,
     didWriteSchemas,
     didWriteDefine,
@@ -151,17 +193,55 @@ function renderKumikoPackageJson(): string {
  * happen on every mtime change).
  */
 function writeIfChanged(path: string, content: string): boolean {
-  let existing: string | undefined;
-  try {
-    existing = readFileSync(path, "utf-8");
-  } catch {
-    existing = undefined;
-  }
+  const existing = readExistingOrUndefined(path);
   if (existing === content) return false;
   writeFileSync(path, content, "utf-8");
   return true;
 }
 
+function readExistingOrUndefined(path: string): string | undefined {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+// Pre-marker renderer output has no WRITE_HANDLER_QN_MARKER/TYPED_DISPATCHER_MARKER
+// line to find — a file generated before this fix still needs to round-trip.
+// Each anchor is the first line of its block under the old renderer, so slicing
+// from the preceding newline recovers the same block the marker path recovers.
+const LEGACY_WRITE_HANDLER_QN_ANCHOR = `export type WriteHandlerQn =`;
+const LEGACY_TYPED_DISPATCHER_ANCHOR = `import type { Dispatcher, WriteOpts, WriteResult } from "@cosmicdrift/kumiko-headless";`;
+
+/**
+ * Appends whichever handler-derived block a previous run left behind
+ * in `existingPath`, found via its start-of-block `marker` (or, for a
+ * file generated before markers existed, `legacyAnchor`). Used when
+ * the current run has no `handlerQns` of its own — the block can't be
+ * re-derived, so the only options are "delete it" (the #2757 bug) or
+ * "leave it exactly as it was". The marker is always emitted as the
+ * last thing its renderer produces, so slicing from it to EOF recovers
+ * the whole block regardless of how many times this preserve-path runs
+ * in a row.
+ */
+function withPreservedBlock(
+  freshContent: string,
+  existingPath: string,
+  marker: string,
+  legacyAnchor: string,
+): string {
+  const existing = readExistingOrUndefined(existingPath);
+  const preserved = extractBlock(existing, marker) ?? extractBlock(existing, legacyAnchor);
+  return preserved !== undefined ? `${freshContent}${preserved}` : freshContent;
+}
+
+function extractBlock(content: string | undefined, anchor: string): string | undefined {
+  if (content === undefined) return undefined;
+  const idx = content.indexOf(`\n${anchor}`);
+  return idx === -1 ? undefined : content.slice(idx);
+}
+
 /**
  * Remove a previously-generated file when the latest scan no longer
  * produces it (e.g. the last inline-schema was refactored to a named

package/src/codegen/scan-events.ts

@@ -91,8 +91,10 @@ export type SchemaSource =
     };
 
 export type ScanWarning = {
-  readonly file: string;
-  readonly line: number;
+  /** Absent for warnings that aren't tied to a scanned source line
+   *  (e.g. a codegen-level warning about a missing manifest file). */
+  readonly file?: string;
+  readonly line?: number;
   readonly message: string;
 };
 
@@ -101,6 +103,13 @@ export type ScanResult = {
   readonly warnings: readonly ScanWarning[];
 };
 
+/** Renders a `ScanWarning` for terminal output; omits the location prefix when the warning has no source line. */
+export function formatScanWarning(warning: ScanWarning): string {
+  return warning.file !== undefined
+    ? `${warning.file}:${warning.line} — ${warning.message}`
+    : warning.message;
+}
+
 export type ScanOptions = {
   /** App-Wurzel — alles unter `<root>/src` wird gescannt. Tests +
    *  generated-files (`.kumiko`, `dist*`, `node_modules`) sind raus. */

package/src/codegen/watch.ts

@@ -17,6 +17,7 @@
 import { type FSWatcher, watch } from "node:fs";
 import { join } from "node:path";
 import { runCodegen } from "./run-codegen";
+import { formatScanWarning } from "./scan-events";
 
 export type WatchOptions = {
   /** App-Wurzel — gleiche Bedeutung wie für `runCodegen`. */
@@ -74,7 +75,7 @@ export function watchAndRegenerate(opts: WatchOptions): WatchHandle {
         if (result.warnings.length > 0) {
           for (const w of result.warnings) {
             // biome-ignore lint/suspicious/noConsole: codegen-watcher logs to terminal
-            console.warn(`[codegen] ${w.file}:${w.line} — ${w.message}`);
+            console.warn(`[codegen] ${formatScanWarning(w)}`);
           }
         }
       }