@cosmicdrift/kumiko-bundled-features 0.12.2 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # @cosmicdrift/kumiko-bundled-features
 
+## 0.13.0
+
+### Minor Changes
+
+- 7f56b2f: **Framework**: add `JsonbFieldDef` + `createJsonbField()` primitive. Schema-less jsonb-Spalte (default `{}`, NOT NULL) für tenant-defined extension-data, AI-inferred metadata, free-form config-blobs. Vs. `embedded` (typed sub-schema): jsonb akzeptiert beliebige keys. Table-builder + schema-builder + e2e-generator alle aktualisiert.
+
+  **custom-fields-Bundle (B2)**: ergänzt B1 um Custom-Field-VALUES:
+
+  - `customField.set` + `customField.cleared` Event-Types (auf host-aggregate stream)
+  - `set-custom-field` + `clear-custom-field` write-handlers (emit events)
+  - `r.extendsRegistrar("customFields")` für consumer opt-in via `useExtension`
+  - `customFieldsField()` helper für entity-fields-definition
+  - `wireCustomFieldsFor(r, entityName, entityTable)` consumer-side-API registriert:
+    - `r.useExtension("customFields", entity)` opt-in marker
+    - MultiStreamProjection: customField.set/.cleared/fieldDefinition.deleted → UPDATE entityTable.customFields jsonb (jsonb_set / minus-operator)
+    - `r.entityHook("postQuery", entity, ...)` — flatten row.customFields auf API-root (Spec-Promise "indistinguishable von Stammfeldern")
+    - `r.searchPayloadExtension(entity, ...)` — customFields-keys flach ins Meilisearch-Index (F3 wiring)
+
+  **Out-of-B2** (future iterations): cross-scope-conflict (tenant override system fieldKey), cap-counter quota, user-data-rights anonymization, value-validation gegen fieldDefinition.serializedField, system+tenant UNION-read.
+
+  Part of custom-fields-bundle Sprint Phase B2 (Plan-Doc: kumiko-platform/docs/plans/custom-fields-sprint.md).
+
+- 9121928: T1 — integration tests for custom-fields bundle. 6 full-stack scenarios via setupTestStack:
+
+  - Define field → set value → query: customField lands flat in entity-response (postQuery hook + MSP)
+  - Clear: fieldKey gone from response after clear-custom-field
+  - Multiple fields on same entity: all merge flat
+  - Entity without customField values: still queryable
+  - fieldDefinition-delete cascade: orphan values removed from all entity-rows via MSP
+  - Last-Wins on concurrent set: last value wins (unsafeAppendEvent without expectedVersion)
+
+  Plus bugfix: Event-short-name-constants haben jetzt kebab-dashes statt Punkten (toKebab collapsed dots → Registry-Drift bei type-string-templates).
+
+- 72518fa: custom-fields: per-field `fieldAccess.write` enforcement (T1.5b).
+
+  `set-custom-field` and `clear-custom-field` handlers now read `fieldDefinition.serializedField.fieldAccess.write[]` and reject with `unprocessable` + `reason: "field_access_denied"` when the caller's roles do not intersect. Handler-level RBAC (TenantAdmin/Member) keeps applying on top.
+
+  When `fieldAccess.write` is absent or empty, behavior is unchanged — existing consumers stay green without code changes.
+
+  `serializedField` schema gains the optional `fieldAccess: { read?: string[], write?: string[] }` shape (read is reserved for T1.5c).
+
+- 0a00e7b: custom-fields: user-data-rights wiring (T1.5c).
+
+  New `wireCustomFieldsUserDataRightsFor(r, { entityName, entityTable, userIdColumn })` opt-in helper. Registers a second `r.useExtension(EXT_USER_DATA, ...)` for the host entity whose hooks handle the customFields jsonb under DSGVO Art. 15+17+20:
+
+  - **Export**: every row owned by the user contributes its customFields jsonb into the export bundle under `<entity>.customFields`.
+  - **Forget anonymize**: sensitive customFields keys (declared via `serializedField.sensitive: true`) are stripped from the jsonb. Non-sensitive keys stay.
+  - **Forget delete**: no-op — the host entity's own user-data-rights hook removes the row, jsonb travels with it.
+
+  `serializedField` gains optional `sensitive: boolean` alongside `fieldAccess` (T1.5b).
+
+- aca1443: custom-fields: per-field retention sweep (T1.5d).
+
+  New `runCustomFieldsRetention(opts)` walks one host entity's rows and strips/nulls customField values whose host-row `modified_at` is older than the per-field `retention.keepFor` policy. Strategy `delete` removes the key; `anonymize` sets it to `null`.
+
+  `serializedField` gains optional `retention: { keepFor: string; strategy: "delete" | "anonymize" }`.
+
+  Designed to run alongside (or inside) the data-retention bundle's daily cron. No auto-registration — the consumer chooses the schedule and which host entities to sweep.
+
+- c6cb96c: custom-fields: per-tenant fieldDefinition quota (T1.5e).
+
+  `createCustomFieldsFeature({ fieldDefinitionLimitPerTenant: N })` installs a quota-aware `define-tenant-field` handler. The handler runs a `COUNT(*)` on `read_custom_field_definitions` per tenant before insert and rejects with `unprocessable` + `reason: cap_exceeded` once the limit is reached.
+
+  Cap is per-tenant total (across all entity-names), not per entity-name — the natural unit for tier-pricing.
+
+  Without the option, behavior is unchanged: the singleton feature and its handler retain pre-T1.5e semantics.
+
+### Patch Changes
+
+- 68b8118: custom-fields: typed `eventDef.name` pattern statt Template-Literal-Konstruktion.
+
+  `createCustomFieldsFeature()` returnt jetzt typed `exports` (`setEvent`, `clearedEvent`, `fieldDefinitionDeletedEvent`). Handler + `wireCustomFieldsFor` nutzen `customFieldsFeature.exports.<event>.name` als compile-time literal-typed qualified-string — keine hand-gebauten `${FEATURE}:event:${SHORT}`-Strings mehr.
+
+  Rationale: T1 hat den toKebab-collapse-Bug aufgedeckt (Dots in short-names kollabieren zu Dashes → Registry-Mismatch bei hand-gebauten Strings). Mit dem refactor wird die Drift compile-time-strukturell unmöglich (siehe Memory feedback_event_def_exports_pattern).
+
+  Kein API-Change für consumers: `createCustomFieldsFeature()` bleibt unverändert; zusätzlicher named export `customFieldsFeature` (Singleton) ist additiv.
+
+- 3d5e9ef: `kumiko-schema-check` CLI — Empfehlung 3 aus Sprint-9.8-Retro
+  (`luminous-watching-moler.md`). Diff't APP_FEATURES (runtime, aus
+  `src/run-config.ts`) gegen FEATURE_IMPORT_REGISTRY (statisch, aus
+  `drizzle/generate.ts`). Fängt Studio's 9.8-Drama: registry 18 features
+  hinter APP_FEATURES → migrations fehlten für mounted features.
+
+  Usage (im app-workspace):
+
+  ```sh
+  bunx kumiko-schema-check
+  # or with custom paths:
+  bunx kumiko-schema-check --run-config src/run-config.ts --generate drizzle/generate.ts
+  ```
+
+  Plus: 5 bundled-features hatten camelCase feature-names statt kebab-case
+  (Memory `feedback_kebab_aggregates`) — aufgedeckt durch den schema-check
+  gegen use-all-bundled. Fix: `channelEmail` → `channel-email`,
+  `channelInApp` → `channel-in-app`, `channelPush` → `channel-push`,
+  `rateLimiting` → `rate-limiting`, `rendererSimple` → `renderer-simple`.
+
+  Plus `CHANNEL_IN_APP_FEATURE` und `RATE_LIMITING_FEATURE` Konstanten
+  angepasst (waren intern auf camelCase, jetzt kebab-case).
+
+- Updated dependencies [7f56b2f]
+  - @cosmicdrift/kumiko-framework@0.13.0
+  - @cosmicdrift/kumiko-renderer@0.13.0
+  - @cosmicdrift/kumiko-dispatcher-live@0.13.0
+  - @cosmicdrift/kumiko-renderer-web@0.13.0
+
 ## 0.12.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.12.2",
