@cosmicdrift/kumiko-bundled-features 0.12.2 → 0.13.0

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

@@ -0,0 +1,57 @@
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { customFieldsFeature } from "../feature";
+import { checkFieldAccessForWrite } from "../lib/field-access";
+
+export const clearCustomFieldPayloadSchema = z.object({
+  entityName: z.string().min(1).max(64),
+  entityId: z.string().min(1),
+  fieldKey: z.string().min(1).max(64),
+});
+export type ClearCustomFieldPayload = z.infer<typeof clearCustomFieldPayloadSchema>;
+
+// clear-custom-field — entfernt einen Custom-Field-Wert von einer host-
+// entity. Emittiert customField.cleared-Event; MSP entfernt key aus
+// jsonb-column (key-removal, nicht null-set).
+//
+// T1.5b: per-field fieldAccess.write gate — caller muss eine der definierten
+// Rollen halten falls fieldDefinition.serializedField.fieldAccess.write
+// gesetzt ist. Handler-level RBAC (TenantAdmin/Member) bleibt zusätzlich.
+export const clearCustomFieldHandler: WriteHandlerDef = {
+  name: "clear-custom-field",
+  schema: clearCustomFieldPayloadSchema,
+  access: { roles: ["TenantAdmin", "TenantMember"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as ClearCustomFieldPayload; // @cast-boundary engine-payload
+
+    const accessCheck = await checkFieldAccessForWrite(
+      ctx.db,
+      event.user.tenantId,
+      payload.entityName,
+      payload.fieldKey,
+      event.user.roles,
+    );
+    if (!accessCheck.ok) {
+      if (accessCheck.reason === "field_definition_not_found") {
+        return failNotFound("fieldDefinition", payload.fieldKey);
+      }
+      return failUnprocessable("field_access_denied", {
+        fieldKey: payload.fieldKey,
+        requiredRoles: accessCheck.requiredRoles ?? [],
+      });
+    }
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: payload.entityId,
+      aggregateType: payload.entityName,
+      type: customFieldsFeature.exports.clearedEvent.name,
+      payload: { fieldKey: payload.fieldKey },
+    });
+
+    return {
+      isSuccess: true as const,
+      data: { entityName: payload.entityName, entityId: payload.entityId },
+    };
+  },
+};

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

