@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/custom-fields-basic.md

@@ -0,0 +1,314 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/custom-fields-basic. Do not edit. -->
+
+# custom-fields-basic
+
+Tenant-defined extra fields on an entity without writing migrations.
+
+## README
+
+# Custom fields
+
+Let a tenant add their own fields to your entity at runtime — without
+writing a migration, without rebuilding your handler, without a code
+change. The recipe wires a `property` entity into the `custom-fields`
+bundle and drives a full *define → set → read* roundtrip.
+
+The result: the tenant defines `internalNumber: text`, sets it on a
+property, and reads it back flattened onto the row — looking exactly
+like a first-class column.
+
+## What it shows
+
+- **`customFieldsField()`** — a jsonb column factory that holds the
+  per-row custom field values. Add it to any entity you want
+  custom-field-capable.
+- **`wireCustomFieldsFor(r, entityName, table)`** — wires the
+  bundle's projection: a multi-stream projection consumes
+  `customField.set` / `.cleared` events and writes them into the
+  jsonb column, and an entity-postQuery hook flattens the jsonb onto
+  the row at read-time.
+- **No migrations at runtime** — the schema for custom fields lives
+  in two bundled tables (`field-definition` for the spec, jsonb on
+  the host row for the values). Defining a field is a write, not a
+  DDL.
+- **Stammfeld-look on the response** — reads return `{ id, name,
+  internalNumber: "X-2042" }`. The consumer can't tell which fields
+  are first-class and which are custom.
+
+## Feature composition
+
+```
+custom-fields          → core bundle: events + write-handlers + MSP +
+                         field-definition entity
+property-management    → our feature: opts the `property` entity into
+                         custom-fields via wireCustomFieldsFor
+```
+
+The `property-management` feature `r.requires("custom-fields")` — the
+bundle is non-optional for this recipe because the wired entity would
+otherwise have an empty jsonb column and no way to write into it.
+
+## Flow
+
+1. Tenant admin calls `custom-fields:write:define-tenant-field` to
+   declare `internalNumber: text` on `property`.
+2. App code creates a `property` row via
+   `property-management:write:property:create`.
+3. Tenant admin calls `custom-fields:write:set-custom-field` with the
+   `entityId`, `fieldKey: "internalNumber"`, `value: "X-2042"`.
+4. The bundle's MSP consumes the `customField.set` event and writes
+   the value into the property row's `customFields` jsonb column.
+5. The next `property-management:query:property:list` returns the row
+   with `internalNumber: "X-2042"` flattened onto the response — the
+   entity-postQuery hook merges the jsonb keys onto the row root.
+
+## When to reach for it
+
+You ship a SaaS where every tenant wants one or two of their own
+columns — internal IDs, vendor names, custom flags — and you don't
+want to either ship them all as `extraFields1..extraFields5` or push
+the tenant to a request-a-feature queue. Custom fields cover the
+single-or-handful-of-extra-fields case without engineering
+involvement.
+
+If you need the field to drive business logic (`if vipFlag then ...`),
+make it a first-class field instead — see [`basic-entity`](../basic-entity/).
+
+## Tests
+
+The integration test under `src/__tests__/` walks two scenarios:
+
+- Tenant defines a text field, sets a value, reads it back flat.
+- Tenant defines a number field, sets it, reads it back with the
+  number type preserved.
+
+```bash
+bun kumiko test integration samples/custom-fields-basic
+```
+
+## Source
+
+The feature is ~80 lines (`src/feature.ts`). The integration test is
+~110 lines (`src/__tests__/feature.integration.test.ts`).
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Custom-Fields Basic — integration test.
+//
+// Proves the full define → set → read roundtrip via the real dispatcher,
+// MSP-pipeline and DB:
+//   1. tenant defines `internalNumber` on `property`
+//   2. property is created
+//   3. customField is set → MSP writes into jsonb
+//   4. list-query returns the value flattened onto the row
+//
+// This is the smallest evidence that wireCustomFieldsFor + the bundle's
+// projection-hook + entity-postQuery flattening all line up.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  createCustomFieldsFeature,
+  fieldDefinitionEntity,
+} from "@cosmicdrift/kumiko-bundled-features/custom-fields";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { propertyEntity, propertyFeature } from "../feature";
+
+const admin = createTestUser({ roles: ["TenantAdmin"] });
+const customFields = createCustomFieldsFeature();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [customFields, propertyFeature] });
+  await unsafeCreateEntityTable(stack.db, fieldDefinitionEntity);
+  await unsafeCreateEntityTable(stack.db, propertyEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM kumiko_events`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM read_sample_cf_properties`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM read_custom_field_definitions`);
+});
+
+async function defineField(fieldKey: string, type = "text") {
+  return stack.http.writeOk(
+    "custom-fields:write:define-tenant-field",
+    {
+      entityName: "property",
+      fieldKey,
+      serializedField: { type },
+      required: false,
+      searchable: false,
+      displayOrder: 0,
+    },
+    admin,
+  );
+}
+
+async function setField(entityId: string, fieldKey: string, value: unknown) {
+  return stack.http.writeOk(
+    "custom-fields:write:set-custom-field",
+    { entityName: "property", entityId, fieldKey, value },
+    admin,
+  );
+}
+
+async function listProperties() {
+  return (await stack.http.queryOk("property-management:query:property:list", {}, admin)) as {
+    rows: Array<Record<string, unknown>>;
+  };
+}
+
+describe("custom-fields-basic recipe — define + set + read", () => {
+  test("tenant-defined field lands flat on the entity response", async () => {
+    const id = "11111111-1111-4000-8000-000000000001";
+
+    await defineField("internalNumber");
+    await stack.http.writeOk(
+      "property-management:write:property:create",
+      { id, name: "Hofgarten 12" },
+      admin,
+    );
+    await setField(id, "internalNumber", "X-2042");
+    await stack.eventDispatcher?.runOnce();
+
+    const { rows } = await listProperties();
+    const property = rows.find((row) => row["id"] === id);
+    expect(property?.["internalNumber"]).toBe("X-2042");
+  });
+
+  test("typed field: number value preserves its type", async () => {
+    const id = "22222222-2222-4000-8000-000000000002";
+
+    await defineField("tier", "number");
+    await stack.http.writeOk(
+      "property-management:write:property:create",
+      { id, name: "MultiField" },
+      admin,
+    );
+    await setField(id, "tier", 2);
+    await stack.eventDispatcher?.runOnce();
+
+    const property = (await listProperties()).rows.find((row) => row["id"] === id);
+    expect(property?.["tier"]).toBe(2);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// kumiko-feature-version: 1
+// Custom-Fields Basic Sample
+//
+// Shows how a feature opts a tenant-owned entity into the custom-fields
+// extension: tenants can define their own fields at runtime, set values
+// per row, and read them back flattened onto the entity — without writing
+// a single migration or extra handler.
+//
+// Flow:
+//   1. App-author defines a `property` entity and wires it via
+//      `wireCustomFieldsFor(r, "property", propertyTable)`.
+//   2. A tenant admin defines a field at runtime
+//      (e.g. `internalNumber: text`) via the bundle's CRUD.
+//   3. Values are written via `custom-fields:write:set-custom-field`,
+//      not through the host entity's own write handler.
+//   4. Reads return the field flattened onto the row — looks like a
+//      first-class column. The flattening is an entity-level postQuery
+//      hook (registered by wireCustomFieldsFor), so it fires for ANY
+//      query whose name maps to this entity — including the hand-written
+//      `property:list` below.
+
+import {
+  customFieldsField,
+  wireCustomFieldsFor,
+} from "@cosmicdrift/kumiko-bundled-features/custom-fields";
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// --- Entity ---
+//
+// The field shape is declared as a plain object literal so the feature is
+// self-describing Object-Form (what the AI/Designer should emit). The same
+// literal is passed inline to `r.entity` below. `{ type: "jsonb" }` is
+// exactly what `customFieldsField()` produces — the jsonb column the
+// bundle's projection writes into; without it `wireCustomFieldsFor` has
+// nowhere to land the values.
+
+export const propertyEntity = createEntity({
+  table: "read_sample_cf_properties",
+  fields: {
+    name: { type: "text", required: true, maxLength: 200 },
+    customFields: customFieldsField(),
+  },
+});
+
+export const propertyTable = buildEntityTable("property", propertyEntity);
+
+function propertyExecutor() {
+  return createEventStoreExecutor(propertyTable, propertyEntity, { entityName: "property" });
+}
+
+// --- Feature ---
+
+export const propertyFeature = defineFeature("property-management", (r) => {
+  r.requires("custom-fields");
+
+  r.entity("property", {
+    table: "read_sample_cf_properties",
+    fields: {
+      name: { type: "text", required: true, maxLength: 200 },
+      customFields: { type: "jsonb" },
+    },
+  });
+
+  // Opt this entity into the custom-fields extension. This registers the
+  // multi-stream projection (MSP) that consumes customField.set / .cleared
+  // events and writes them into the `customFields` jsonb column, plus the
+  // entity postQuery hook that flattens the jsonb onto the row at read-time.
+  wireCustomFieldsFor(r, "property", propertyTable);
+
+  r.writeHandler({
+    name: "property:create",
+    schema: z.object({ id: z.string(), name: z.string() }),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (event, ctx) =>
+      propertyExecutor().create(
+        { id: event.payload.id, name: event.payload.name, customFields: {} },
+        event.user,
+        ctx.db,
+      ),
+  });
+
+  // List query. Named `property:list` so it maps to the `property` entity
+  // (colon convention) — that mapping is what lets the entity postQuery
+  // hook from wireCustomFieldsFor flatten customFields onto each row. The
+  // handler itself just reads the tenant-scoped read table; ctx.db is
+  // already tenant-scoped.
+  r.queryHandler({
+    name: "property:list",
+    schema: z.object({}),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (_query, ctx) => {
+      const rows = await ctx.db.selectMany(propertyTable);
+      return { rows };
+    },
+  });
+});
+```

package/agents/examples/custom-handlers.md

@@ -0,0 +1,397 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/custom-handlers. Do not edit. -->
+
+# custom-handlers
+
+Beyond CRUD — when your domain refuses to fit a table.
+
+## README
+
+# Custom handlers
+
+Replace the default CRUD with handler bodies that carry business rules.
+This recipe ships a `counter` entity with three custom write handlers
+(create, increment with read-modify-write, reset with last-writer-wins)
+plus a custom query that filters the projection.
+
+The point is to show the **boundary**: where the entity executor stops
+doing work for you and where your code has to take over. The framework
+gives you `createEntityExecutor` so the executor's `create` / `update` /
+`detail` / `list` are still one-liners — only the surrounding business
+logic is yours.
+
+## What it shows
+
+- **`r.writeHandler(name, schema, handler, options)`** — the positional
+  inline form, useful when the handler body is short and stays close to
+  its registration.
+- **Read-modify-write with optimistic locking** — `increment` reads the
+  current count, computes the new one, and updates with the version it
+  read. Two concurrent increments cannot both succeed.
+- **`skipOptimisticLock` for last-writer-wins** — `reset` deliberately
+  bypasses the version check because the operation is admin-driven and
+  resetting twice is semantically the same as resetting once.
+- **Custom queries** — `counter:active` filters the projection in
+  TypeScript after the executor's list returns. Useful when the filter is
+  computed (above-threshold) rather than indexed.
+- **`failNotFound` helper** — typed error response for the 404 case
+  without a hand-built `KumikoError` subclass.
+
+## When to reach for it
+
+You have an entity but the default CRUD doesn't capture what your
+business rule actually does. The default `update` blindly writes the
+payload; your `increment` needs to read first, decide, and write. That's
+the line.
+
+## Source
+
+The whole feature lives in `src/feature.ts` (~100 lines). Integration
+tests cover the optimistic-lock case, the skip-lock case, and the
+custom-filter query.
+
+```bash
+bun kumiko test integration samples/custom-handlers
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Custom Handlers Sample — Integration Test
+// Proves: custom business logic in handlers, payload transformation, custom queries
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { counterEntity, counterFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+const user = createTestUser({ id: 2, roles: ["User"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [counterFeature] });
+  await unsafeCreateEntityTable(stack.db, counterEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  stack.events.reset();
+});
+
+describe("custom write handler: increment", () => {
+  test("increment adds to existing count", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "page-views",
+      },
+      admin,
+    );
+    expect(created.data["count"]).toBe(0);
+
+    const incremented = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 5,
+      },
+      user,
+    );
+
+    expect(incremented.data["count"]).toBe(5);
+    expect(incremented.data["lastIncrementedBy"]).toBe(`user:${user.id}`);
+  });
+
+  test("multiple increments accumulate", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "clicks",
+      },
+      admin,
+    );
+
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 3,
+      },
+      user,
+    );
+    const result = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 7,
+      },
+      user,
+    );
+
+    expect(result.data["count"]).toBe(10);
+  });
+
+  test("increment validates max amount", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "guarded",
+      },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 101,
+      },
+      user,
+    );
+    expectErrorIncludes(error, "validation");
+  });
+
+  test("increment on non-existent returns error", async () => {
+    const error = await stack.http.writeErr(
+      "counters:write:counter:increment",
+      {
+        id: "00000000-0000-4000-8000-000000000999",
+        amount: 1,
+      },
+      user,
+    );
+    expect(error.code).toBe("not_found");
+  });
+});
+
+describe("custom write handler: reset", () => {
+  test("reset sets count back to zero", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "resettable",
+      },
+      admin,
+    );
+
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      {
+        id: created.id,
+        amount: 42,
+      },
+      user,
+    );
+
+    const reset = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:reset",
+      {
+        id: created.id,
+      },
+      admin,
+    );
+
+    expect(reset.data["count"]).toBe(0);
+    expect(reset.data["lastIncrementedBy"]).toBe("");
+  });
+
+  test("only Admin can reset", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      {
+        name: "admin-only-reset",
+      },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(
+      "counters:write:counter:reset",
+      {
+        id: created.id,
+      },
+      user,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+});
+
+describe("custom query handler: active counters", () => {
+  test("filters counters by minimum count", async () => {
+    const c1 = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      { name: "active-a" },
+      admin,
+    );
+    const c2 = await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      { name: "active-b" },
+      admin,
+    );
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:create",
+      { name: "inactive" },
+      admin,
+    );
+
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      { id: c1.id, amount: 10 },
+      user,
+    );
+    await stack.http.writeOk<SaveContext>(
+      "counters:write:counter:increment",
+      { id: c2.id, amount: 5 },
+      user,
+    );
+
+    const result = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "counters:query:counter:active",
+      { minCount: 5 },
+      admin,
+    );
+
+    const names = result.rows.map((r) => r["name"]);
+    expect(names).toContain("active-a");
+    expect(names).toContain("active-b");
+    expect(names).not.toContain("inactive");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Custom Handlers Sample
+// Shows: writeHandler with business logic, queryHandler with custom filtering,
+// handler that modifies payload before DB write.
+
+import {
+  createEntity,
+  createEntityExecutor,
+  createNumberField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+export const counterEntity = createEntity({
+  table: "read_sample_counters",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    count: createNumberField({ default: 0 }),
+    lastIncrementedBy: createTextField({ personal: "ref" }),
+  },
+});
+
+export const counterFeature = defineFeature("counters", (r) => {
+  r.entity("counter", counterEntity);
+
+  // createEntityExecutor bundles buildEntityTable + createEventStoreExecutor —
+  // the same pair every custom write-handler opens with. Collapses 3 lines
+  // + the { entityName } bookkeeping into one destructure.
+  const { executor: counterExecutor } = createEntityExecutor("counter", counterEntity);
+
+  // Standard create
+  r.writeHandler(
+    "counter:create",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) =>
+      counterExecutor.create({ ...event.payload, count: 0 }, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Custom handler: increment with business logic
+  r.writeHandler(
+    "counter:increment",
+    z.object({ id: z.uuid(), amount: z.number().min(1).max(100) }),
+    async (event, ctx) => {
+      const current = await counterExecutor.detail({ id: event.payload.id }, event.user, ctx.db);
+      if (!current) {
+        return failNotFound("counter", event.payload.id);
+      }
+
+      const newCount = (current["count"] as number) + event.payload.amount;
+      // Read-modify-write on counter: use the version we just read so two
+      // concurrent increments don't clobber each other's changes.
+      return counterExecutor.update(
+        {
+          id: event.payload.id,
+          version: current["version"] as number,
+          changes: { count: newCount, lastIncrementedBy: `user:${event.user.id}` },
+        },
+        event.user,
+        ctx.db,
+      );
+    },
+    { access: { roles: ["Admin", "User"] } },
+  );
+
+  // Custom handler: reset to zero
+  r.writeHandler(
+    "counter:reset",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) =>
+      // Admin reset: last-writer-wins is intentional — there's no useful
+      // concurrent-reset race to guard against.
+      counterExecutor.update(
+        { id: event.payload.id, changes: { count: 0, lastIncrementedBy: "" } },
+        event.user,
+        ctx.db,
+        { skipOptimisticLock: true },
+      ),
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Custom query: only counters above a threshold
+  r.queryHandler(
+    "counter:active",
+    z.object({ minCount: z.number().default(1) }),
+    async (query, ctx) => {
+      const all = await counterExecutor.list({}, query.user, ctx.db);
+      return {
+        ...all,
+        rows: all.rows.filter((r) => (r["count"] as number) >= query.payload.minCount),
+      };
+    },
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in user may list active counters; the sample has no per-user counter ownership",
+        },
+      },
+    },
+  );
+
+  // Standard detail
+  r.queryHandler(
+    "counter:detail",
+    z.object({ id: z.uuid() }),
+    async (query, ctx) => counterExecutor.detail(query.payload, query.user, ctx.db),
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in user may read a counter by id; the sample has no per-user counter ownership",
+        },
+      },
+    },
+  );
+});
+```