@cosmicdrift/kumiko-framework 0.364.0 → 0.365.1

package/agents/examples/dashboard-stats.md

@@ -0,0 +1,229 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/dashboard-stats. Do not edit. -->
+
+# dashboard-stats
+
+Key figures on a dashboard: stat panels backed by one counting query.
+
+## README
+
+# Dashboard stats
+
+Key figures on a dashboard. This recipe ships a `ticket` entity, one query
+handler that returns the figures as a flat object, and a `dashboard` screen
+with a stat group (open, closed) and a single stat (total).
+
+The point is to show how the three pieces connect: the screen only names a
+query and the fields to read, the query does the counting.
+
+## What it shows
+
+- **Panels reference a query by qualified name**: each `stat` carries
+  `query: "tickets:query:ticket:stats"`. The dashboard calls that handler and
+  renders the result.
+- **`valueField` picks a field from a flat result**: the handler returns
+  `{ open, closed, total }`, and each stat names one of those keys.
+- **`stat-group` and `stat`**: a group shows several stats side by side under
+  one title, a top-level `stat` stands alone.
+- **Counting happens in the database**: the handler calls the executor's
+  `list` with `filter`, `limit: 1` and `totalCount: true`. The total is counted
+  over the whole WHERE clause, so no rows are loaded just to be counted.
+- **Labels are translation keys**: declared with `r.translations`.
+
+## When to reach for it
+
+You want a landing screen with a few numbers: open items, overdue invoices,
+this month's revenue. Write one query per screen that returns every figure,
+and let the stats pick their field.
+
+## Source
+
+The whole feature lives in `src/feature.ts` (~100 lines). The integration test
+checks that every stat reads a field the query returns, and that the query
+counts open and closed tickets correctly.
+
+```bash
+bun kumiko test integration samples/dashboard-stats
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Dashboard Stats Sample, integration test.
+// Proves: the dashboard screen boots, its panels point at a registered query,
+// and that query counts per status in the database.
+
+import { afterAll, beforeAll, 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,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { TICKET_STATS_QUERY, ticketEntity, ticketFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = createTestUser({ roles: ["Admin"], tenantId: testTenantId(31) });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [ticketFeature] });
+  await unsafeCreateEntityTable(stack.db, ticketEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("dashboard screen", () => {
+  test("boots, and every stat reads a field the stats query returns", async () => {
+    const screen = ticketFeature.screens["ticket-dashboard"];
+    if (screen?.type !== "dashboard") throw new Error("ticket-dashboard is not a dashboard screen");
+
+    const stats = screen.panels.flatMap((panel) =>
+      panel.kind === "stat-group" ? panel.stats : panel.kind === "stat" ? [panel] : [],
+    );
+    expect(stats.map((s) => s.valueField)).toEqual(["open", "closed", "total"]);
+    for (const stat of stats) expect(stat.query).toBe(TICKET_STATS_QUERY);
+
+    const result = await stack.http.queryOk<Record<string, unknown>>(TICKET_STATS_QUERY, {}, admin);
+    for (const stat of stats) expect(result).toHaveProperty(stat.valueField);
+  });
+});
+
+describe("ticket:stats", () => {
+  test("counts open and closed tickets in the database", async () => {
+    for (const [title, status] of [
+      ["a", "open"],
+      ["b", "open"],
+      ["c", "open"],
+      ["d", "closed"],
+      ["e", "closed"],
+    ] as const) {
+      await stack.http.writeOk<SaveContext>(
+        "tickets:write:ticket:create",
+        { title, status },
+        admin,
+      );
+    }
+
+    const result = await stack.http.queryOk<Record<string, unknown>>(TICKET_STATS_QUERY, {}, admin);
+
+    expect(result).toEqual({ open: 3, closed: 2, total: 5 });
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Dashboard Stats Sample
+// Shows: a dashboard screen with a stat-group and a single stat, backed by one
+// query handler that counts in the database.
+
+import {
+  createEntity,
+  createEntityExecutor,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const TICKET_STATUSES = ["open", "closed"] as const;
+
+export const ticketEntity = createEntity({
+  table: "read_sample_tickets",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    status: createSelectField({ options: TICKET_STATUSES, default: "open", required: true }),
+  },
+});
+
+export const TICKET_STATS_QUERY = "tickets:query:ticket:stats";
+
+const readerRoles = { roles: ["Admin", "User"] } as const;
+
+export const ticketFeature = defineFeature("tickets", (r) => {
+  const { executor: ticketExecutor } = createEntityExecutor("ticket", ticketEntity);
+
+  r.crud("ticket", ticketEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: readerRoles },
+  });
+
+  // Flat result: each dashboard stat reads one field via its valueField.
+  // limit: 1 keeps the page tiny; totalCount counts over the whole WHERE in
+  // the database, so no rows are loaded just to be counted.
+  r.queryHandler(
+    "ticket:stats",
+    z.object({}),
+    async (query, ctx) => {
+      const countWithStatus = async (status: (typeof TICKET_STATUSES)[number]): Promise<number> => {
+        const page = await ticketExecutor.list(
+          { filter: { field: "status", op: "eq", value: status }, limit: 1, totalCount: true },
+          query.user,
+          ctx.db,
+        );
+        return page.total ?? 0;
+      };
+      const [open, closed] = await Promise.all([
+        countWithStatus("open"),
+        countWithStatus("closed"),
+      ]);
+      return { open, closed, total: open + closed };
+    },
+    { access: readerRoles },
+  );
+
+  r.translations({
+    keys: {
+      "tickets.dashboard.group": { en: "Tickets by status" },
+      "tickets.dashboard.open": { en: "Open" },
+      "tickets.dashboard.closed": { en: "Closed" },
+      "tickets.dashboard.total": { en: "All tickets" },
+    },
+  });
+
+  r.screen({
+    id: "ticket-dashboard",
+    type: "dashboard",
+    panels: [
+      {
+        kind: "stat-group",
+        id: "by-status",
+        label: "tickets.dashboard.group",
+        stats: [
+          {
+            kind: "stat",
+            id: "open",
+            label: "tickets.dashboard.open",
+            query: TICKET_STATS_QUERY,
+            valueField: "open",
+          },
+          {
+            kind: "stat",
+            id: "closed",
+            label: "tickets.dashboard.closed",
+            query: TICKET_STATS_QUERY,
+            valueField: "closed",
+          },
+        ],
+      },
+      {
+        kind: "stat",
+        id: "total",
+        label: "tickets.dashboard.total",
+        query: TICKET_STATS_QUERY,
+        valueField: "total",
+      },
+    ],
+    access: readerRoles,
+  });
+});
+```