@@ -3,8 +3,10 @@ import {
   isSystemTenant,
   type WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
 import { fieldDefinitionEntity } from "../entity";
+import { countTenantFieldDefinitions } from "../lib/quota";
 import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas";
 
 const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
@@ -24,39 +26,74 @@ const { executor } = createEntityExecutor("field-definition", fieldDefinitionEnt
 // durch. Resolution beim Read (B2) zeigt dann den system-scope-Wert. v2
 // kann r.systemScope-Sub-Handler einführen um cross-scope-conflict am Write
 // abzulehnen.
-export const defineTenantFieldHandler: WriteHandlerDef = {
-  name: "define-tenant-field",
-  schema: defineFieldPayloadSchema,
-  access: { roles: ["TenantAdmin"] },
-  handler: async (event, ctx) => {
-    const payload = event.payload as DefineFieldPayload; // @cast-boundary engine-payload
-    const tenantId = event.user.tenantId;
-
-    // TenantAdmin darf NICHT system-scope schreiben — strict-guard.
-    if (isSystemTenant(tenantId)) {
-      throw new Error(
-        "define-tenant-field: tenantId is SYSTEM_TENANT_ID — use define-system-field for system-scope definitions",
+//
+// **Quota (T1.5e)**: optional `fieldDefinitionLimitPerTenant` gate. When the
+// tenant already has ≥ limit definitions, the handler rejects with
+// `unprocessable` + reason `cap_exceeded` BEFORE attempting the insert.
+// The factory below closes over the limit; the legacy const-export keeps
+// behavior unchanged for callers who didn't opt into a limit.
+export interface DefineTenantFieldOptions {
+  /** Hard quota — `>= limit` definitions per tenant rejects further defines. */
+  readonly fieldDefinitionLimitPerTenant?: number;
+}
+
+export function createDefineTenantFieldHandler(
+  opts: DefineTenantFieldOptions = {},
+): WriteHandlerDef {
+  const limit = opts.fieldDefinitionLimitPerTenant;
+  return {
+    name: "define-tenant-field",
+    schema: defineFieldPayloadSchema,
+    access: { roles: ["TenantAdmin"] },
+    handler: async (event, ctx) => {
+      const payload = event.payload as DefineFieldPayload; // @cast-boundary engine-payload
+      const tenantId = event.user.tenantId;
+
+      // TenantAdmin darf NICHT system-scope schreiben — strict-guard.
+      if (isSystemTenant(tenantId)) {
+        throw new Error(
+          "define-tenant-field: tenantId is SYSTEM_TENANT_ID — use define-system-field for system-scope definitions",
+        );
+      }
+
+      if (limit !== undefined) {
+        const current = await countTenantFieldDefinitions(ctx.db, tenantId);
+        if (current >= limit) {
+          return failUnprocessable("cap_exceeded", {
+            capName: "customFields.fieldDefinition.count",
+            limit,
+            current,
+          });
+        }
+      }
+
+      const aggregateId = fieldDefinitionAggregateId(
+        tenantId,
+        payload.entityName,
+        payload.fieldKey,
+      );
+
+      return executor.create(
+        {
+          id: aggregateId,
+          entityName: payload.entityName,
+          fieldKey: payload.fieldKey,
+          type: payload.serializedField.type,
+          required: payload.required,
+          searchable: payload.searchable,
+          displayOrder: payload.displayOrder,
+          serializedField: JSON.stringify({
+            ...payload.serializedField,
+            label: payload.label,
+          }),
+        },
+        event.user,
+        ctx.db,
       );
-    }
-
-    const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
-
-    return executor.create(
-      {
-        id: aggregateId,
-        entityName: payload.entityName,
-        fieldKey: payload.fieldKey,
-        type: payload.serializedField.type,
-        required: payload.required,
-        searchable: payload.searchable,
-        displayOrder: payload.displayOrder,
-        serializedField: JSON.stringify({
-          ...payload.serializedField,
-          label: payload.label,
-        }),
-      },
-      event.user,
-      ctx.db,
-    );
-  },
-};
+    },
+  };
+}
+
+// Backwards-compat: existing imports of `defineTenantFieldHandler` keep
+// working — the handler has no quota, identical to pre-T1.5e behavior.
+export const defineTenantFieldHandler: WriteHandlerDef = createDefineTenantFieldHandler();

package/src/custom-fields/handlers/delete-system-field.write.ts

@@ -5,6 +5,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
 import { fieldDefinitionEntity } from "../entity";
+import { customFieldsFeature } from "../feature";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
 
 const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
@@ -28,6 +29,19 @@ export const deleteSystemFieldHandler: WriteHandlerDef = {
     );
 
     const systemUser = { ...event.user, tenantId: SYSTEM_TENANT_ID };
-    return executor.delete({ id: aggregateId }, systemUser, ctx.db);
+    const result = await executor.delete({ id: aggregateId }, systemUser, ctx.db);
+
+    // Cascade-cleanup-Event — host-entity-MSPs entfernen orphan values aus
+    // ihrer customFields jsonb. Im selben TX = atomic.
+    if (result.isSuccess) {
+      await ctx.unsafeAppendEvent({
+        aggregateId,
+        aggregateType: "field-definition",
+        type: customFieldsFeature.exports.fieldDefinitionDeletedEvent.name,
+        payload: { entityName: payload.entityName, fieldKey: payload.fieldKey },
+      });
+    }
+
+    return result;
   },
 };

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

@@ -5,6 +5,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
 import { fieldDefinitionEntity } from "../entity";
+import { customFieldsFeature } from "../feature";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
 
 const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
@@ -35,6 +36,20 @@ export const deleteTenantFieldHandler: WriteHandlerDef = {
 
     const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
 
-    return executor.delete({ id: aggregateId }, event.user, ctx.db);
+    const result = await executor.delete({ id: aggregateId }, event.user, ctx.db);
+
+    // Emit cascade-cleanup-Event NACH erfolgreichem Delete. host-entity-MSPs
+    // (registriert via wireCustomFieldsFor) konsumieren das + entfernen orphan
+    // values aus ihrer customFields jsonb. Im selben TX = atomic cleanup.
+    if (result.isSuccess) {
+      await ctx.unsafeAppendEvent({
+        aggregateId,
+        aggregateType: "field-definition",
+        type: customFieldsFeature.exports.fieldDefinitionDeletedEvent.name,
+        payload: { entityName: payload.entityName, fieldKey: payload.fieldKey },
+      });
+    }
+
+    return result;
   },
 };

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

