@cosmicdrift/kumiko-bundled-features 0.32.1 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "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>",

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

@@ -113,6 +113,17 @@ async function countDefinitions(tenantId: string, fieldKey: string): Promise<num
   return (rows as ReadonlyArray<{ n: number }>)[0]?.n ?? 0;
 }
 
+async function fetchDefinitionRow(
+  tenantId: string,
+  fieldKey: string,
+): Promise<Record<string, unknown> | undefined> {
+  const rows = await asRawClient(stack.db).unsafe(
+    "SELECT entity_name, field_key, type, required, searchable, display_order, serialized_field FROM read_custom_field_definitions WHERE tenant_id = $1 AND field_key = $2",
+    [tenantId, fieldKey],
+  );
+  return (rows as ReadonlyArray<Record<string, unknown>>)[0];
+}
+
 async function defineField(entityName: string, fieldKey: string, type = "text") {
   return stack.http.writeOk(
     "custom-fields:write:define-tenant-field",
@@ -561,3 +572,142 @@ describe("custom-fields integration — value validation (Builder-Reuse)", () =>
     expect(await rawCustomFields(id)).toMatchObject({ geo: { city: "Bonn" } });
   });
 });
+
+describe("custom-fields integration — update-tenant-field (Bug-Bash D2)", () => {
+  async function updateField(fieldKey: string, overrides: Record<string, unknown>, user = admin) {
+    return stack.http.writeOk(
+      "custom-fields:write:update-tenant-field",
+      {
+        entityName: "property",
+        fieldKey,
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+        ...overrides,
+      },
+      user,
+    );
+  }
+
+  test("define → update ersetzt Spalten + serializedField-Inhalt (Projektion)", async () => {
+    await defineField("property", "priority", "number");
+    await updateField("priority", {
+      serializedField: { type: "number", min: 0, max: 10 },
+      required: true,
+      searchable: true,
+      displayOrder: 7,
+      label: { de: "Priorität", en: "Priority" },
+    });
+
+    const row = await fetchDefinitionRow(admin.tenantId, "priority");
+    expect(row).toBeDefined();
+    expect(row?.["type"]).toBe("number");
+    expect(row?.["required"]).toBe(true);
+    expect(row?.["searchable"]).toBe(true);
+    expect(Number(row?.["display_order"])).toBe(7);
+    // serializedField über den update-Pfad (flattenCompoundTypes ≠ create-Pfad)
+    // zurückparsen — Inhalt beweisen, nicht nur write-success.
+    const sf = JSON.parse(String(row?.["serialized_field"])) as Record<string, unknown>;
+    expect(sf["min"]).toBe(0);
+    expect(sf["max"]).toBe(10);
+    expect(sf["label"]).toEqual({ de: "Priorität", en: "Priority" });
+  });
+
+  test("zwei sequentielle Updates ohne version_conflict (skipOptimisticLock)", async () => {
+    await defineField("property", "stage", "text");
+    await updateField("stage", { displayOrder: 1 });
+    await updateField("stage", { displayOrder: 2 });
+    const row = await fetchDefinitionRow(admin.tenantId, "stage");
+    expect(Number(row?.["display_order"])).toBe(2);
+  });
+
+  test("update auf nicht-existente Definition → 404", async () => {
+    const err = await stack.http.writeErr(
+      "custom-fields:write:update-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "ghost",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      admin,
+    );
+    expect(err.httpStatus).toBe(404);
+  });
+
+  test("type-Wechsel → 422 field_type_immutable, Bestand unverändert", async () => {
+    await defineField("property", "color", "text");
+    const err = await stack.http.writeErr(
+      "custom-fields:write:update-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "color",
+        serializedField: { type: "number" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      admin,
+    );
+    expect(err.httpStatus).toBe(422);
+    expect(err.details).toMatchObject({
+      reason: "field_type_immutable",
+      currentType: "text",
+      requestedType: "number",
+    });
+    const row = await fetchDefinitionRow(admin.tenantId, "color");
+    expect(row?.["type"]).toBe("text");
+  });
+
+  test("Cross-Tenant: fremde (entityName,fieldKey) → 404, Owner-Definition unverändert", async () => {
+    await defineField("property", "secret", "text");
+    // Expliziter Fremd-Tenant — createTestUser ohne tenantId landet im
+    // selben Default-Test-Tenant wie `admin`.
+    const otherAdmin = createTestUser({
+      roles: ["TenantAdmin"],
+      tenantId: "00000000-0000-4000-8000-000000000099",
+    });
+    const err = await stack.http.writeErr(
+      "custom-fields:write:update-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "secret",
+        serializedField: { type: "text" },
+        required: true,
+        searchable: false,
+        displayOrder: 0,
+      },
+      otherAdmin,
+    );
+    // aggregate-id deriviert aus otherAdmin.tenantId → trifft nichts.
+    expect(err.httpStatus).toBe(404);
+    const row = await fetchDefinitionRow(admin.tenantId, "secret");
+    expect(row?.["required"]).toBe(false);
+  });
+
+  test("update-tenant-field rejects a caller whose tenant IS the system tenant", async () => {
+    const systemScopedAdmin = createTestUser({
+      roles: ["TenantAdmin"],
+      tenantId: SYSTEM_TENANT_ID,
+    });
+    const err = await stack.http.writeErr(
+      "custom-fields:write:update-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "leaky",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      systemScopedAdmin,
+    );
+    // Guard wirft plain Error → 500; Message pinnen (wie der define-Guard-Test).
+    expect(err.httpStatus).toBe(500);
+    const causeMessage = (err.details as { causeMessage?: string } | undefined)?.causeMessage ?? "";
+    expect(causeMessage).toContain("update-tenant-field");
+  });
+});

