@cosmicdrift/kumiko-bundled-features 0.21.1 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.21.1",
+  "version": "0.23.1",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -26,6 +26,7 @@
     "./tier-engine": "./src/tier-engine/index.ts",
     "./cap-counter": "./src/cap-counter/index.ts",
     "./custom-fields": "./src/custom-fields/index.ts",
+    "./custom-fields/web": "./src/custom-fields/web/index.ts",
     "./billing-foundation": "./src/billing-foundation/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",

package/src/auth-email-password/__tests__/invite-flow.integration.test.ts

@@ -138,12 +138,12 @@ beforeEach(async () => {
   });
 
   // Alice = Admin von Tenant-A
-  aliceId = await seedUser(stack.db, {
+  ({ id: aliceId } = await seedUser(stack.db, {
     email: ALICE_EMAIL,
     displayName: "Alice",
     passwordHash: await hashPassword("alice-pw-1234"),
     emailVerified: true,
-  });
+  }));
   await seedTenantMembership(stack.db, {
     userId: aliceId,
     tenantId: TENANT_A_ID,
@@ -151,12 +151,12 @@ beforeEach(async () => {
   });
 
   // Bob = Member von Tenant-B (für Branch 1 + 2 tests)
-  bobId = await seedUser(stack.db, {
+  ({ id: bobId } = await seedUser(stack.db, {
     email: BOB_EMAIL,
     displayName: "Bob",
     passwordHash: await hashPassword(BOB_PASSWORD),
     emailVerified: true,
-  });
+  }));
   await seedTenantMembership(stack.db, {
     userId: bobId,
     tenantId: TENANT_B_ID,

package/src/auth-email-password/__tests__/seed-admin.integration.test.ts

@@ -61,7 +61,7 @@ beforeEach(async () => {
 
 describe("seedAdmin", () => {
   test("legt Tenants, User mit gehashtem Password und Memberships an — Login-Roundtrip funktioniert", async () => {
-    const userId = await seedAdmin(stack.db, {
+    const { id: userId } = await seedAdmin(stack.db, {
       email: "admin@example.com",
       password: "secret-pw",
       displayName: "Admin",
@@ -113,7 +113,7 @@ describe("seedAdmin", () => {
 
   test("idempotent: zweiter Aufruf no-op (kein Crash, Stand bleibt)", async () => {
     // Erstaufruf
-    const userId1 = await seedAdmin(stack.db, {
+    const { id: userId1 } = await seedAdmin(stack.db, {
       email: "admin@example.com",
       password: "pw1",
       displayName: "Admin",
@@ -124,7 +124,7 @@ describe("seedAdmin", () => {
     // Zweiter Aufruf — gleicher Email, anderes Password (würde theoretisch
     // einen neuen Hash erzeugen und neu schreiben, der idempotent-Check
     // greift VOR dem Insert).
-    const userId2 = await seedAdmin(stack.db, {
+    const { id: userId2 } = await seedAdmin(stack.db, {
       email: "admin@example.com",
       password: "pw2",
       displayName: "Admin",

package/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -138,7 +138,7 @@ export function createInviteSignupCompleteHandler() {
         // @cast-boundary db-runner — TenantDb.raw is DbRunner; seed-helpers
         // operate on plain drizzle-API which both shapes expose identically.
         const dbConn = ctx.db.raw as DbConnection;
-        const userId = await seedUserWithPassword(dbConn, {
+        const { id: userId } = await seedUserWithPassword(dbConn, {
           email: invitationEmail,
           password: event.payload.password,
           displayName: invitationEmail.split("@")[0] ?? invitationEmail,

package/src/auth-email-password/seeding.ts

@@ -46,12 +46,12 @@ export type SeedUserWithPasswordOptions = {
 
 /**
  * Seed a user mit Plain-Password (wird vor dem Insert mit argon2
- * gehasht). Liefert userId, idempotent über email.
+ * gehasht). Liefert die userId, idempotent über email.
  */
 export async function seedUserWithPassword(
   db: DbConnection,
   options: SeedUserWithPasswordOptions,
-): Promise<string> {
+): Promise<{ id: string }> {
   const passwordHash = await hashPassword(options.password);
   return seedUser(db, {
     email: options.email,
@@ -114,7 +114,7 @@ export async function provisionSignupAccount(
     key: options.tenantKey,
     name: options.tenantName,
   });
-  const userId = await seedUserWithPassword(db, {
+  const { id: userId } = await seedUserWithPassword(db, {
     email: options.email,
     password: options.password,
     displayName: options.displayName,
@@ -155,14 +155,17 @@ export type SeedAdminOptions = {
  * Password + N Tenants + N Memberships. Alles idempotent (Re-Run im
  * persistent-DB-Modus läuft durch). Liefert die userId zurück.
  */
-export async function seedAdmin(db: DbConnection, options: SeedAdminOptions): Promise<string> {
+export async function seedAdmin(
+  db: DbConnection,
+  options: SeedAdminOptions,
+): Promise<{ id: string }> {
   const by = options.by ?? TestUsers.systemAdmin;
 
   for (const m of options.memberships) {
     await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, by });
   }
 
-  const userId = await seedUserWithPassword(db, {
+  const { id: userId } = await seedUserWithPassword(db, {
     email: options.email,
     password: options.password,
     displayName: options.displayName,
@@ -179,5 +182,5 @@ export async function seedAdmin(db: DbConnection, options: SeedAdminOptions): Pr
     });
   }
 
-  return userId;
+  return { id: userId };
 }

package/src/compliance-profiles/seeding.ts

@@ -45,7 +45,7 @@ export type SeedComplianceProfileOptions = {
 export async function seedComplianceProfile(
   db: DbConnection,
   opts: SeedComplianceProfileOptions,
-): Promise<{ id: string | number }> {
+): Promise<{ id: string }> {
   // user.tenantId muss === opts.tenantId sein damit Event-Store-Stream
   // + Projection im selben Tenant-Bucket landen (Memory:
   // feedback_event_store_tenant_consistency).
@@ -73,6 +73,9 @@ export async function seedComplianceProfile(
       if (!result.isSuccess) {
         throw new Error(`seedComplianceProfile create failed: ${JSON.stringify(result)}`);
       }
+      // @cast-boundary db-row: executor.create result.data ist die
+      // inserted Projection-Row (Record<string, unknown>); id ist nach
+      // INSERT garantiert (Runtime-Check direkt darunter).
       const data = result.data as { id?: string };
       if (data.id === undefined) {
         throw new Error("seedComplianceProfile: executor.create did not return an id");

package/src/custom-fields/__tests__/custom-fields.integration.test.ts

@@ -335,6 +335,64 @@ describe("custom-fields integration — value validation (Builder-Reuse)", () =>
     expect(await countSetEvents(id)).toBe(0);
   });
 
+  test("required-text accepts empty + over-maxLength strings (constraint-keys stripped)", async () => {
+    const id = "bbbbbbbb-bbbb-4000-8000-00000000000b";
+    // serializedField carries required + maxLength + format — value-schema
+    // strips these before fieldToZod, so the runtime schema collapses to a
+    // bare z.string(). Required-on-set + length/format-enforcement remain
+    // out-of-scope (Plan-Doc "Stammfeld-Identität").
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "note",
+        serializedField: { type: "text", required: true, maxLength: 5, format: "email" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      admin,
+    );
+    await createProperty(id, "TypeOnly");
+
+    await setCustomField("property", id, "note", "");
+    await setCustomField("property", id, "note", "not-an-email-and-way-too-long");
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await rawCustomFields(id)).toMatchObject({ note: "not-an-email-and-way-too-long" });
+  });
+
+  test("default-having field validates as plain type (default-key stripped)", async () => {
+    const id = "cccccccc-cccc-4000-8000-00000000000c";
+    // Pre-fix: fieldToZod folded `default` into `.default(...)`. Combined with
+    // emitting `payload.value` (not `parsed.data`) the in-code path would skip
+    // the type-check for a missing value. value-schema now strips `default`
+    // before fieldToZod so the runtime schema is bare `z.number()` — matching
+    // values still pass, type-mismatches still 422.
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "score",
+        serializedField: { type: "number", default: 0 },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      admin,
+    );
+    await createProperty(id, "DefaultStripped");
+
+    const err = await setErr(id, "score", "not-a-number");
+    expect(err.httpStatus).toBe(422);
+    expect(err.details).toMatchObject({ reason: "custom_field_value_invalid" });
+    expect(await countSetEvents(id)).toBe(0);
+
+    await setCustomField("property", id, "score", 7);
+    await stack.eventDispatcher?.runOnce();
+    expect(await rawCustomFields(id)).toMatchObject({ score: 7 });
+  });
+
   test("embedded field rejects a non-object value → 422, no event", async () => {
     const id = "aaaaaaaa-aaaa-4000-8000-00000000000a";
     // embedded carries a sub-field schema in serializedField — exercises

package/src/custom-fields/constants.ts

@@ -1,3 +1,4 @@
+// @runtime client
 // custom-fields bundle constants — feature-name + event-names.
 //
 // Spec: kumiko-platform/docs/plans/features/custom-fields.md
@@ -5,6 +6,28 @@
 
 export const CUSTOM_FIELDS_FEATURE_NAME = "custom-fields";
 
+// Qualified handler names (QN format: scope:type:name). Mirror text-
+// content's Handler/Queries object pattern — Clients (z.B. die
+// CustomFieldsFormSection web-component) referenzieren über das Object
+// statt magic-strings.
+export const CustomFieldsHandlers = {
+  defineTenantField: "custom-fields:write:define-tenant-field",
+  defineSystemField: "custom-fields:write:define-system-field",
+  deleteTenantField: "custom-fields:write:delete-tenant-field",
+  deleteSystemField: "custom-fields:write:delete-system-field",
+  setCustomField: "custom-fields:write:set-custom-field",
+  clearCustomField: "custom-fields:write:clear-custom-field",
+} as const;
+
+export const CustomFieldsQueries = {
+  fieldDefinitionList: "custom-fields:query:field-definition:list",
+} as const;
+
+// Name unter dem die web-component im ExtensionSectionsProvider
+// registriert wird — Apps referenzieren ihn im Screen-Schema via
+// `component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } }`.
+export const CUSTOM_FIELDS_FORM_EXTENSION_NAME = "CustomFieldsFormSection";
+
 // Event-Type-Names (qualified at registration via r.defineEvent — final
 // names are `custom-fields:event:field-definition-created` etc.).
 // Short-names MUST be in kebab-case (no dots): qualifyEntityName runs toKebab

package/src/custom-fields/handlers/set-custom-field.write.ts

@@ -32,11 +32,15 @@ export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
 //   3. Value-Validation (Builder-Reuse): der Wert wird gegen das aus
 //      serializedField rehydrierte fieldToZod-Schema geparst. Type-Mismatch →
 //      422, KEIN Event entsteht (Projection bleibt typed — Plan-Doc
-//      Stammfeld-Identität). `value: null` auf einem typisierten Feld ist ein
-//      Type-Mismatch → 422; zum Entfernen eines Werts dient clear-custom-field.
+//      Stammfeld-Identität). `value: null` ODER `value: undefined` auf einem
+//      typisierten Feld sind Type-Mismatches → 422; zum Entfernen eines Werts
+//      dient clear-custom-field.
 //
-// Scope: NUR Type-Validation. Required-on-set + Default-Application sind
-// out-of-scope (Plan-Doc "Stammfeld-Identität" listet sie als eigene Zeilen).
+// Scope: ECHTE type-only Validation. value-schema.ts strippt `required`,
+// `maxLength`, `format` und `default` aus dem serializedField bevor fieldToZod
+// daraus ein Schema baut — wir prüfen nur die Type-Shape. Required-on-set,
+// Default-Application und Length-/Format-Enforcement bleiben out-of-scope
+// (Plan-Doc "Stammfeld-Identität" listet sie als eigene Zeilen).
 export const setCustomFieldHandler: WriteHandlerDef = {
   name: "set-custom-field",
   schema: setCustomFieldPayloadSchema,

package/src/custom-fields/lib/value-schema.ts

@@ -4,29 +4,67 @@ import {
   fieldToZod,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { z } from "zod";
+import { SUPPORTED_FIELD_TYPES } from "../constants";
 
 // Builds a Zod schema that validates a custom-field VALUE against its
 // fieldDefinition. Reuses the framework's `fieldToZod` (Builder-Reuse /
 // Stammfeld-Identität, Plan-Doc) — one field-type-schema source, no drift
 // between Stammfeld- and Custom-Field-validation.
 //
+// Scope: type-shape only. fieldToZod also folds `required`, `maxLength`,
+// `format`, and `default` into Zod refinements; we strip those before the
+// call so set-custom-field rejects type-mismatches and only type-mismatches.
+// Required-on-set, default-application, and length/format-enforcement remain
+// out-of-scope per the Plan-Doc ("Stammfeld-Identität" lists them as
+// separate concerns).
+//
 // Vocabulary bridge: custom-fields expose `enum` (Plan + `r.field.enum([...])`)
 // where the framework's FieldDefinition calls the equivalent type `select`
-// with an `options` array. This single boundary translates it; everything
-// else is already FieldDefinition-shaped (the serialized dehydrated builder).
+// with an `options` array.
 //
 // Returns `null` when the serialized field is unparseable or names a type
-// `fieldToZod` cannot interpret — callers then skip value-validation rather
-// than hard-rejecting a field they cannot understand.
+// outside the custom-fields-supported set — callers then skip value-validation.
+
+const SUPPORTED_TYPES_SET: ReadonlySet<string> = new Set(SUPPORTED_FIELD_TYPES);
+const SUPPORTED_EMBEDDED_SUB_TYPES: ReadonlySet<string> = new Set([
+  "text",
+  "number",
+  "boolean",
+  "date",
+]);
+
+// Constraint-keys fieldToZod converts into Zod refinements. Stripped so the
+// resulting schema validates the type-shape only, not the constraint.
+const CONSTRAINT_KEYS = ["required", "maxLength", "format", "default"] as const;
+
 export function buildCustomFieldValueSchema(parsedField: unknown): z.ZodTypeAny | null {
   if (!parsedField || typeof parsedField !== "object") return null;
   const obj = parsedField as Record<string, unknown>;
-  if (typeof obj["type"] !== "string") return null;
+  const rawType = obj["type"];
+  if (typeof rawType !== "string") return null;
+  if (!SUPPORTED_TYPES_SET.has(rawType)) return null;
 
-  const fieldDef =
-    obj["type"] === "enum"
-      ? { ...obj, type: "select", options: obj["values"] ?? obj["options"] ?? [] }
-      : obj;
+  // Embedded sub-fields: pre-check the sub-type set so we surface unknown
+  // sub-types as "skip validation" (return null) rather than letting
+  // fieldToZod's assertUnreachable throw and the catch swallow real bugs.
+  if (rawType === "embedded") {
+    const schema = obj["schema"];
+    if (!schema || typeof schema !== "object") return null;
+    for (const sub of Object.values(schema)) {
+      if (!sub || typeof sub !== "object") return null;
+      const subType = (sub as Record<string, unknown>)["type"];
+      if (typeof subType !== "string" || !SUPPORTED_EMBEDDED_SUB_TYPES.has(subType)) {
+        return null;
+      }
+    }
+  }
+
+  const fieldDef: Record<string, unknown> = { ...obj };
+  for (const k of CONSTRAINT_KEYS) delete fieldDef[k];
+  if (rawType === "enum") {
+    fieldDef["type"] = "select";
+    fieldDef["options"] = obj["values"] ?? obj["options"] ?? [];
+  }
 
   // fieldToZod's money case validates `currency` against the passed list, not
   // a field-level key — so surface the field's own currency when it declares
@@ -34,12 +72,8 @@ export function buildCustomFieldValueSchema(parsedField: unknown): z.ZodTypeAny
   const currencies =
     typeof obj["currency"] === "string" ? [obj["currency"] as string] : DEFAULT_CURRENCIES;
 
-  try {
-    // @cast-boundary serialized-field is the dehydrated r.field.X() output =
-    // a FieldDefinition; fieldToZod reads only its type-specific keys (the
-    // extra fieldAccess/sensitive/retention/label keys are ignored).
-    return fieldToZod(fieldDef as unknown as FieldDefinition, currencies);
-  } catch {
-    return null;
-  }
+  // @cast-boundary serialized-field is the dehydrated r.field.X() output =
+  // a FieldDefinition; fieldToZod reads only its type-specific keys (the
+  // extra fieldAccess/sensitive/retention/label keys are ignored).
+  return fieldToZod(fieldDef as unknown as FieldDefinition, currencies);
 }

package/src/custom-fields/web/__tests__/custom-fields-form-section.test.tsx

@@ -0,0 +1,144 @@
+import { describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { fireEvent, render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { CustomFieldsFormSection } from "../custom-fields-form-section";
+
+type FieldRow = {
+  id: string;
+  entityName: string;
+  fieldKey: string;
+  type: string;
+  required: boolean;
+  displayOrder: number;
+};
+
+const dispatchSpy = mock(async () => ({ isSuccess: true, data: undefined }));
+let mockedQueryRows: readonly FieldRow[] = [];
+
+const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actual_renderer,
+  useDispatcher: mock(() => ({
+    write: dispatchSpy,
+    query: mock(),
+    batch: mock(),
+  })),
+  useQuery: mock(() => ({
+    data: { rows: mockedQueryRows },
+    loading: false,
+    error: null,
+    refetch: mock(),
+  })),
+}));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+describe("CustomFieldsFormSection", () => {
+  test("renders an input per matching fieldDefinition and dispatches set-custom-field on save", async () => {
+    mockedQueryRows = [
+      {
+        id: "f1",
+        entityName: "component",
+        fieldKey: "vendor",
+        type: "text",
+        required: false,
+        displayOrder: 1,
+      },
+      {
+        id: "f2",
+        entityName: "component",
+        fieldKey: "tier",
+        type: "number",
+        required: false,
+        displayOrder: 2,
+      },
+      {
+        id: "f3",
+        entityName: "incident",
+        fieldKey: "rootCause",
+        type: "text",
+        required: false,
+        displayOrder: 1,
+      },
+    ];
+    dispatchSpy.mockClear();
+
+    render(
+      <Wrapper>
+        <CustomFieldsFormSection entityName="component" entityId="row-42" />
+      </Wrapper>,
+    );
+
+    // Only `component`-entity fields are rendered (incident's rootCause filtered out).
+    expect(screen.getByTestId("custom-fields-form-section")).toBeTruthy();
+    const vendorInput = document.getElementById("custom-field-vendor") as HTMLInputElement;
+    const tierInput = document.getElementById("custom-field-tier") as HTMLInputElement;
+    expect(vendorInput).toBeTruthy();
+    expect(tierInput).toBeTruthy();
+    expect(document.getElementById("custom-field-rootCause")).toBeNull();
+
+    // Type in vendor; tier left empty (should be skipped on save).
+    fireEvent.change(vendorInput, { target: { value: "Hetzner" } });
+
+    const saveBtn = screen.getByTestId("custom-fields-form-save");
+    fireEvent.click(saveBtn);
+    // Wait one microtask for the async handleSave loop.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(dispatchSpy).toHaveBeenCalledTimes(1);
+    expect(dispatchSpy).toHaveBeenCalledWith("custom-fields:write:set-custom-field", {
+      entityName: "component",
+      entityId: "row-42",
+      fieldKey: "vendor",
+      value: "Hetzner",
+    });
+  });
+
+  test("shows create-mode banner when entityId is null", () => {
+    mockedQueryRows = [];
+
+    render(
+      <Wrapper>
+        <CustomFieldsFormSection entityName="component" entityId={null} />
+      </Wrapper>,
+    );
+
+    expect(screen.getByTestId("custom-fields-form-create-mode")).toBeTruthy();
+    expect(screen.queryByTestId("custom-fields-form-section")).toBeNull();
+  });
+
+  test("shows empty banner when no fieldDefinitions match entityName", () => {
+    mockedQueryRows = [
+      {
+        id: "f3",
+        entityName: "incident",
+        fieldKey: "rootCause",
+        type: "text",
+        required: false,
+        displayOrder: 1,
+      },
+    ];
+
+    render(
+      <Wrapper>
+        <CustomFieldsFormSection entityName="component" entityId="row-42" />
+      </Wrapper>,
+    );
+
+    expect(screen.getByTestId("custom-fields-form-empty")).toBeTruthy();
+    expect(screen.queryByTestId("custom-fields-form-section")).toBeNull();
+  });
+});

package/src/custom-fields/web/client-plugin.tsx

@@ -0,0 +1,25 @@
+// @runtime client
+// Client-Feature-Factory für custom-fields. Wird vom App-Code in
+// createKumikoApp({ clientFeatures: [customFieldsClient()] }) eingehängt
+// und registriert die CustomFieldsFormSection unter dem Namen
+// CUSTOM_FIELDS_FORM_EXTENSION_NAME im ExtensionSectionsProvider. Apps
+// referenzieren den Namen im Screen-Schema:
+//
+//   layout: { sections: [
+//     { kind: "extension", title: "...", component: {
+//       react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME }
+//     } },
+//   ]}
+
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { CUSTOM_FIELDS_FEATURE_NAME, CUSTOM_FIELDS_FORM_EXTENSION_NAME } from "../constants";
+import { CustomFieldsFormSection } from "./custom-fields-form-section";
+
+export function customFieldsClient(): ClientFeatureDefinition {
+  return {
+    name: CUSTOM_FIELDS_FEATURE_NAME,
+    extensionSectionComponents: {
+      [CUSTOM_FIELDS_FORM_EXTENSION_NAME]: CustomFieldsFormSection,
+    },
+  };
+}