@cosmicdrift/kumiko-framework 0.55.1 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.55.1",
+  "version": "0.56.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,8 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.50.0",
-    "@types/uuid": "^11.0.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.55.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/queries/seed-context.ts

@@ -51,7 +51,7 @@ export async function selectMembershipsOfUser(
 
 export async function selectAllTenants(db: AnyDb): Promise<readonly SeedTenantDbRow[]> {
   return (await asRawClient(db).unsafe(
-    `SELECT id::text AS id, name, tenant_key
+    `SELECT id::text AS id, name, key AS tenant_key
      FROM read_tenants
      ORDER BY inserted_at`,
   )) as readonly SeedTenantDbRow[];

package/src/engine/__tests__/search-payload-extension.test.ts

@@ -144,6 +144,43 @@ describe("buildSearchDocument — contributor precedence (base fields win)", ()
     expect(doc?.fields).toMatchObject({ title: "real-value", flatTags: "a,b" });
     expect(warnSpy).not.toHaveBeenCalled();
   });
+
+  test("collision dedup — same collision warns exactly once across calls", async () => {
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity(
+        "thing-dedup",
+        createEntity({
+          table: "things_dedup",
+          fields: { title: createTextField({ searchable: true }) },
+        }),
+      );
+      r.searchPayloadExtension(thing, () => ({ title: "from-contributor" }));
+    });
+    const registry = createRegistry([feature]);
+    await buildSearchDocument("thing-dedup", "t1", { title: "real-value" }, registry);
+    await buildSearchDocument("thing-dedup", "t1", { title: "real-value" }, registry);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test("contributor-vs-contributor collision warns with the right message", async () => {
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity(
+        "thing",
+        createEntity({ table: "things", fields: { title: createTextField({ searchable: true }) } }),
+      );
+      r.searchPayloadExtension(thing, () => ({ overlap: "first" }));
+      r.searchPayloadExtension(thing, () => ({ overlap: "second" }));
+    });
+    const registry = createRegistry([feature]);
+
+    const doc = await buildSearchDocument("thing", "t1", { title: "real-value" }, registry);
+    // Stammfield title → no collision. overlap is NOT a Stammfield, so the
+    // second contributor's "overlap" collides with the first one's → "earlier contributor key".
+    expect(doc?.fields["title"]).toBe("real-value");
+    expect(doc?.fields["overlap"]).toBe("first");
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]?.[0]).toContain("earlier contributor key");
+  });
 });
 
 describe("Boot-Validation", () => {

package/src/engine/__tests__/validate-custom-screen-write-qns.test.ts

@@ -0,0 +1,43 @@
+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 { validateAppCustomScreenWriteQns } from "../boot-validator/custom-screen-write-qns";
+
+describe("validateAppCustomScreenWriteQns", () => {
+  test("throws on unknown dispatcher.write QN in app src", () => {
+    const appRoot = mkdtempSync(join(tmpdir(), "kumiko-boot-qns-"));
+    const srcDir = join(appRoot, "src", "screens");
+    mkdirSync(srcDir, { recursive: true });
+    writeFileSync(
+      join(srcDir, "list.tsx"),
+      `export function List() {
+        return null;
+      }
+      async function onDelete(dispatcher: { write: (t: string, p: unknown) => Promise<unknown> }) {
+        await dispatcher.write("shop:write:ghost-delete", { id: "1" });
+      }
+      `,
+      "utf-8",
+    );
+
+    const known = new Set(["shop:write:item:delete"]);
+    expect(() => validateAppCustomScreenWriteQns(appRoot, known)).toThrow(
+      /shop:write:ghost-delete/,
+    );
+  });
+
+  test("passes when QN is registered", () => {
+    const appRoot = mkdtempSync(join(tmpdir(), "kumiko-boot-qns-"));
+    const srcDir = join(appRoot, "src");
+    mkdirSync(srcDir, { recursive: true });
+    writeFileSync(
+      join(srcDir, "screen.tsx"),
+      `await dispatcher.write("shop:write:item:delete", { id: "1" });`,
+      "utf-8",
+    );
+
+    const known = new Set(["shop:write:item:delete"]);
+    expect(() => validateAppCustomScreenWriteQns(appRoot, known)).not.toThrow();
+  });
+});

package/src/engine/__tests__/write-handler-qn-extract.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import {
+  extractDispatcherWriteQnsFromSource,
+  validateDispatcherWriteQn,
+  WRITE_HANDLER_QN_FORMAT_RE,
+} from "../write-handler-qn-extract";
+
+describe("extractDispatcherWriteQnsFromSource", () => {
+  test("extracts string literals from dispatcher.write and .write calls", () => {
+    const source = `
+      await dispatcher.write("credit:write:create", { name: "x" });
+      await foo.write("tenant:write:update", payload);
+    `;
+    expect(extractDispatcherWriteQnsFromSource(source)).toEqual([
+      "credit:write:create",
+      "tenant:write:update",
+    ]);
+  });
+
+  test("skips dynamic QNs", () => {
+    const source = `await dispatcher.write(HANDLERS.delete, { id });`;
+    expect(extractDispatcherWriteQnsFromSource(source)).toEqual([]);
+  });
+});
+
+describe("validateDispatcherWriteQn", () => {
+  const known = new Set(["credit:write:credit:delete", "tenant:write:create"]);
+
+  test("accepts known QN", () => {
+    expect(validateDispatcherWriteQn("credit:write:credit:delete", known)).toEqual({ ok: true });
+  });
+
+  test("rejects invalid format", () => {
+    const result = validateDispatcherWriteQn("feautre-write-create", known);
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.reason).toContain("invalid QN format");
+  });
+
+  test("rejects unknown QN when registry provided", () => {
+    const result = validateDispatcherWriteQn("credit:write:update", known);
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.reason).toContain("unknown write handler");
+  });
+
+  test("format regex accepts 4-segment entity delete QNs", () => {
+    expect(WRITE_HANDLER_QN_FORMAT_RE.test("credit:write:credit:delete")).toBe(true);
+  });
+});

package/src/engine/boot-validator/custom-screen-write-qns.ts

@@ -0,0 +1,87 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import {
+  extractDispatcherWriteQnsFromSource,
+  validateDispatcherWriteQn,
+} from "../write-handler-qn-extract";
+
+const SKIP_SEGMENTS = new Set(["node_modules", ".kumiko", "dist", "dist-server", "__tests__"]);
+
+function collectAppSourceFiles(dir: string, out: string[]): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    // skip: directory unreadable (permissions / race) — treat as empty
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.startsWith(".")) continue;
+    if (SKIP_SEGMENTS.has(entry)) continue;
+    const full = join(dir, entry);
+    let stat: ReturnType<typeof statSync>;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      collectAppSourceFiles(full, out);
+    } else if (
+      stat.isFile() &&
+      (entry.endsWith(".ts") || entry.endsWith(".tsx")) &&
+      !entry.endsWith(".d.ts") &&
+      !entry.endsWith(".test.ts") &&
+      !entry.endsWith(".test.tsx") &&
+      !entry.endsWith(".integration.ts") &&
+      !entry.endsWith(".integration.tsx")
+    ) {
+      out.push(full);
+    }
+  }
+}
+
+/**
+ * Boot-time scan of app `src/**` for `dispatcher.write("…")` string literals.
+ * Fails fast before the first Custom-Screen click would 404.
+ *
+ * Only covers string literals — Handler-constant refs are caught by the CI
+ * guard (ts-morph) and compile-time TypedDispatcher.
+ */
+export function validateAppCustomScreenWriteQns(
+  appRoot: string,
+  knownQns: ReadonlySet<string>,
+): void {
+  const srcDir = join(appRoot, "src");
+  // skip: apps without a src/ tree (server-only packages) — nothing to scan
+  if (!existsSync(srcDir)) return;
+
+  const files: string[] = [];
+  collectAppSourceFiles(srcDir, files);
+
+  const violations: Array<{ readonly file: string; readonly qn: string; readonly reason: string }> =
+    [];
+
+  for (const filePath of files) {
+    const source = readFileSync(filePath, "utf-8");
+    for (const qn of extractDispatcherWriteQnsFromSource(source)) {
+      const result = validateDispatcherWriteQn(qn, knownQns);
+      if (!result.ok) {
+        violations.push({
+          file: relative(appRoot, filePath),
+          qn,
+          reason: result.reason,
+        });
+      }
+    }
+  }
+
+  // skip: no invalid QNs found — boot continues
+  if (violations.length === 0) return;
+
+  const lines = violations.map((v) => `  - ${v.file}: "${v.qn}" — ${v.reason}`);
+  throw new Error(
+    `[kumiko:boot] ${violations.length} invalid dispatcher.write QN(s) in app source:\n${lines.join("\n")}\n` +
+      `  Check spelling against registered write handlers (expected "<feature>:write:<handler>").`,
+  );
+}

package/src/engine/boot-validator/index.ts

@@ -39,6 +39,12 @@ import {
   validateWorkspaces,
 } from "./screens-nav";
 
+export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns";
+// Re-export: wird von run-dev-app.ts benötigt um Write-Handler-QNs
+// an den Codegen zu übergeben. Nicht Teil von validateBoot, aber
+// dieselbe Extraktionslogik.
+export { collectWriteHandlerQns } from "./screens-nav";
+
 /**
  * Validates all feature configurations at boot time.
  * Throws on the first error found — fail fast.

package/src/engine/boot-validator.ts

@@ -1 +1,5 @@
-export { validateBoot } from "./boot-validator/index";
+export {
+  collectWriteHandlerQns,
+  validateAppCustomScreenWriteQns,
+  validateBoot,
+} from "./boot-validator/index";

package/src/engine/feature-manifest.ts

@@ -7,6 +7,7 @@
 // lesen.
 
 import { compareByCodepoint } from "../utils";
+import { qualifyEntityName } from "./qualified-name";
 import type { Registry } from "./types/feature";
 
 export type ManifestConfigKey = {
@@ -51,6 +52,11 @@ export type ManifestFeature = {
   readonly extensionsUsed: readonly ManifestExtension[];
   readonly configKeys: readonly ManifestConfigKey[];
   readonly secrets: readonly ManifestSecret[];
+  /** Alle registrierten Write-Handler-QNs dieses Features
+   *  (z.B. "user:write:user:create", "auth-email-password:write:login").
+   *  Von `collectWriteHandlerQns` abgeleitet — dient als Source-of-Truth
+   *  für den Client-seitigen Typcheck von `dispatcher.write`-Calls. */
+  readonly writeHandlers: readonly string[];
   /** Optionaler Herkunfts-Tag (z.B. "enterprise") — gesetzt via Options. */
   readonly tier?: string;
 };
@@ -117,8 +123,14 @@ export function buildManifestFromRegistry(
       });
     }
 
+    const writeHandlerQns: string[] = [];
+    for (const handlerName of Object.keys(feature.writeHandlers)) {
+      writeHandlerQns.push(qualifyEntityName(feature.name, "write", handlerName));
+    }
+
     configKeys.sort((a, b) => compareByCodepoint(a.qualifiedName, b.qualifiedName));
     secrets.sort((a, b) => compareByCodepoint(a.qualifiedName, b.qualifiedName));
+    writeHandlerQns.sort(compareByCodepoint);
 
     manifestFeatures.push({
       name: feature.name,
@@ -135,6 +147,7 @@ export function buildManifestFromRegistry(
       })),
       configKeys,
       secrets,
+      writeHandlers: writeHandlerQns,
       ...(options.tier !== undefined && { tier: options.tier }),
     });
   }

