@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/realtime-sse.md

@@ -0,0 +1,187 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/realtime-sse. Do not edit. -->
+
+# realtime-sse
+
+Server-sent events demo. Goodbye F5.
+
+## README
+
+# Realtime SSE
+
+Server-sent events — live updates without F5.
+
+## What it shows
+
+- Entity writes that fan out over SSE
+- Client subscription shape for live lists
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/realtime-sse
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Realtime SSE Sample — Integration Test
+// Proves: SSE events fire on create, update, delete through the async
+// event-dispatcher (D.3). Shape mirrors the StoredEvent: `type` is the
+// event type ("message.created"), `data` carries id/version only: the
+// frame is a change signal, clients refetch the record through a query.
+
+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 { chatFeature, messageEntity } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+const user = createTestUser({ id: 2, roles: ["User"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [chatFeature] });
+  await unsafeCreateEntityTable(stack.db, messageEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  // Advance the event-dispatcher past previous-test events, then reset the
+  // collector. Without this, each test would see SSE events stacked up from
+  // its predecessors.
+  await stack.eventDispatcher?.runOnce();
+  stack.events.reset();
+});
+
+describe("SSE broadcast on create", () => {
+  test("emits message.created event", async () => {
+    await stack.http.writeOk<SaveContext>(
+      "chat:write:message:create",
+      {
+        channel: "general",
+        text: "Hello world",
+        author: "Alice",
+      },
+      user,
+    );
+
+    // SSE is delivered asynchronously by the event-dispatcher. Drain once so
+    // the test observes a deterministic state.
+    await stack.eventDispatcher?.runOnce();
+
+    expect(stack.events.sse).toHaveLength(1);
+    expect(stack.events.sse[0]?.type).toBe("message.created");
+    expect(stack.events.sse[0]?.data["id"]).toBeDefined();
+  });
+});
+
+describe("SSE broadcast on update", () => {
+  test("emits a message.updated signal without field values", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "chat:write:message:create",
+      {
+        channel: "general",
+        text: "Original",
+      },
+      user,
+    );
+
+    // Drain the create event, then reset so the update assertion is isolated.
+    await stack.eventDispatcher?.runOnce();
+    stack.events.reset();
+
+    await stack.http.writeOk<SaveContext>(
+      "chat:write:message:update",
+      {
+        id: created.id,
+        changes: { text: "Edited" },
+        version: 1,
+      },
+      user,
+    );
+    await stack.eventDispatcher?.runOnce();
+
+    const updateEvent = stack.events.sse.find((e) => e.type === "message.updated");
+    expect(updateEvent).toBeDefined();
+    expect(updateEvent?.data["id"]).toBe(created.id);
+    expect(updateEvent?.data["version"]).toBe(2);
+    expect(updateEvent?.data).not.toHaveProperty("payload");
+  });
+});
+
+describe("SSE broadcast on delete", () => {
+  test("emits message.deleted event", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "chat:write:message:create",
+      {
+        channel: "general",
+        text: "Delete me",
+      },
+      user,
+    );
+
+    await stack.eventDispatcher?.runOnce();
+    stack.events.reset();
+
+    await stack.http.writeOk<SaveContext>("chat:write:message:delete", { id: created.id }, admin);
+    await stack.eventDispatcher?.runOnce();
+
+    const deleteEvent = stack.events.sse.find((e) => e.type === "message.deleted");
+    expect(deleteEvent).toBeDefined();
+    expect(deleteEvent?.data["id"]).toBe(created.id);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import {
+  createEntity,
+  createTextField,
+  defineEntityDeleteHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const messageEntity = createEntity({
+  table: "read_sample_messages",
+  fields: {
+    channel: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    text: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    author: createTextField({ personal: { of: "id" }, find: "none" }),
+  },
+  softDelete: true,
+});
+
+const userWrite = { access: { roles: ["Admin", "User"] } } as const;
+const adminWrite = { access: { roles: ["Admin"] } } as const;
+
+export const chatFeature = defineFeature("chat", (r) => {
+  r.crud("message", messageEntity, {
+    write: userWrite,
+    verbs: { list: false, detail: false, restore: false, delete: false },
+  });
+  r.writeHandler(defineEntityDeleteHandler("message", messageEntity, adminWrite));
+});
+```

package/agents/examples/record-detail-layout.md

@@ -0,0 +1,297 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/record-detail-layout. Do not edit. -->
+
+# record-detail-layout
+
+projectionDetail record header, metrics band, and layout.mode: "tabs" — an order screen with two relatedList tabs and a fields tab.
+
+## README
+
+# Record Detail Layout
+
+Register a `projectionDetail` screen as a tabbed record view ("Akte"): a
+header, a metrics band, and a tabbed layout instead of one long stacked form.
+
+## What it shows
+
+- `header` (title/subtitle/status) and `metrics` (labeled via `fieldLabels`)
+  rendered from the columns of the screen's own query row
+- `layout.mode: "tabs"` with two `relatedList` tabs (order items, payments)
+  and one `fields` tab (master data) — each `relatedList` runs its own query
+- boot-validator catching two common author mistakes: a `metrics` entry
+  without a `fieldLabels` override, and a `tabs` layout with fewer than two
+  sections
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/record-detail-layout
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.test.ts
+
+```ts
+// Record Detail Layout Showcase — Unit Test (no DB / HTTP needed).
+// Proves:
+//   - header/metrics/tabs land on the registered ProjectionDetailScreenDefinition
+//     exactly as declared (column names, not literals)
+//   - relatedList columns collapse the string shorthand like entityList columns do
+//   - the boot-validator catches the two mistakes the projectionDetail tabs
+//     layout introduces: a metric without a fieldLabels entry, and a tabs
+//     layout with fewer than two sections
+
+import { describe, expect, test } from "bun:test";
+import {
+  createRegistry,
+  defineFeature,
+  normalizeListColumn,
+  validateBoot as validateBootRaw,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { withBootValidatorFixture } from "@cosmicdrift/kumiko-framework/testing";
+import { z } from "zod";
+import { createOrderDeskFeature } from "../feature";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+const orderDesk = createOrderDeskFeature();
+const registry = createRegistry([orderDesk]);
+
+describe("record-detail-layout showcase — registration", () => {
+  test("validateBoot accepts the full registered app", () => {
+    expect(() => validateBoot([orderDesk])).not.toThrow();
+  });
+
+  test("order-detail registers as projectionDetail with a qualified id", () => {
+    const screen = registry.getScreen("order-desk:screen:order-detail");
+    expect(screen?.type).toBe("projectionDetail");
+  });
+
+  test("header and metrics store column names, not literals", () => {
+    const screen = registry.getScreen("order-desk:screen:order-detail");
+    if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
+    expect(screen.header).toEqual({
+      title: "customerName",
+      subtitle: "orderNumber",
+      status: "status",
+    });
+    expect(screen.metrics).toEqual(["totalAmount", "outstandingAmount", "itemCount", "placedAt"]);
+  });
+
+  test("layout.mode is tabs with two relatedList sections, one fields section, and one extension section", () => {
+    const screen = registry.getScreen("order-desk:screen:order-detail");
+    if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
+    expect(screen.layout.mode).toBe("tabs");
+    expect(screen.layout.sections.map((s) => s.kind)).toEqual([
+      "relatedList",
+      "relatedList",
+      "fields",
+      "extension",
+    ]);
+  });
+
+  test("screen-level actions carry a refresh-order navigate action", () => {
+    const screen = registry.getScreen("order-desk:screen:order-detail");
+    if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
+    expect(screen.actions?.map((a) => a.id)).toEqual(["refresh-order"]);
+  });
+
+  test("relatedList columns collapse string shorthand into the object form", () => {
+    const screen = registry.getScreen("order-desk:screen:order-detail");
+    if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
+    const itemsSection = screen.layout.sections[0];
+    if (itemsSection?.kind !== "relatedList") throw new Error("expected relatedList");
+    expect(normalizeListColumn(itemsSection.columns[0]!)).toEqual({ field: "sku" });
+  });
+});
+
+describe("record-detail-layout showcase — boot-validator catches author mistakes", () => {
+  test("metric without a fieldLabels entry fails boot — no fallback to the raw column name", () => {
+    const broken = defineFeature("broken-order-desk", (r) => {
+      r.queryHandler("order:detail", z.object({ id: z.string() }), async () => ({ id: "1" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "order-detail",
+        type: "projectionDetail",
+        query: "broken-order-desk:query:order:detail",
+        metrics: ["totalAmount"],
+        layout: { sections: [{ title: "Details", fields: ["id"] }] },
+      });
+    });
+    expect(() => validateBoot([broken])).toThrow(
+      /metric "totalAmount" has no entry in fieldLabels/,
+    );
+  });
+
+  test("tabs with only one section fails boot", () => {
+    const broken = defineFeature("broken-order-desk-tabs", (r) => {
+      r.queryHandler("order:detail", z.object({ id: z.string() }), async () => ({ id: "1" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "order-detail",
+        type: "projectionDetail",
+        query: "broken-order-desk-tabs:query:order:detail",
+        layout: {
+          mode: "tabs",
+          sections: [{ id: "only", title: "Only", fields: ["id"] }],
+        },
+      });
+    });
+    expect(() => validateBoot([broken])).toThrow(/tabs need at least 2 sections/);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Record Detail Layout Showcase — a projectionDetail screen with the
+// "Akte" (case file) layout:
+//   1. `header` renders the query row's customer/order/status columns above
+//      the layout — the identity a support agent scans first.
+//   2. `metrics` renders a labeled band of key numbers from the same row —
+//      labels come from `fieldLabels`, there is no fallback to the raw
+//      column name.
+//   3. `layout.mode: "tabs"` splits the record into four tabs: two
+//      `relatedList` sections (own query, own pagination, mounts only when
+//      active), one `fields` section (master data from the detail row), and
+//      one `extension` section (a plugin-mounted component, fw#3234 padding-
+//      parity check — every tab kind must sit in the same Card padding, no
+//      section carries extra chrome of its own).
+//   4. A screen-level `actions` entry (fw#3234) renders next to the header,
+//      not inside any tab's Card.
+//
+// projectionDetail has no entity — it binds to an explicit query instead, so
+// every field name below (header, metrics, fields) is a column of that
+// query's row, not an entity field.
+
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+const rowIdSchema = z.object({ id: z.string() });
+
+export function createOrderDeskFeature(): FeatureDefinition {
+  return defineFeature("order-desk", (r) => {
+    r.systemScope();
+
+    r.queryHandler(
+      "order:detail",
+      rowIdSchema,
+      async (query) => ({
+        id: query.payload.id,
+        customerName: "Aiko Tanaka",
+        orderNumber: "SO-10482",
+        status: "processing",
+        totalAmount: "€ 1,248.00",
+        outstandingAmount: "€ 312.00",
+        itemCount: "3",
+        placedAt: "2026-08-21",
+        shippingAddress: "Karl-Marx-Straße 12, 12043 Berlin",
+        billingAddress: "Karl-Marx-Straße 12, 12043 Berlin",
+        salesRep: "Jonas Weber",
+      }),
+      { access: { roles: ["Support", "Admin"] } },
+    );
+
+    r.queryHandler(
+      "order:items",
+      rowIdSchema,
+      async () => ({
+        rows: [
+          { sku: "KB-100", description: "Mechanical keyboard", quantity: 1, unitPrice: 148 },
+          { sku: "MS-220", description: "Wireless mouse", quantity: 2, unitPrice: 45 },
+          { sku: "PAD-01", description: "Desk mat", quantity: 1, unitPrice: 22 },
+        ],
+      }),
+      { access: { roles: ["Support", "Admin"] } },
+    );
+
+    r.queryHandler(
+      "order:payments",
+      rowIdSchema,
+      async () => ({
+        rows: [
+          { paidAt: "2026-08-21", amount: 936, method: "card", status: "settled" },
+          { paidAt: "2026-08-25", amount: 312, method: "invoice", status: "pending" },
+        ],
+      }),
+      { access: { roles: ["Support", "Admin"] } },
+    );
+
+    r.screen({
+      id: "order-detail",
+      type: "projectionDetail",
+      query: "order-desk:query:order:detail",
+      header: { title: "customerName", subtitle: "orderNumber", status: "status" },
+      metrics: ["totalAmount", "outstandingAmount", "itemCount", "placedAt"],
+      fieldLabels: {
+        totalAmount: "order-desk.metric.totalAmount",
+        outstandingAmount: "order-desk.metric.outstandingAmount",
+        itemCount: "order-desk.metric.itemCount",
+        placedAt: "order-desk.metric.placedAt",
+      },
+      layout: {
+        mode: "tabs",
+        sections: [
+          {
+            id: "items",
+            kind: "relatedList",
+            title: "order-desk.tab.items",
+            query: "order-desk:query:order:items",
+            columns: [
+              "sku",
+              "description",
+              "quantity",
+              { field: "unitPrice", renderer: { format: "currency", symbol: "€" } },
+            ],
+          },
+          {
+            id: "payments",
+            kind: "relatedList",
+            title: "order-desk.tab.payments",
+            query: "order-desk:query:order:payments",
+            columns: [
+              "paidAt",
+              { field: "amount", renderer: { format: "currency", symbol: "€" } },
+              "method",
+              "status",
+            ],
+          },
+          {
+            id: "details",
+            kind: "fields",
+            title: "order-desk.tab.details",
+            fields: ["shippingAddress", "billingAddress", "salesRep"],
+          },
+          {
+            id: "internal-note",
+            kind: "extension",
+            title: "order-desk.tab.internalNote",
+            component: { react: { __component: "OrderInternalNote" } },
+            entityName: "order",
+          },
+        ],
+      },
+      actions: [
+        {
+          kind: "navigate",
+          id: "refresh-order",
+          label: "order-desk.action.refreshOrder",
+          screen: "order-detail",
+          icon: "refresh",
+        },
+      ],
+      access: { roles: ["Support", "Admin"] },
+    });
+  });
+}
+```

package/agents/examples/reference-data.md

@@ -0,0 +1,151 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/reference-data. Do not edit. -->
+
+# reference-data
+
+Upsert-based seeds. Lookup tables done right.
+
+## README
+
+# Reference Data
+
+Seed reference data with `r.referenceData`.
+
+## What it shows
+
+- Declarative reference rows loaded at boot
+- Idempotent seeding for lookup tables
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/reference-data
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Reference Data Sample — Integration Test
+// Proves: seed data is inserted, upsert updates existing rows, new rows added
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { seedReferenceData } from "@cosmicdrift/kumiko-framework/db";
+import type { ReferenceDataDef } from "@cosmicdrift/kumiko-framework/engine";
+import { createTestDb, type TestDb, unsafePushTables } from "@cosmicdrift/kumiko-framework/stack";
+import { categoryFeature, categoryTable } from "../feature";
+
+let testDb: TestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafePushTables(testDb.db, { categoryTable });
+});
+
+afterAll(async () => {
+  await testDb?.cleanup();
+});
+
+type CategoryRow = { code: string; name: string; description: string | null };
+
+async function readCategories(): Promise<CategoryRow[]> {
+  const rows = await selectMany(testDb.db, categoryTable);
+  return [...rows].sort((a: CategoryRow, b: CategoryRow) => a.code.localeCompare(b.code));
+}
+
+describe("reference data seeding", () => {
+  test("inserts initial seed data", async () => {
+    const tables = new Map([["category", categoryTable]]);
+
+    // seedReferenceData(defs, tables, db)
+    await seedReferenceData(categoryFeature.referenceData, tables, testDb.db);
+
+    const rows = await readCategories();
+    expect(rows).toHaveLength(4);
+    expect(rows[0]?.code).toBe("books");
+    expect(rows[1]?.code).toBe("clothing");
+    expect(rows[2]?.code).toBe("electronics");
+    expect(rows[3]?.code).toBe("food");
+  });
+
+  test("upsert updates existing rows without duplicating", async () => {
+    const tables = new Map([["category", categoryTable]]);
+
+    // Modified seed data: changed name for "books", added new category
+    const updatedDefs: ReferenceDataDef[] = [
+      {
+        entityName: "category",
+        data: [
+          { code: "electronics", name: "Electronics", description: "Phones, laptops, tablets" },
+          { code: "clothing", name: "Clothing", description: "Shirts, pants, shoes" },
+          { code: "books", name: "Books & Media", description: "Books, audiobooks, magazines" },
+          { code: "food", name: "Food & Drinks", description: "Groceries and beverages" },
+          { code: "sports", name: "Sports", description: "Equipment and gear" },
+        ],
+        upsertKey: "code",
+      },
+    ];
+
+    await seedReferenceData(updatedDefs, tables, testDb.db);
+
+    const rows = await readCategories();
+    expect(rows).toHaveLength(5);
+
+    const books = rows.find((r: CategoryRow) => r.code === "books");
+    expect(books?.name).toBe("Books & Media");
+
+    const sports = rows.find((r: CategoryRow) => r.code === "sports");
+    expect(sports?.name).toBe("Sports");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Reference Data Sample
+// Shows: r.referenceData() for static seed data with upsert logic
+
+import { table, text } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const categoryEntity = createEntity({
+  table: "read_sample_categories",
+  fields: {
+    code: createTextField({ personal: false, reason: "is_reference_data", required: true }),
+    name: createTextField({ personal: false, reason: "is_reference_data", required: true }),
+    description: createTextField({ personal: false, reason: "is_reference_data" }),
+  },
+});
+
+// Drizzle table for direct DB queries in tests
+export const categoryTable = table("read_sample_categories", {
+  code: text("code").notNull(),
+  name: text("name").notNull(),
+  description: text("description"),
+});
+
+export const categoryFeature = defineFeature("catalog", (r) => {
+  r.entity("category", categoryEntity);
+
+  // Static reference data — seeded on boot, upserted on changes
+  r.referenceData(
+    "category",
+    [
+      { code: "electronics", name: "Electronics", description: "Phones, laptops, tablets" },
+      { code: "clothing", name: "Clothing", description: "Shirts, pants, shoes" },
+      { code: "books", name: "Books", description: "Fiction and non-fiction" },
+      { code: "food", name: "Food & Drinks", description: "Groceries and beverages" },
+    ],
+    { upsertKey: "code" },
+  );
+});
+```