package/agents/examples/encrypted-tenant-config.md

@@ -155,7 +155,7 @@ import {
   createConfigFeature,
   createConfigResolver,
 } from "@cosmicdrift/kumiko-bundled-features/config";
-import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   setupTestStack,
   type TestStack,
@@ -166,10 +166,10 @@ import {
 import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import { billingFeature, stripeApiKeyHandle } from "../feature";
 
-const TENANT_A = testTenantId(1);
-const TENANT_B = testTenantId(2);
-const acmeAdmin = { ...TestUsers.admin, tenantId: TENANT_A };
-const globexAdmin = { ...TestUsers.admin, tenantId: TENANT_B, id: "globex-admin" };
+// Each test gets its own pair of tenants, so config rows from other tests never show up.
+let acmeAdmin = { ...TestUsers.admin, tenantId: testTenantId(1) };
+let globexAdmin = { ...TestUsers.admin, tenantId: testTenantId(2), id: "globex-admin" };
+let nextTenantPair = 0;
 
 let stack: TestStack;
 
@@ -190,8 +190,14 @@ beforeAll(async () => {
 
 afterAll(async () => stack?.cleanup());
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${configValuesTable.tableName}"`);
+beforeEach(() => {
+  nextTenantPair += 1;
+  acmeAdmin = { ...TestUsers.admin, tenantId: testTenantId(nextTenantPair * 2 + 1) };
+  globexAdmin = {
+    ...TestUsers.admin,
+    tenantId: testTenantId(nextTenantPair * 2 + 2),
+    id: "globex-admin",
+  };
 });
 
 describe("encrypted tenant-config: per-tenant Stripe-API-key", () => {
@@ -203,7 +209,10 @@ describe("encrypted tenant-config: per-tenant Stripe-API-key", () => {
       acmeAdmin,
     );
 
-    const rows = await selectMany(stack.db, configValuesTable, { key: stripeApiKeyHandle.name });
+    const rows = await selectMany(stack.db, configValuesTable, {
+      key: stripeApiKeyHandle.name,
+      tenantId: acmeAdmin.tenantId,
+    });
     expect(rows.length).toBe(1);
     const stored = rows[0]?.["value"];
     expect(typeof stored).toBe("string");

package/agents/examples/error-contract.md

@@ -115,8 +115,7 @@ The chain lands in the log (for forensics), but **not** in the response to the c
 // documented wire shape. If you extend the sample, add a matching test here
 // so the "copy this" guarantee stays valid.
 
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
@@ -142,9 +141,6 @@ beforeAll(async () => {
   await createEventsTable(stack.db);
 });
 afterAll(async () => stack.cleanup());
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${orderTable.tableName}"`);
-});
 
 // --- 1) Zod validation error via schema: empty cart rejected ---
 

package/agents/examples/feature-toggles.md

@@ -39,7 +39,7 @@ import {
   GlobalFeatureToggleRuntime,
   globalFeatureStateTable,
 } from "@cosmicdrift/kumiko-bundled-features/feature-toggles";
-import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
@@ -89,21 +89,36 @@ afterAll(async () => {
   await stack?.cleanup();
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${productAuditTable.tableName}"`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${productTable.tableName}"`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${globalFeatureStateTable.tableName}"`);
-  await runtime.refresh();
-});
-
 const admin = createTestUser({
   id: "11111111-1111-1111-1111-111111111111",
   tenantId: SYSTEM_TENANT_ID,
   roles: ["SystemAdmin"],
 });
 
+// Products and audit rows are system-wide by design, so tests isolate through
+// product names that are unique per test instead of per tenant.
+let testNumber = 0;
+let suffix = "";
+
+beforeEach(() => {
+  testNumber += 1;
+  suffix = `-t${testNumber}`;
+  runtime.apply("product", true);
+  runtime.apply("product-audit", true);
+});
+
+async function auditNames(): Promise<string[]> {
+  const rows = await selectMany(stack.db, productAuditTable);
+  return rows.map((row) => String(row["productName"])).filter((name) => name.endsWith(suffix));
+}
+
+async function productNames(): Promise<string[]> {
+  const rows = await selectMany(stack.db, productTable);
+  return rows.map((row) => String(row["name"])).filter((name) => name.endsWith(suffix));
+}
+
 async function createProduct(name: string) {
-  return stack.http.write("product:write:product:create", { name }, admin);
+  return stack.http.write("product:write:product:create", { name: `${name}${suffix}` }, admin);
 }
 
 describe("feature-toggles showcase", () => {
@@ -111,8 +126,7 @@ describe("feature-toggles showcase", () => {
     // ON
     const ok = await createProduct("alpha");
     expect((await ok.json()).isSuccess).toBe(true);
-    const auditRowsAfterOn = await selectMany(stack.db, productAuditTable);
-    expect(auditRowsAfterOn.length).toBe(1);
+    expect(await auditNames()).toHaveLength(1);
 
     // OFF
     runtime.apply("product", false);
@@ -127,8 +141,7 @@ describe("feature-toggles showcase", () => {
     runtime.apply("product", true);
     const again = await createProduct("gamma");
     expect((await again.json()).isSuccess).toBe(true);
-    const auditRowsAfterReEnable = await selectMany(stack.db, productAuditTable);
-    expect(auditRowsAfterReEnable.length).toBe(2);
+    expect(await auditNames()).toHaveLength(2);
   });
 
   test("cross-feature hook: disabling product-audit skips its hook but product keeps working", async () => {
@@ -137,11 +150,9 @@ describe("feature-toggles showcase", () => {
     const ok = await createProduct("delta");
     expect((await ok.json()).isSuccess).toBe(true);
     // Product row written — handler unaffected.
-    const productRows = await selectMany(stack.db, productTable);
-    expect(productRows.length).toBe(1);
+    expect(await productNames()).toHaveLength(1);
     // Audit hook owned by product-audit — silently skipped.
-    const auditRows = await selectMany(stack.db, productAuditTable);
-    expect(auditRows.length).toBe(0);
+    expect(await auditNames()).toHaveLength(0);
   });
 });
 ```

package/agents/examples/ledger-banking.md

@@ -72,17 +72,19 @@ import {
   createLedgerFeature,
   transactionEntity,
 } from "@cosmicdrift/kumiko-bundled-features/ledger";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
   setupTestStack,
   type TestStack,
+  testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { bankingFlow, type LedgerClient } from "../usage";
 
-const admin = createTestUser({ roles: ["TenantAdmin"] });
+// Each test runs in its own tenant, so rows from other tests never show up.
+let admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(1) });
+let nextTenant = 1;
 const ledger = createLedgerFeature();
 
 let stack: TestStack;
@@ -104,10 +106,9 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
-  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_accounts");
-  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_transactions");
+beforeEach(() => {
+  nextTenant += 1;
+  admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(nextTenant) });
 });
 
 describe("ledger-banking recipe — transfer + derived balance", () => {

package/agents/examples/ledger-invoicing.md

@@ -81,17 +81,19 @@ import {
   createLedgerFeature,
   transactionEntity,
 } from "@cosmicdrift/kumiko-bundled-features/ledger";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
   setupTestStack,
   type TestStack,
+  testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { invoicingFlow, type LedgerClient } from "../usage";
 
-const admin = createTestUser({ roles: ["TenantAdmin"] });
+// Each test runs in its own tenant, so rows from other tests never show up.
+let admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(1) });
+let nextTenant = 1;
 const ledger = createLedgerFeature();
 
 let stack: TestStack;
@@ -112,10 +114,9 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
-  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_accounts");
-  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_transactions");
+beforeEach(() => {
+  nextTenant += 1;
+  admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(nextTenant) });
 });
 
 describe("ledger-invoicing recipe — accrual + receivable lifecycle", () => {

package/agents/examples/legal-pages.md

@@ -95,8 +95,8 @@ imprint" decision.
 
 ```bash
 # In the app workspace:
-bun kumiko-schema generate <name>    # detects text-block entity → SQL migration
-bun kumiko-schema apply       # one-time (pre-deploy step in prod)
+bunx kumiko-schema generate <name>    # detects text-block entity → SQL migration
+bunx kumiko-schema apply       # one-time (pre-deploy step in prod)
 ```
 
 ### 3. Initial seed of the required blocks

package/agents/examples/managed-pages.md

@@ -89,8 +89,8 @@ the recipe lists `createConfigFeature()` explicitly (see `src/feature.ts`).
 ### 2. Create the table
 
 ```bash
-bun kumiko-schema generate <name>    # detects the `page` entity → SQL migration
-bun kumiko-schema apply
+bunx kumiko-schema generate <name>    # detects the `page` entity → SQL migration
+bunx kumiko-schema apply
 ```
 
 ### 3. Authoring + branding

package/agents/examples/notes-history-basic.md

@@ -121,18 +121,20 @@ import {
   noteMentionEntity,
   notesHistoryFeature,
 } from "@cosmicdrift/kumiko-bundled-features/notes-history";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
   setupTestStack,
   type TestStack,
+  testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { taskEntity, taskFeature } from "../feature";
 import { type NotesClient, notesFlow } from "../usage";
 
-const admin = createTestUser({ roles: ["TenantAdmin"] });
+// Each test runs in its own tenant, so rows from other tests never show up.
+let admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(1) });
+let nextTenant = 1;
 
 // Adapt the test stack to the host-facing NotesClient the docs embed uses.
 const notesClient: NotesClient = {
@@ -154,10 +156,9 @@ 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_notes_history_tasks");
-  await asRawClient(stack.db).unsafe("DELETE FROM read_note_entries");
+beforeEach(() => {
+  nextTenant += 1;
+  admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(nextTenant) });
 });
 
 async function createTask(id: string, title: string) {

package/agents/examples/ownership.md

@@ -39,7 +39,7 @@ bun test
 // feature. Each test maps directly to a cell in the design-doc matrix.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
   setupTestStack,
@@ -52,26 +52,33 @@ import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
 import { contractEntity, contractsFeature, teamsFeature } from "../feature";
 
 let stack: TestStack;
-const tenant = testTenantId(1);
-
-const admin = { ...TestUsers.admin, tenantId: tenant };
-const teamMemberEng = createTestUser({
-  id: "11111111-0000-4000-8000-000000000001",
-  tenantId: tenant,
-  roles: ["TeamMember"],
-  claims: { "teams:teamId": "eng" },
-});
-const teamMemberOps = createTestUser({
-  id: "11111111-0000-4000-8000-000000000002",
-  tenantId: tenant,
-  roles: ["TeamMember"],
-  claims: { "teams:teamId": "ops" },
-});
-const driverAlice = createTestUser({
-  id: "22222222-0000-4000-8000-000000000001",
-  tenantId: tenant,
-  roles: ["Driver"],
-});
+
+function usersForTenant(tenant: TenantId) {
+  return {
+    admin: { ...TestUsers.admin, tenantId: tenant },
+    teamMemberEng: createTestUser({
+      id: "11111111-0000-4000-8000-000000000001",
+      tenantId: tenant,
+      roles: ["TeamMember"],
+      claims: { "teams:teamId": "eng" },
+    }),
+    teamMemberOps: createTestUser({
+      id: "11111111-0000-4000-8000-000000000002",
+      tenantId: tenant,
+      roles: ["TeamMember"],
+      claims: { "teams:teamId": "ops" },
+    }),
+    driverAlice: createTestUser({
+      id: "22222222-0000-4000-8000-000000000001",
+      tenantId: tenant,
+      roles: ["Driver"],
+    }),
+  };
+}
+
+// Each test runs in its own tenant, so contract rows from other tests never show up.
+let nextTenant = 1;
+let { admin, teamMemberEng, teamMemberOps, driverAlice } = usersForTenant(testTenantId(nextTenant));
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [teamsFeature, contractsFeature] });
@@ -87,7 +94,8 @@ let engRowVersion: number;
 let opsRowId: string;
 
 beforeEach(async () => {
-  await asRawClient(stack.db).unsafe("DELETE FROM read_ownership_contracts");
+  nextTenant += 1;
+  ({ admin, teamMemberEng, teamMemberOps, driverAlice } = usersForTenant(testTenantId(nextTenant)));
   const eng = await stack.http.writeOk<{ id: string; data: { version: number } }>(
     "contracts:write:contract:create",
     {