package/src/engine/index.ts

@@ -1,7 +1,11 @@
 // Public API
 
 export { hasAccess } from "./access";
-export { validateBoot } from "./boot-validator";
+export {
+  collectWriteHandlerQns,
+  validateAppCustomScreenWriteQns,
+  validateBoot,
+} from "./boot-validator";
 export { buildAppSchema } from "./build-app-schema";
 export type { ConfigFeatureSchema } from "./build-config-feature-schema";
 export {

package/src/engine/write-handler-qn-extract.ts

@@ -0,0 +1,47 @@
+import { toKebab } from "./qualified-name";
+
+/**
+ * Regex for a valid write-handler QN shape.
+ * 3 segments (feature:write:handler) or 4+ (feature:write:entity:verb).
+ */
+export const WRITE_HANDLER_QN_FORMAT_RE =
+  /^[a-zA-Z][a-zA-Z0-9-]*:write:[a-zA-Z][a-zA-Z0-9-]*(:[a-zA-Z][a-zA-Z0-9-]*)*$/;
+
+// Matches `dispatcher.write("qn", ...)` and `<expr>.write("qn", ...)` —
+// same surface the CI guard scans. Dynamic QNs (variables, templates) are
+// intentionally skipped (known limitation, documented in #403).
+const DISPATCHER_WRITE_LITERAL_RE = /\.write\s*\(\s*["']([^"']+)["']/g;
+
+/** Extract string-literal write-handler QNs from TS/TSX source text. */
+export function extractDispatcherWriteQnsFromSource(source: string): readonly string[] {
+  const out = new Set<string>();
+  for (const match of source.matchAll(DISPATCHER_WRITE_LITERAL_RE)) {
+    const qn = match[1];
+    if (qn) out.add(qn);
+  }
+  return [...out];
+}
+
+export type WriteHandlerQnValidation =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: string };
+
+/** Validate a single QN against optional known set (kebab-normalized). */
+export function validateDispatcherWriteQn(
+  qn: string,
+  knownQns: ReadonlySet<string>,
+): WriteHandlerQnValidation {
+  if (!WRITE_HANDLER_QN_FORMAT_RE.test(qn)) {
+    return {
+      ok: false,
+      reason: `invalid QN format: "${qn}" — expected "<feature>:write:<handler>"`,
+    };
+  }
+  if (knownQns.size > 0 && !knownQns.has(toKebab(qn))) {
+    return {
+      ok: false,
+      reason: `unknown write handler: "${qn}" — not registered via r.writeHandler(...)`,
+    };
+  }
+  return { ok: true };
+}

package/src/es-ops/__tests__/context.integration.test.ts

@@ -66,7 +66,7 @@ beforeAll(async () => {
     CREATE TABLE IF NOT EXISTS read_tenants (
       id            uuid PRIMARY KEY,
       name          text NOT NULL,
-      tenant_key    text NOT NULL,
+      key    text NOT NULL,
       inserted_at   timestamptz NOT NULL DEFAULT now()
     );
   `);
@@ -273,7 +273,7 @@ describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
 describe("SeedMigrationContext.findTenants (integration)", () => {
   test("returnt alle Tenants sortiert nach inserted_at", async () => {
     await asRawClient(testDb.db).unsafe(`
-      INSERT INTO read_tenants (id, name, tenant_key, inserted_at) VALUES
+      INSERT INTO read_tenants (id, name, key, inserted_at) VALUES
         ('00000000-0000-4000-8000-000000000002'::uuid, 'Beta',  'beta',  '2026-01-02'),
         ('00000000-0000-4000-8000-000000000001'::uuid, 'Alpha', 'alpha', '2026-01-01')
     `);
@@ -365,7 +365,7 @@ describe("runPendingSeedMigrations: skippable + env-flag (integration)", () => {
 describe("SeedMigrationContext.db (escape-hatch, integration)", () => {
   test("ctx.db kann für eigene Lookups genutzt werden (read-only)", async () => {
     await asRawClient(testDb.db).unsafe(`
-      INSERT INTO read_tenants (id, name, tenant_key) VALUES
+      INSERT INTO read_tenants (id, name, key) VALUES
         ('00000000-0000-4000-8000-000000000007'::uuid, 'Lucky', 'lucky')
     `);
     const ctx = createSeedMigrationContext({
@@ -373,7 +373,7 @@ describe("SeedMigrationContext.db (escape-hatch, integration)", () => {
       dbRunner: testDb.db,
     });
     const rows = (await asRawClient(ctx.db).unsafe(
-      `SELECT name FROM read_tenants WHERE tenant_key = 'lucky'`,
+      `SELECT name FROM read_tenants WHERE key = 'lucky'`,
     )) as unknown as readonly { name: string }[];
     expect(rows[0]?.name).toBe("Lucky");
   });