package/src/custom-fields/feature.ts

@@ -6,6 +6,7 @@
 //   2. define-tenant-field / define-system-field — RBAC write-handlers für
 //      Definition-CRUD.
 //   3. delete-tenant-field / delete-system-field — RBAC write-handlers.
+//   3b. update-tenant-field — Vollersatz-Edit (Bug-Bash D2); type immutable.
 //   4. set-custom-field / clear-custom-field — write-handlers für VALUES.
 //      Emittieren customField.set/.cleared-Events auf host-aggregate-stream.
 //   5. r.defineEvent für customField.set/.cleared + fieldDefinition.deleted.
@@ -62,6 +63,7 @@ import {
 import { deleteSystemFieldHandler } from "./handlers/delete-system-field.write";
 import { deleteTenantFieldHandler } from "./handlers/delete-tenant-field.write";
 import { setCustomFieldHandler } from "./handlers/set-custom-field.write";
+import { updateTenantFieldHandler } from "./handlers/update-tenant-field.write";
 
 const tenantAdminAccess = { access: { roles: ["TenantAdmin"] } } as const;
 
@@ -85,7 +87,7 @@ function registerCustomFields(
   defineTenantHandler: WriteHandlerDef,
 ) {
   r.describe(
-    "Tenant- and system-scoped custom field definitions with generic value storage on any host entity. Registers the `field-definition` entity (event-sourced CRUD via `define-tenant-field`, `define-system-field`, `delete-tenant-field`, `delete-system-field`) and two value write-handlers (`set-custom-field`, `clear-custom-field`) that emit `custom-fields:event:custom-field-set` / `custom-fields:event:custom-field-cleared` events on the host aggregate's stream. To attach custom fields to your own entity, call `wireCustomFieldsFor(r, entityName, entityTable)` in the host feature — this wires the JSONB projection, `postQuery` flattening hook, and search-payload extension. The host entity must declare a `customFieldsField()` JSONB column.",
+    "Tenant- and system-scoped custom field definitions with generic value storage on any host entity. Registers the `field-definition` entity (event-sourced CRUD via `define-tenant-field`, `define-system-field`, `update-tenant-field`, `delete-tenant-field`, `delete-system-field`) and two value write-handlers (`set-custom-field`, `clear-custom-field`) that emit `custom-fields:event:custom-field-set` / `custom-fields:event:custom-field-cleared` events on the host aggregate's stream. To attach custom fields to your own entity, call `wireCustomFieldsFor(r, entityName, entityTable)` in the host feature — this wires the JSONB projection, `postQuery` flattening hook, and search-payload extension. The host entity must declare a `customFieldsField()` JSONB column.",
   );
   r.entity("field-definition", fieldDefinitionEntity);
 
@@ -110,9 +112,10 @@ function registerCustomFields(
   // explicit-wiring statt magic-auto-wiring.
   r.extendsRegistrar(CUSTOM_FIELDS_EXTENSION, {});
 
-  // Definition-CRUD handlers (B1).
+  // Definition-CRUD handlers (B1; update kam mit Bug-Bash D2 2026-06-08).
   r.writeHandler(defineTenantHandler);
   r.writeHandler(defineSystemFieldHandler);
+  r.writeHandler(updateTenantFieldHandler);
   r.writeHandler(deleteTenantFieldHandler);
   r.writeHandler(deleteSystemFieldHandler);
 

package/src/custom-fields/handlers/update-tenant-field.write.ts

@@ -0,0 +1,65 @@
+import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { fieldDefinitionAggregateId } from "../aggregate-id";
+import { fieldDefinitionExecutor } from "../executor";
+import { buildFieldDefinitionColumns } from "../lib/field-definition-row";
+import { type UpdateFieldPayload, updateFieldPayloadSchema } from "../schemas";
+
+// update-tenant-field — TenantAdmin ersetzt den Stand einer bestehenden
+// Field-Definition (Vollersatz: Payload-Shape = define, der Edit-Screen
+// schickt den kompletten neuen Stand). Identität ist (entityName, fieldKey)
+// → deterministische aggregate-id wie bei define/delete; tenantId kommt
+// aus event.user (Cross-Tenant-Mutation unmöglich, fremde Definitionen
+// derivieren auf eine andere aggregate-id → 404).
+//
+// **type ist immutable.** Ein Type-Wechsel würde bestehende Values in den
+// host-entity customFields-jsonbs verwaisen (text-Wert unter number-Feld);
+// dafür ist delete + re-define der ehrliche Weg (Bug-Bash D2: bewusst KEIN
+// delete+redefine im update — das würde Event-Historie + Field-Ids
+// zerstören, aber ein Type-Wechsel will genau diese Zäsur).
+//
+// **skipOptimisticLock:** Definition-Edits sind admin-only + low-frequency
+// (gleiche Abwägung wie der Quota-soft-cap in define). Last-write-wins
+// statt version-Roundtrip durch den Edit-Screen.
+export const updateTenantFieldHandler: WriteHandlerDef = {
+  name: "update-tenant-field",
+  schema: updateFieldPayloadSchema,
+  access: { roles: ["TenantAdmin"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as UpdateFieldPayload; // @cast-boundary engine-payload
+    const tenantId = event.user.tenantId;
+
+    if (isSystemTenant(tenantId)) {
+      throw new Error(
+        "update-tenant-field: tenantId is SYSTEM_TENANT_ID — system-scope definitions have no update handler (delete + re-define via the system-field handlers)",
+      );
+    }
+
+    const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
+
+    const existing = await fieldDefinitionExecutor.detail({ id: aggregateId }, event.user, ctx.db);
+    if (!existing) {
+      return failNotFound("field-definition", aggregateId);
+    }
+
+    if (existing["type"] !== payload.serializedField.type) {
+      return failUnprocessable("field_type_immutable", {
+        entityName: payload.entityName,
+        fieldKey: payload.fieldKey,
+        currentType: existing["type"],
+        requestedType: payload.serializedField.type,
+      });
+    }
+
+    // entityName/fieldKey sind die Identität — nicht Teil der changes.
+    const {
+      entityName: _entityName,
+      fieldKey: _fieldKey,
+      ...changes
+    } = buildFieldDefinitionColumns(payload);
+
+    return fieldDefinitionExecutor.update({ id: aggregateId, changes }, event.user, ctx.db, {
+      skipOptimisticLock: true,
+    });
+  },
+};

package/src/custom-fields/schemas.ts

@@ -83,6 +83,13 @@ export const defineFieldPayloadSchema = z.object({
 });
 export type DefineFieldPayload = z.infer<typeof defineFieldPayloadSchema>;
 
+// Payload für `update-tenant-field` — bewusst dieselbe Shape wie define
+// (Vollersatz-Semantik: der Edit-Screen schickt den kompletten neuen Stand;
+// entityName+fieldKey sind die Identität, type ist immutable und wird im
+// Handler gegen den Bestand geprüft).
+export const updateFieldPayloadSchema = defineFieldPayloadSchema;
+export type UpdateFieldPayload = DefineFieldPayload;
+
 // Payload für `delete-tenant-field` / `delete-system-field`.
 export const deleteFieldPayloadSchema = z.object({
   entityName: z.string().min(1).max(64),