@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/embedded.md

@@ -0,0 +1,649 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/embedded. Do not edit. -->
+
+# embedded
+
+Embedded fields on entities. Structured JSON without the JSON part.
+
+## README
+
+# Embedded fields and lists
+
+Keep owned, fixed-shape data with its parent entity instead of giving every
+nested value its own aggregate. This recipe covers both a single embedded
+object and an embedded list rendered by a declarative `entityEdit` screen.
+
+## What it shows
+
+- **Embedded objects** — `address` and optional `billingAddress` are validated
+  sub-schemas stored in the contact row.
+- **Embedded lists** — invoice `lines` repeat a fixed row shape without their
+  own identity or event stream.
+- **Structured cells** — a line uses a reference, select, number, and money
+  cell, with `amount` derived from `quantity × unitPrice` and a totals row.
+- **Server-authoritative derived cells** — the write schema recomputes
+  `derived` values before validation, so a client cannot supply a stale amount;
+  the edit view model exposes the definitions as `embeddedListDerived`.
+- **Declarative editing** — the `invoice-edit` screen uses
+  `createEmbeddedListField`; its renderer receives `embeddedListCells`, so no
+  custom screen component is required.
+
+## When to reach for it
+
+Use an embedded field or list when the nested data is created, changed, and
+deleted with its parent. Promote a row to its own entity when it needs an
+independent status, history, or handler.
+
+## Source
+
+The feature entry point is `src/feature.ts`. The embedded object and invoice
+line-item schemas live under `src/entities/`; integration tests cover schema
+validation, derived values, totals, references, and the declarative edit
+screen.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Embedded Object Sample — Integration Test
+// Proves: embedded objects stored as JSONB, read back correctly,
+// required embedded fails when missing, optional embedded can be omitted,
+// searchable sub-fields registered, field access on sub-fields E2E
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { EntityId, SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { contactEntity } from "../entities/contact";
+import { invoiceEntity } from "../entities/invoice";
+import { productEntity } from "../entities/product";
+import { embeddedFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+const viewer = createTestUser({ id: 2, roles: ["Viewer"] });
+const otherTenant = createTestUser({ id: 3, tenantId: "00000000-0000-4000-8000-000000000002" });
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [embeddedFeature],
+    systemHooks: [],
+  });
+  await unsafeCreateEntityTable(stack.db, contactEntity);
+  await unsafeCreateEntityTable(stack.db, productEntity);
+  await unsafeCreateEntityTable(stack.db, invoiceEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+// --- Create + Read ---
+
+describe("create and read embedded objects", () => {
+  test("create contact with required address succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "contacts:write:contact:create",
+      {
+        name: "Max Mustermann",
+        email: "max@test.de",
+        address: { street: "Hauptstr. 1", zip: "10115", city: "Berlin", country: "DE" },
+      },
+      admin,
+    );
+    expect(data.isNew).toBe(true);
+    expect(data.data["address"]).toEqual({
+      street: "Hauptstr. 1",
+      zip: "10115",
+      city: "Berlin",
+      country: "DE",
+    });
+  });
+
+  test("detail returns embedded object intact", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "contacts:write:contact:create",
+      {
+        name: "Detail Test",
+        address: { street: "Musterweg 5", zip: "80331", city: "München" },
+      },
+      admin,
+    );
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "contacts:query:contact:detail",
+      { id: created.id },
+      admin,
+    );
+    expect(detail["name"]).toBe("Detail Test");
+    const addr = detail["address"] as Record<string, unknown>;
+    expect(addr["street"]).toBe("Musterweg 5");
+    expect(addr["city"]).toBe("München");
+  });
+
+  test("create with optional billingAddress", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "contacts:write:contact:create",
+      {
+        name: "With Billing",
+        address: { street: "A-Str.", zip: "12345", city: "Hamburg" },
+        billingAddress: {
+          street: "B-Str.",
+          zip: "54321",
+          city: "Frankfurt",
+          vatId: "DE123456789",
+        },
+      },
+      admin,
+    );
+    expect(data.isNew).toBe(true);
+    const billing = data.data["billingAddress"] as Record<string, unknown>;
+    expect(billing["vatId"]).toBe("DE123456789");
+  });
+
+  test("create without optional billingAddress succeeds", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "contacts:write:contact:create",
+      {
+        name: "No Billing",
+        address: { street: "C-Str.", zip: "11111", city: "Köln" },
+      },
+      admin,
+    );
+    expect(data.isNew).toBe(true);
+  });
+});
+
+// --- Validation ---
+
+describe("embedded validation", () => {
+  test("missing required address fails", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:contact:create",
+      { name: "No Address" },
+      admin,
+    );
+    expect(error).toBeDefined();
+  });
+
+  test("address with missing required sub-field fails", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:contact:create",
+      {
+        name: "Bad Address",
+        address: { street: "Only Street" }, // missing zip + city
+      },
+      admin,
+    );
+    expect(error).toBeDefined();
+  });
+});
+
+// --- Field access on embedded sub-fields (E2E via API) ---
+
+describe("field access on embedded sub-fields", () => {
+  let contactWithBillingId: EntityId;
+
+  test("create contact with billingAddress for access tests", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "contacts:write:contact:create",
+      {
+        name: "Access Test Contact",
+        address: { street: "A", zip: "1", city: "X" },
+        billingAddress: { street: "B", zip: "2", city: "Y", vatId: "DE999" },
+      },
+      admin,
+    );
+    contactWithBillingId = created.id;
+  });
+
+  test("Admin sees billingAddress.vatId via detail query", async () => {
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "contacts:query:contact:detail",
+      { id: contactWithBillingId },
+      admin,
+    );
+    const billing = detail["billingAddress"] as Record<string, unknown>;
+    expect(billing["vatId"]).toBe("DE999");
+    expect(billing["street"]).toBe("B");
+  });
+
+  test("Viewer does NOT see billingAddress.vatId via detail query", async () => {
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "contacts:query:contact:detail",
+      { id: contactWithBillingId },
+      viewer,
+    );
+    const billing = detail["billingAddress"] as Record<string, unknown>;
+    expect(billing["vatId"]).toBeUndefined();
+    expect(billing["street"]).toBe("B"); // other fields still visible
+  });
+});
+
+// --- Embedded list (createEmbeddedListField) ---
+
+describe("embedded list of like-shaped rows", () => {
+  const withPhones = {
+    name: "Phone Book",
+    address: { street: "D-Str.", zip: "22222", city: "Bremen" },
+    phoneNumbers: [
+      { label: "Buero", number: "+49 30 1", note: "Durchwahl 12" },
+      { label: "Mobil", number: "+49 170 2" },
+    ],
+  };
+
+  test("rows round-trip as an array, in order", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "contacts:write:contact:create",
+      withPhones,
+      admin,
+    );
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "contacts:query:contact:detail",
+      { id: created.id },
+      admin,
+    );
+    expect(detail["phoneNumbers"]).toEqual(withPhones.phoneNumbers);
+  });
+
+  test("an omitted list reads back as an empty array (column default)", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "contacts:write:contact:create",
+      { name: "No Phones", address: { street: "E-Str.", zip: "33333", city: "Essen" } },
+      admin,
+    );
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "contacts:query:contact:detail",
+      { id: created.id },
+      admin,
+    );
+    expect(detail["phoneNumbers"]).toEqual([]);
+  });
+
+  test("a row missing a required sub-field is rejected", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:contact:create",
+      {
+        name: "Bad Row",
+        address: { street: "F-Str.", zip: "44444", city: "Kiel" },
+        phoneNumbers: [{ label: "Buero", number: "+49 30 1" }, { label: "Mobil" }],
+      },
+      admin,
+    );
+    expect(error).toBeDefined();
+  });
+
+  test("field access is applied per row, the value stays an array", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "contacts:write:contact:create",
+      withPhones,
+      admin,
+    );
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "contacts:query:contact:detail",
+      { id: created.id },
+      viewer,
+    );
+    expect(detail["phoneNumbers"]).toEqual([
+      { label: "Buero", number: "+49 30 1" },
+      { label: "Mobil", number: "+49 170 2" },
+    ]);
+  });
+});
+
+// --- Searchable embedded sub-fields (registry) ---
+
+describe("searchable embedded sub-fields", () => {
+  test("registry reports embedded sub-fields as searchable", () => {
+    const searchable = stack.registry.getSearchableFields("contact");
+    expect(searchable).toContain("name");
+    expect(searchable).toContain("address_street");
+    expect(searchable).toContain("address_city");
+    expect(searchable).not.toContain("address_zip"); // not marked searchable
+    expect(searchable).not.toContain("address_country");
+    expect(searchable).toContain("phoneNumbers_label");
+    expect(searchable).not.toContain("phoneNumbers_number");
+  });
+});
+
+// --- Tenant isolation ---
+
+describe("tenant isolation", () => {
+  test("other tenant cannot read contact", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "contacts:write:contact:create",
+      {
+        name: "Secret Contact",
+        address: { street: "Hidden", zip: "00000", city: "Nowhere" },
+      },
+      admin,
+    );
+
+    const detail = await stack.http.queryOk<null>(
+      "contacts:query:contact:detail",
+      { id: created.id },
+      otherTenant,
+    );
+    expect(detail).toBeNull();
+  });
+});
+
+// --- Invoice line items: select/reference/derived/totals metadata (#1835) ---
+
+describe("invoice line items with select/reference/derived/totals metadata", () => {
+  const validLine = {
+    product: "00000000-0000-4000-8000-000000000001",
+    unit: "pcs",
+    quantity: 2,
+    unitPrice: 500,
+    amount: 1000,
+  };
+
+  test("valid lines round-trip, including the client-computed amount", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "contacts:write:invoice:create",
+      { customer: "Acme Inc.", lines: [validLine] },
+      admin,
+    );
+    expect(created.data["lines"]).toEqual([validLine]);
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "contacts:query:invoice:detail",
+      { id: created.id },
+      admin,
+    );
+    expect(detail["lines"]).toEqual([validLine]);
+  });
+
+  test("a line with a unit outside the select options is rejected", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:invoice:create",
+      { customer: "Bad Unit", lines: [{ ...validLine, unit: "liters" }] },
+      admin,
+    );
+    expect(error).toBeDefined();
+  });
+
+  test("a line with a non-UUID product reference is rejected", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:invoice:create",
+      { customer: "Bad Product", lines: [{ ...validLine, product: "not-a-uuid" }] },
+      admin,
+    );
+    expect(error).toBeDefined();
+  });
+
+  test("an empty lines array violates minItems and is rejected", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:invoice:create",
+      { customer: "No Lines", lines: [] },
+      admin,
+    );
+    expect(error).toBeDefined();
+  });
+
+  test("more than maxItems lines is rejected", async () => {
+    const tooManyLines = Array.from({ length: 6 }, () => ({ ...validLine }));
+    const error = await stack.http.writeErr(
+      "contacts:write:invoice:create",
+      { customer: "Too Many Lines", lines: tooManyLines },
+      admin,
+    );
+    expect(error).toBeDefined();
+  });
+});
+```
+
+### src/entities/contact.ts
+
+```ts
+// Contact with embedded address — address belongs 1:1 to the contact,
+// is never shared, and is always read/written together. `phoneNumbers` is the
+// same idea for N rows: written whole with the contact, no per-row history.
+
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEmbeddedField,
+  createEmbeddedListField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const contactEntity = createEntity({
+  table: "read_sample_contacts",
+  fields: {
+    name: createTextField({ required: true, personal: "self", find: "fuzzy" }),
+    email: createTextField({ format: "email", personal: "self", find: "none" }),
+    address: createEmbeddedField(
+      {
+        street: { type: "text", required: true, searchable: true },
+        zip: { type: "text", required: true },
+        city: { type: "text", required: true, searchable: true },
+        country: { type: "text" },
+      },
+      { required: true },
+    ),
+    billingAddress: createEmbeddedField({
+      street: { type: "text", required: true },
+      zip: { type: "text", required: true },
+      city: { type: "text", required: true },
+      country: { type: "text" },
+      vatId: { type: "text", access: { read: ["Admin", "Accounting"] } },
+    }),
+    // A list of like-shaped rows. A phone number has no lifetime of its own —
+    // editing the contact rewrites the whole list. Something that starts and
+    // ends on its own (a contract position, a subscription) would be its own
+    // entity referencing the contact instead.
+    phoneNumbers: createEmbeddedListField({
+      label: { type: "text", required: true, searchable: true },
+      number: { type: "text", required: true },
+      note: { type: "text", access: { read: ["Admin"] } },
+    }),
+  },
+});
+
+export const contactTable = buildEntityTable("contact", contactEntity);
+```
+
+### src/entities/invoice.ts
+
+```ts
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEmbeddedListField,
+  createEntity,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Invoice line-items — the motivating case for select/reference/derived/
+// totals metadata on createEmbeddedListField: each line references a
+// product, has a unit (select), and a derived amount (qty × unitPrice)
+// that the entity sums across all lines.
+export const invoiceEntity = createEntity({
+  table: "read_sample_invoices",
+  fields: {
+    customer: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    lines: createEmbeddedListField(
+      {
+        product: { type: "reference", entity: "product", required: true },
+        unit: { type: "select", options: ["pcs", "hours", "kg"], required: true },
+        quantity: { type: "number", required: true },
+        unitPrice: { type: "money", required: true },
+        amount: { type: "money" },
+      },
+      {
+        required: true,
+        minItems: 1,
+        maxItems: 5,
+        derived: { amount: { op: "multiply", from: ["quantity", "unitPrice"] } },
+        totals: ["amount"],
+      },
+    ),
+  },
+});
+
+export const invoiceTable = buildEntityTable("invoice", invoiceEntity);
+```
+
+### src/entities/product.ts
+
+```ts
+// A minimal entity for the invoice's `product` reference cell — just
+// enough to demonstrate a reference sub-field on an embedded list.
+
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
+
+export const productEntity = createEntity({
+  table: "read_sample_products",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+  },
+});
+
+export const productTable = buildEntityTable("product", productEntity);
+```
+
+### src/feature.ts
+
+```ts
+// Embedded Object Sample
+// Shows: Embedded objects stored as JSONB, searchable sub-fields,
+// field access on sub-fields, required vs optional embedded objects
+//
+// Pattern: Address belongs 1:1 to contact — never shared, always read together.
+// Use embedded when: data is owned by the parent entity, not referenced elsewhere.
+//
+// Tables:
+//   contact — with embedded address (required) and billingAddress (optional)
+//             address.street and address.city are searchable
+//             billingAddress.vatId has restricted field access
+//   product — minimal entity, only exists so `invoice.lines` has something
+//             to reference
+//   invoice — embedded list with select/reference/derived/totals metadata
+//             on its `lines` sub-fields (Issue #1835), plus a declarative
+//             entityEdit screen that renders the list end-to-end via
+//             EmbeddedListField, no custom-screen code required
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { contactEntity } from "./entities/contact";
+import { invoiceEntity } from "./entities/invoice";
+import { productEntity } from "./entities/product";
+import { contactCreate } from "./handlers/contact-create.write";
+import { contactDetail } from "./handlers/contact-detail.query";
+
+export { contactEntity } from "./entities/contact";
+export { invoiceEntity } from "./entities/invoice";
+export { productEntity } from "./entities/product";
+
+const adminWrite = { access: { roles: ["Admin"] } } as const;
+const openRead = {
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may read products and invoices in this recipe; writes are " +
+        "still gated by adminWrite",
+    },
+  },
+} as const;
+
+export const embeddedFeature = defineFeature("contacts", (r) => {
+  r.entity("contact", contactEntity);
+
+  r.writeHandler(contactCreate);
+  r.queryHandler(contactDetail);
+
+  r.crud("product", productEntity, { write: adminWrite, read: openRead });
+  r.crud("invoice", invoiceEntity, { write: adminWrite, read: openRead });
+
+  r.screen({
+    id: "invoice-edit",
+    type: "entityEdit",
+    entity: "invoice",
+    layout: {
+      sections: [{ columns: 1, fields: ["customer", "lines"] }],
+    },
+  });
+});
+```
+
+### src/handlers/contact-create.write.ts
+
+```ts
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { contactEntity, contactTable } from "../entities/contact";
+
+const contactCrud = createEventStoreExecutor(contactTable, contactEntity, {
+  entityName: "contact",
+});
+
+const addressSchema = z.object({
+  street: z.string().min(1),
+  zip: z.string().min(1),
+  city: z.string().min(1),
+  country: z.string().optional(),
+});
+
+const billingAddressSchema = z.object({
+  street: z.string().min(1),
+  zip: z.string().min(1),
+  city: z.string().min(1),
+  country: z.string().optional(),
+  vatId: z.string().optional(),
+});
+
+const phoneNumberSchema = z.object({
+  label: z.string().min(1),
+  number: z.string().min(1),
+  note: z.string().optional(),
+});
+
+export const contactCreate = defineWriteHandler({
+  name: "contact:create",
+  schema: z.object({
+    name: z.string().min(1),
+    email: z.email().optional(),
+    address: addressSchema,
+    billingAddress: billingAddressSchema.optional(),
+    phoneNumbers: z.array(phoneNumberSchema).optional(),
+  }),
+  access: { roles: ["Admin"] },
+  // Embedded fields (address/billingAddress) arrive as objects, the embedded
+  // list (phoneNumbers) as an array — already the combined API form the
+  // executor expects; it flattens them into the read row.
+  handler: async (event, ctx) => contactCrud.create(event.payload, event.user, ctx.db),
+});
+```
+
+### src/handlers/contact-detail.query.ts
+
+```ts
+import { defineQueryHandler, filterReadFields } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { contactEntity, contactTable } from "../entities/contact";
+
+export const contactDetail = defineQueryHandler({
+  name: "contact:detail",
+  schema: z.object({ id: z.uuid() }),
+  access: {
+    openToAll: {
+      reason:
+        "demo recipe: any signed-in user may look up any contact by id, subject to " +
+        "the entity's own field-level read access on restricted sub-fields like billingAddress.vatId",
+    },
+  },
+  handler: async (query, ctx) => {
+    const [row] = await ctx.db.selectMany(contactTable, { id: query.payload.id });
+    if (!row) return null;
+    return filterReadFields(contactEntity, row as Record<string, unknown>, query.user);
+  },
+});
+```