@@ -0,0 +1,77 @@
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { customFieldsFeature } from "../feature";
+import { checkFieldAccessForWrite } from "../lib/field-access";
+
+export const setCustomFieldPayloadSchema = z.object({
+  entityName: z.string().min(1).max(64),
+  entityId: z.string().min(1),
+  fieldKey: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
+  value: z.unknown(),
+});
+export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
+
+// set-custom-field — schreibt einen Custom-Field-Wert auf eine host-entity.
+//
+// **ES-Option-B**: emittiert customField.set-Event auf dem host-aggregate
+// stream (aggregateType = host-entity-name, aggregateId = host-entity-id).
+// Last-Wins-Semantik: customField.set wird OHNE expectedVersion appended,
+// concurrent writes auf gleiches Field gehen beide durch (Plan-Doc v2
+// Concurrency-Tabelle).
+//
+// **WAS DIESER HANDLER NICHT MACHT (yet)**:
+//   - Validation des Werts gegen fieldDefinition-type (B2-todo: rehydriere
+//     r.field.X() aus serializedField, .schema.safeParse(value))
+//   - cap-counter-quota-Check (T1.5e)
+// → Diese Aspekte kommen als Folgekommits oder durch consumer-side hooks.
+//
+// **WAS NEU IST (T1.5b)**:
+//   - field-access-check: wenn fieldDefinition.serializedField.fieldAccess.write
+//     gesetzt ist, muss der calling user mindestens eine der Rollen halten.
+//     Handler-level RBAC (TenantAdmin/Member) bleibt zusätzlich.
+export const setCustomFieldHandler: WriteHandlerDef = {
+  name: "set-custom-field",
+  schema: setCustomFieldPayloadSchema,
+  access: { roles: ["TenantAdmin", "TenantMember"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as SetCustomFieldPayload; // @cast-boundary engine-payload
+
+    const accessCheck = await checkFieldAccessForWrite(
+      ctx.db,
+      event.user.tenantId,
+      payload.entityName,
+      payload.fieldKey,
+      event.user.roles,
+    );
+    if (!accessCheck.ok) {
+      if (accessCheck.reason === "field_definition_not_found") {
+        return failNotFound("fieldDefinition", payload.fieldKey);
+      }
+      return failUnprocessable("field_access_denied", {
+        fieldKey: payload.fieldKey,
+        requiredRoles: accessCheck.requiredRoles ?? [],
+      });
+    }
+
+    // Emit customField.set on host-aggregate stream. unsafeAppendEvent
+    // (statt strict appendEvent) weil event-type-map keine cross-feature-
+    // augmentation für diesen event-typ hat — wir nutzen den qualified
+    // string-namen direkt.
+    await ctx.unsafeAppendEvent({
+      aggregateId: payload.entityId,
+      aggregateType: payload.entityName,
+      type: customFieldsFeature.exports.setEvent.name,
+      payload: { fieldKey: payload.fieldKey, value: payload.value },
+    });
+
+    return {
+      isSuccess: true as const,
+      data: { entityName: payload.entityName, entityId: payload.entityId },
+    };
+  },
+};

package/src/custom-fields/index.ts

@@ -1,17 +1,32 @@
 export { fieldDefinitionAggregateId } from "./aggregate-id";
 export {
+  CUSTOM_FIELDS_EXTENSION,
   CUSTOM_FIELDS_FEATURE_NAME,
   FIELD_DEFINITION_CREATED_EVENT,
-  FIELD_DEFINITION_DELETED_EVENT,
   FIELD_DEFINITION_UPDATED_EVENT,
   SUPPORTED_FIELD_TYPES,
   type SupportedFieldType,
 } from "./constants";
 export { fieldDefinitionEntity } from "./entity";
-export { createCustomFieldsFeature } from "./feature";
+export {
+  type CustomFieldClearedPayload,
+  type CustomFieldSetPayload,
+  customFieldClearedSchema,
+  customFieldSetSchema,
+} from "./events";
+export { createCustomFieldsFeature, customFieldsFeature } from "./feature";
+export {
+  type ClearCustomFieldPayload,
+  clearCustomFieldPayloadSchema,
+} from "./handlers/clear-custom-field.write";
+export {
+  type SetCustomFieldPayload,
+  setCustomFieldPayloadSchema,
+} from "./handlers/set-custom-field.write";
 export {
   type DefineFieldPayload,
   type DeleteFieldPayload,
   defineFieldPayloadSchema,
   deleteFieldPayloadSchema,
 } from "./schemas";
+export { customFieldsField, wireCustomFieldsFor } from "./wire-for-entity";

package/src/custom-fields/lib/field-access.ts

@@ -0,0 +1,75 @@
+// T1.5b — per-field write access-check for the set/clear handlers.
+//
+// Loads a fieldDefinition by (tenantId, entityName, fieldKey), reads its
+// `serializedField.fieldAccess.write` array, and verifies the calling user
+// holds at least one of the listed roles. When `fieldAccess.write` is
+// absent or empty the handler-level RBAC is the only gate.
+
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { sql } from "drizzle-orm";
+import { parseSerializedField } from "./parse-serialized-field";
+
+export type FieldAccessCheckResult =
+  | { ok: true }
+  | {
+      ok: false;
+      reason: "field_definition_not_found" | "field_access_denied";
+      requiredRoles?: ReadonlyArray<string>;
+    };
+
+// Resolution mirrors the Plan-Doc v2 system+tenant UNION: the active
+// definition for a fieldKey on an entity is either system-scope or
+// tenant-scope, never both (B1 conflict-rule). The tenant-scoped row sits
+// in the caller's tenantId; system-scoped rows would sit under
+// SYSTEM_TENANT_ID. B1 only ships the tenant-scoped pipeline, so we only
+// query the caller's tenant — system-scope lookup will land in B2.
+async function loadSerializedField(
+  db: TenantDb,
+  tenantId: string,
+  entityName: string,
+  fieldKey: string,
+): Promise<unknown | null> {
+  // TenantDb's tenant-filtered API doesn't expose raw SQL — for this
+  // single-row lookup we drop down to the underlying DbRunner. tenantId
+  // is still pinned in the WHERE clause so we don't lose isolation.
+  const rows = await db.raw.execute(sql`
+    SELECT serialized_field
+    FROM read_custom_field_definitions
+    WHERE entity_name = ${entityName}
+      AND field_key = ${fieldKey}
+      AND tenant_id = ${tenantId}
+    LIMIT 1
+  `);
+  const first = (rows as ReadonlyArray<Record<string, unknown>>)[0]; // @cast-boundary db-row
+  return first ? (first["serialized_field"] ?? null) : null;
+}
+
+// Per Plan-Doc T1.5b: an empty / undefined `write` array means the field
+// inherits the handler-level RBAC unchanged. Only an explicit non-empty
+// list constrains. Intersection is role-name equality (case-sensitive).
+export async function checkFieldAccessForWrite(
+  db: TenantDb,
+  tenantId: string,
+  entityName: string,
+  fieldKey: string,
+  userRoles: ReadonlyArray<string>,
+): Promise<FieldAccessCheckResult> {
+  const serialized = await loadSerializedField(db, tenantId, entityName, fieldKey);
+  if (serialized === null) {
+    return { ok: false, reason: "field_definition_not_found" };
+  }
+
+  const parsed = parseSerializedField(serialized);
+  // skip: corrupt serialized_field on disk → treat as no-access-restriction
+  // rather than 500. Loader already returned null on missing row, so a
+  // null here means parse-failure on a present row; behave like an open
+  // field (next gate is the handler-level RBAC).
+  if (!parsed) return { ok: true };
+
+  const required = parsed.fieldAccess?.write;
+  if (!required || required.length === 0) {
+    return { ok: true };
+  }
+  const hit = userRoles.some((role) => required.includes(role));
+  return hit ? { ok: true } : { ok: false, reason: "field_access_denied", requiredRoles: required };
+}

package/src/custom-fields/lib/parse-serialized-field.ts

@@ -0,0 +1,45 @@
+// Centralised parser for `fieldDefinition.serializedField`.
+//
+// The column is stored as `text` in B1 (entity.ts) — what the db row hands
+// back depends on the driver: postgres-js returns text as a `string`, but
+// jsonb-tolerant drivers and middleware can deliver an already-parsed
+// object. This helper normalises both, validates the shape, and centralises
+// the single boundary cast so callers don't sprinkle `as { … }`-narrowings
+// across the bundle.
+//
+// All structured `serializedField`-keys recognised today (`fieldAccess`,
+// `sensitive`, `retention`) live on this shape. New keys go here so the
+// other call-sites can read them via the typed result instead of re-parsing.
+
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+
+export interface SerializedFieldShape {
+  readonly type: string;
+  readonly fieldAccess?: {
+    readonly read?: ReadonlyArray<string>;
+    readonly write?: ReadonlyArray<string>;
+  };
+  readonly sensitive?: boolean;
+  readonly retention?: {
+    readonly keepFor: string;
+    readonly strategy: "delete" | "anonymize";
+  };
+}
+
+function isShape(v: unknown): v is SerializedFieldShape {
+  if (!v || typeof v !== "object") return false;
+  // `in` narrows v's type from `object` to `object & { type: unknown }` so
+  // the property access below does not need a cast.
+  if (!("type" in v)) return false;
+  return typeof v.type === "string";
+}
+
+/**
+ * Normalises the row's `serialized_field` column. Returns `null` for
+ * absent/corrupt rows so callers can short-circuit cleanly without
+ * having to mirror the safe-json fallback semantics themselves.
+ */
+export function parseSerializedField(raw: unknown): SerializedFieldShape | null {
+  const parsed = typeof raw === "string" ? parseJsonSafe<unknown>(raw, null) : raw;
+  return isShape(parsed) ? parsed : null;
+}

package/src/custom-fields/lib/quota.ts

@@ -0,0 +1,28 @@
+// T1.5e — per-tenant fieldDefinition quota.
+//
+// `countTenantFieldDefinitions(db, tenantId)` runs a single COUNT(*) against
+// `read_custom_field_definitions` scoped to the caller's tenant. The
+// `define-tenant-field` handler consults this before insert and rejects
+// with `cap_exceeded` once a configurable per-tenant ceiling is reached.
+//
+// This is a simple projection-count rather than a `cap-counter`-bundle
+// counter, because the read-projection is the authoritative source
+// (soft-deleted rows already drop out) and we don't need rolling-window
+// semantics. A future iteration can swap to `cap-counter` if pricing
+// wants e.g. monthly-roll definition allowances.
+
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { sql } from "drizzle-orm";
+
+export async function countTenantFieldDefinitions(db: TenantDb, tenantId: string): Promise<number> {
+  const rowsResult = await db.raw.execute(sql`
+    SELECT COUNT(*)::int AS n
+    FROM read_custom_field_definitions
+    WHERE tenant_id = ${tenantId}
+  `);
+  const rows = rowsResult as ReadonlyArray<Record<string, unknown>>; // @cast-boundary db-row
+  const first = rows[0];
+  if (!first) return 0;
+  const n = first["n"];
+  return typeof n === "number" ? n : Number.parseInt(String(n ?? 0), 10);
+}