+  "version": "0.13.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>",
@@ -75,10 +75,10 @@
     "@aws-sdk/client-s3": "^3.1045.0",
     "@aws-sdk/lib-storage": "^3.1045.0",
     "@aws-sdk/s3-request-presigner": "^3.1045.0",
-    "@cosmicdrift/kumiko-dispatcher-live": "0.12.2",
-    "@cosmicdrift/kumiko-framework": "0.12.2",
-    "@cosmicdrift/kumiko-renderer": "0.12.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.12.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.13.0",
+    "@cosmicdrift/kumiko-framework": "0.13.0",
+    "@cosmicdrift/kumiko-renderer": "0.13.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.13.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/channel-email/feature.ts

@@ -4,7 +4,7 @@ import { createEmailChannel, type EmailChannelOptions } from "./email-channel";
 export function createChannelEmailFeature(options: EmailChannelOptions): FeatureDefinition {
   const channel = createEmailChannel(options);
 
-  return defineFeature("channelEmail", (r) => {
+  return defineFeature("channel-email", (r) => {
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "email", {

package/src/channel-in-app/constants.ts

@@ -1,4 +1,4 @@
-export const CHANNEL_IN_APP_FEATURE = "channelInApp" as const;
+export const CHANNEL_IN_APP_FEATURE = "channel-in-app" as const;
 
 export const InAppHandlers = {
   markRead: "channel-in-app:write:mark-read",

package/src/channel-in-app/feature.ts

@@ -6,7 +6,7 @@ import { unreadCountQuery } from "./handlers/unread-count.query";
 import { inAppChannel } from "./in-app-channel";
 
 export function createChannelInAppFeature(): FeatureDefinition {
-  return defineFeature("channelInApp", (r) => {
+  return defineFeature("channel-in-app", (r) => {
     r.requires("delivery");
 
     // Register as delivery channel via extension system

package/src/channel-push/feature.ts

@@ -4,7 +4,7 @@ import { createPushChannel, type PushChannelOptions } from "./push-channel";
 export function createChannelPushFeature(options: PushChannelOptions): FeatureDefinition {
   const channel = createPushChannel(options);
 
-  return defineFeature("channelPush", (r) => {
+  return defineFeature("channel-push", (r) => {
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "push", {

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

@@ -0,0 +1,277 @@
+// T1.5a — Audit cross-feature integration for custom-fields.
+//
+// Verifies that all custom-field write-actions (define-tenant-field,
+// set-custom-field, clear-custom-field, delete-tenant-field) emit events
+// that are visible via the `audit:query:list` handler — without any extra
+// wiring between the bundles.
+//
+// The promise: customField writes go through the event-store like any
+// other entity write, so the audit-bundle (which queries the events table
+// directly) picks them up automatically. This suite is the evidence that
+// the promise holds end-to-end.
+
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createEntityExecutor,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { AuditQueries } from "../../audit/constants";
+import { createAuditFeature } from "../../audit/feature";
+import { fieldDefinitionEntity } from "../entity";
+import { createCustomFieldsFeature } from "../feature";
+import { customFieldsField, wireCustomFieldsFor } from "../wire-for-entity";
+
+const propertyEntity = createEntity({
+  table: "read_t15a_properties",
+  fields: {
+    name: createTextField({ required: true }),
+    customFields: customFieldsField(),
+  },
+});
+const propertyTable = buildDrizzleTable("property", propertyEntity);
+
+const propertyFeature = defineFeature("property-t15a", (r) => {
+  r.entity("property", propertyEntity);
+  r.requires("custom-fields");
+  wireCustomFieldsFor(r, "property", propertyTable);
+
+  const { executor } = createEntityExecutor("property", propertyEntity);
+  r.writeHandler({
+    name: "property:create",
+    schema: z.object({ id: z.string(), name: z.string() }),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (event, ctx) =>
+      executor.create(
+        { id: event.payload.id, name: event.payload.name, customFields: {} },
+        event.user,
+        ctx.db,
+      ),
+  });
+});
+
+const customFieldsFeature = createCustomFieldsFeature();
+
+// Tenant-admin role for custom-fields handlers + audit. Audit's listQuery
+// allows `Admin` and `SystemAdmin`; we add `TenantAdmin` to a single user
+// because rotating user-identities mid-test would split the audit trail.
+const adminWithAudit = createTestUser({ roles: ["TenantAdmin", "Admin"] });
+
+// Distinct-tenant user for the isolation test — same tenant as `adminWithAudit`
+// would defeat the purpose. `TestUsers.otherTenant` is `testTenantId(2)`,
+// `adminWithAudit` defaults to `testTenantId(1)` via `TestUsers.admin`.
+const otherTenantAdmin = TestUsers.otherTenant;
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [customFieldsFeature, propertyFeature, createAuditFeature()],
+  });
+  await unsafeCreateEntityTable(stack.db, fieldDefinitionEntity);
+  await unsafeCreateEntityTable(stack.db, propertyEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetEventStore(stack);
+  await stack.db.execute(sql`DELETE FROM read_t15a_properties`);
+  await stack.db.execute(sql`DELETE FROM read_custom_field_definitions`);
+});
+
+type AuditRow = {
+  id: string;
+  aggregateId: string;
+  aggregateType: string;
+  type: string;
+  createdBy: string;
+  payload: Record<string, unknown>;
+};
+type AuditResponse = { rows: AuditRow[]; nextBefore: string | null };
+
+async function listAudit(filter: { eventType?: string; aggregateType?: string } = {}) {
+  return stack.http.queryOk<AuditResponse>(AuditQueries.list, filter, adminWithAudit);
+}
+
+describe("T1.5a: custom-fields events are visible in the audit log", () => {
+  test("define-tenant-field emits an event the audit query returns", async () => {
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "internalNumber",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      adminWithAudit,
+    );
+
+    const res = await listAudit({ aggregateType: "field-definition" });
+
+    // The fieldDefinition is created via r.entity + r.crud, so the event-type
+    // follows the entity-CRUD convention `<entity>.created` (with a dot),
+    // not the feature-emit-via-defineEvent convention used by set/cleared
+    // (`custom-fields:event:<short>`).
+    const created = res.rows.find((r) => r.type === "field-definition.created");
+    expect(created).toBeDefined();
+    expect(created?.createdBy).toBe(String(adminWithAudit.id));
+    expect(created?.payload["fieldKey"]).toBe("internalNumber");
+  });
+
+  test("set-custom-field emits a customField.set event on the host-aggregate stream", async () => {
+    const propertyId = "11111111-1111-4000-8000-000000000001";
+
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "internalNumber",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      adminWithAudit,
+    );
+    await stack.http.writeOk(
+      "property-t15a:write:property:create",
+      { id: propertyId, name: "Hofgarten 12" },
+      adminWithAudit,
+    );
+    await stack.http.writeOk(
+      "custom-fields:write:set-custom-field",
+      { entityName: "property", entityId: propertyId, fieldKey: "internalNumber", value: "X-42" },
+      adminWithAudit,
+    );
+
+    const res = await listAudit({ aggregateType: "property" });
+
+    const setEvent = res.rows.find((r) => r.type === "custom-fields:event:custom-field-set");
+    expect(setEvent).toBeDefined();
+    expect(setEvent?.aggregateId).toBe(propertyId);
+    expect(setEvent?.payload["fieldKey"]).toBe("internalNumber");
+    expect(setEvent?.payload["value"]).toBe("X-42");
+    expect(setEvent?.createdBy).toBe(String(adminWithAudit.id));
+  });
+
+  test("clear-custom-field emits a customField.cleared event with the fieldKey", async () => {
+    const propertyId = "22222222-2222-4000-8000-000000000002";
+
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "vipFlag",
+        serializedField: { type: "boolean" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      adminWithAudit,
+    );
+    await stack.http.writeOk(
+      "property-t15a:write:property:create",
+      { id: propertyId, name: "BookStore" },
+      adminWithAudit,
+    );
+    await stack.http.writeOk(
+      "custom-fields:write:set-custom-field",
+      { entityName: "property", entityId: propertyId, fieldKey: "vipFlag", value: true },
+      adminWithAudit,
+    );
+    await stack.http.writeOk(
+      "custom-fields:write:clear-custom-field",
+      { entityName: "property", entityId: propertyId, fieldKey: "vipFlag" },
+      adminWithAudit,
+    );
+
+    const res = await listAudit({ aggregateType: "property" });
+
+    const clearedEvent = res.rows.find(
+      (r) => r.type === "custom-fields:event:custom-field-cleared",
+    );
+    expect(clearedEvent).toBeDefined();
+    expect(clearedEvent?.aggregateId).toBe(propertyId);
+    expect(clearedEvent?.payload["fieldKey"]).toBe("vipFlag");
+  });
+
+  test("delete-tenant-field emits a fieldDefinition.deleted event", async () => {
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "ephemeral",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      adminWithAudit,
+    );
+    await stack.http.writeOk(
+      "custom-fields:write:delete-tenant-field",
+      { entityName: "property", fieldKey: "ephemeral" },
+      adminWithAudit,
+    );
+
+    const res = await listAudit({ aggregateType: "field-definition" });
+
+    const deletedEvent = res.rows.find(
+      (r) => r.type === "custom-fields:event:field-definition-deleted",
+    );
+    expect(deletedEvent).toBeDefined();
+    expect(deletedEvent?.payload["fieldKey"]).toBe("ephemeral");
+    expect(deletedEvent?.payload["entityName"]).toBe("property");
+  });
+
+  test("tenant isolation: audit list never returns custom-field events from other tenants", async () => {
+    // adminWithAudit is on testTenantId(1), otherTenantAdmin is on
+    // testTenantId(2). The field define lands on tenant-1; querying audit
+    // as tenant-2's admin must surface zero rows for it. Proves that the
+    // existing tenant-isolation in the audit query
+    // (`eq(eventsTable.tenantId, query.user.tenantId)`) covers custom-field
+    // events too — no extra wiring required.
+    expect(adminWithAudit.tenantId).not.toBe(otherTenantAdmin.tenantId);
+
+    await stack.http.writeOk(
+      "custom-fields:write:define-tenant-field",
+      {
+        entityName: "property",
+        fieldKey: "leakyField",
+        serializedField: { type: "text" },
+        required: false,
+        searchable: false,
+        displayOrder: 0,
+      },
+      adminWithAudit,
+    );
+
+    const res = await stack.http.queryOk<AuditResponse>(
+      AuditQueries.list,
+      { aggregateType: "field-definition" },
+      otherTenantAdmin,
+    );
+
+    const leak = res.rows.find((r) => (r.payload["fieldKey"] as string) === "leakyField");
+    expect(leak).toBeUndefined();
+  });
+});