@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/ownership.md

@@ -0,0 +1,396 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/ownership. Do not edit. -->
+
+# ownership
+
+Entity- and Field-level Row-Ownership: from() helper, Straddle-safe multi-role checks, Field-level Read/Write filtering.
+
+## README
+
+# Ownership
+
+Row-level ownership for read and write.
+
+## What it shows
+
+- Entity- and field-level ownership rules
+- Straddle-safe checks across tenants/users
+
+## 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/ownership
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Ownership Sample — Integration Test
+//
+// Drives the whole Read/Write × Entity/Field matrix against the contract
+// 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 {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+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"],
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [teamsFeature, contractsFeature] });
+  await unsafeCreateEntityTable(stack.db, contractEntity, "contract");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+let engRowId: string;
+let engRowVersion: number;
+let opsRowId: string;
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM read_ownership_contracts");
+  const eng = await stack.http.writeOk<{ id: string; data: { version: number } }>(
+    "contracts:write:contract:create",
+    {
+      teamId: "eng",
+      assigneeId: driverAlice.id,
+      propA: "public-eng",
+      propB: "admin-eng",
+      propC: "team-eng",
+    },
+    admin,
+  );
+  engRowId = eng.id;
+  engRowVersion = eng.data.version;
+  const ops = await stack.http.writeOk<{ id: string }>(
+    "contracts:write:contract:create",
+    {
+      teamId: "ops",
+      propA: "public-ops",
+      propB: "admin-ops",
+      propC: "team-ops",
+    },
+    admin,
+  );
+  opsRowId = ops.id;
+});
+
+// --- Entity-level READ ---
+
+describe("entity-level read: list / detail filtering", () => {
+  test("Admin lists both rows", async () => {
+    const res = await stack.http.queryOk<{ rows: Array<{ teamId: string }> }>(
+      "contracts:query:contract:list",
+      {},
+      admin,
+    );
+    expect(res.rows).toHaveLength(2);
+  });
+
+  test("TeamMember eng lists only eng's row", async () => {
+    const res = await stack.http.queryOk<{ rows: Array<{ teamId: string }> }>(
+      "contracts:query:contract:list",
+      {},
+      teamMemberEng,
+    );
+    expect(res.rows).toHaveLength(1);
+    expect(res.rows[0]?.teamId).toBe("eng");
+  });
+
+  test("Driver alice lists only rows assigned to her", async () => {
+    const res = await stack.http.queryOk<{ rows: Array<{ assigneeId: string }> }>(
+      "contracts:query:contract:list",
+      {},
+      driverAlice,
+    );
+    expect(res.rows).toHaveLength(1);
+    expect(res.rows[0]?.assigneeId).toBe(driverAlice.id);
+  });
+
+  test("TeamMember eng getting ops row via detail → null (indistinguishable from not-found)", async () => {
+    const res = await stack.http.queryOk(
+      "contracts:query:contract:detail",
+      {
+        id: opsRowId,
+      },
+      teamMemberEng,
+    );
+    expect(res).toBeNull();
+  });
+});
+
+// --- Field-level READ ---
+
+describe("field-level read: response JSON strips unreadable fields", () => {
+  test("TeamMember eng sees propA + propC; propB missing", async () => {
+    const res = await stack.http.queryOk<Record<string, unknown>>(
+      "contracts:query:contract:detail",
+      { id: engRowId },
+      teamMemberEng,
+    );
+    expect(res["propA"]).toBe("public-eng");
+    expect(res["propC"]).toBe("team-eng");
+    expect(res).not.toHaveProperty("propB");
+  });
+
+  test("TeamMember ops reading eng's row — blocked at entity level (detail=null)", async () => {
+    const res = await stack.http.queryOk(
+      "contracts:query:contract:detail",
+      {
+        id: engRowId,
+      },
+      teamMemberOps,
+    );
+    expect(res).toBeNull();
+  });
+});
+
+// --- Entity-level WRITE ---
+
+describe("entity-level write: create/update/delete blocked on foreign rows", () => {
+  test("TeamMember eng CANNOT create an ops-team contract", async () => {
+    const err = await stack.http.writeErr(
+      "contracts:write:contract:create",
+      { teamId: "ops", propA: "rogue" },
+      teamMemberEng,
+    );
+    expectErrorIncludes(err, "ownership_denied");
+  });
+
+  test("TeamMember eng CANNOT update the ops row (not visible → not modifiable)", async () => {
+    // The row exists but entity-level ownership rejects the update.
+    // version is guessed — doesn't matter, the ownership check fires first.
+    const err = await stack.http.writeErr(
+      "contracts:write:contract:update",
+      { id: opsRowId, version: 1, changes: { propA: "hack" } },
+      teamMemberEng,
+    );
+    expectErrorIncludes(err, "ownership_denied");
+  });
+
+  test("TeamMember eng CANNOT move their row to another team (teamId rewrite blocked)", async () => {
+    const err = await stack.http.writeErr(
+      "contracts:write:contract:update",
+      {
+        id: engRowId,
+        version: engRowVersion,
+        changes: { teamId: "ops" },
+      },
+      teamMemberEng,
+    );
+    expectErrorIncludes(err, "ownership_denied");
+  });
+});
+
+// --- Field-level WRITE ---
+
+describe("field-level write: individual fields rejected fail-loud", () => {
+  test("TeamMember eng updating propB (Admin-only) → access_denied (role gate)", async () => {
+    const err = await stack.http.writeErr(
+      "contracts:write:contract:update",
+      {
+        id: engRowId,
+        version: engRowVersion,
+        changes: { propB: "sneak" },
+      },
+      teamMemberEng,
+    );
+    expectErrorIncludes(err, "access_denied");
+  });
+
+  test("TeamMember eng updating propA succeeds on their own row", async () => {
+    const res = await stack.http.writeOk<{ data: { propA: string } }>(
+      "contracts:write:contract:update",
+      {
+        id: engRowId,
+        version: engRowVersion,
+        changes: { propA: "my-edit" },
+      },
+      teamMemberEng,
+    );
+    expect(res.data.propA).toBe("my-edit");
+  });
+});
+
+// --- Admin short-circuit ---
+
+describe("admin-all short-circuit skips every ownership predicate", () => {
+  test("Admin reads both rows with all fields intact", async () => {
+    const eng = await stack.http.queryOk<Record<string, unknown>>(
+      "contracts:query:contract:detail",
+      { id: engRowId },
+      admin,
+    );
+    expect(eng["propA"]).toBe("public-eng");
+    expect(eng["propB"]).toBe("admin-eng");
+    expect(eng["propC"]).toBe("team-eng");
+  });
+
+  test("Admin updates, deletes, restores on any team", async () => {
+    const updated = await stack.http.writeOk<{ data: { propB: string; version: number } }>(
+      "contracts:write:contract:update",
+      {
+        id: opsRowId,
+        version: 1,
+        changes: { propB: "admin-edit-across-teams" },
+      },
+      admin,
+    );
+    expect(updated.data.propB).toBe("admin-edit-across-teams");
+    const deleted = await stack.http.writeOk<{ id: string }>(
+      "contracts:write:contract:delete",
+      { id: opsRowId },
+      admin,
+    );
+    expect(deleted.id).toBe(opsRowId);
+    const restored = await stack.http.writeOk<{ id: string }>(
+      "contracts:write:contract:restore",
+      { id: opsRowId },
+      admin,
+    );
+    expect(restored.id).toBe(opsRowId);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Ownership Sample
+//
+// Concrete contract-entity showing the full ownership matrix:
+//
+//   Dimension      Entity-level           Field-level
+//   ---------      ------------           -----------
+//   Read           list/detail filter     propX stripped from response JSON
+//   Write          create/update/delete   individual fields rejected loud
+//   Rule shape     { Role: OwnershipRule } (same on both dimensions)
+//   Rule kinds     "all" / from(ref, col?) / { where: (user, table) => SQL }
+//
+// The entity below is the "contract" example from the H.2 design
+// discussion: propA is public, propB is Admin-only, propC requires a
+// matching team claim. Integration tests prove each row/column path.
+//
+// Why fail-loud on write (not silent drop): Silent-drop makes bugs
+// invisible at the reporting layer. "Save doesn't work" with no error
+// becomes weeks of blame between frontend / API / infrastructure. A loud
+// `field_ownership_denied` with the field name + role + userId in the
+// details payload is a single log-line to a root cause.
+
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  from,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// The "teams" feature declares the teamId claim. Any other feature can
+// reference it via the QN string "teams:teamId" in ownership rules — no
+// cross-feature import needed. The boot-validator rejects a reference to a
+// claim no feature declared.
+export const teamsFeature = defineFeature("teams", (r) => {
+  r.claimKey("teamId", { type: "string" });
+});
+
+// Contract entity demonstrating the full access matrix.
+export const contractEntity = createEntity({
+  table: "read_ownership_contracts",
+  softDelete: true,
+  fields: {
+    // teamId is the ownership-scoping column. It's referenced by claim-rules
+    // via the default column (rule's shortName = "teamId" matches).
+    teamId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+    // Optional — when set, only that user (via user:id rule) can access.
+    assigneeId: createTextField({ personal: "ref" }),
+
+    // propA: public field. No access declared — every caller reads AND writes.
+    propA: createTextField({ personal: false, reason: "is_business_data" }),
+
+    // propB: Admin-only. Non-admins don't see it in responses; attempts
+    // to write it return access_denied (role gate in dispatcher).
+    propB: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      access: {
+        read: { Admin: "all" },
+        write: { Admin: "all" },
+      },
+    }),
+
+    // propC: Admin + Matching-Team. Non-admins with the wrong team see no
+    // propC in responses; writes to propC on a foreign team's row return
+    // field_ownership_denied (executor ownership check).
+    propC: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      access: {
+        read: { Admin: "all", TeamMember: from("claim:teams:teamId") },
+        write: { Admin: "all", TeamMember: from("claim:teams:teamId") },
+      },
+    }),
+  },
+
+  // Entity-level access: controls list/detail/update/delete/restore of the
+  // whole row. Admin sees everything; TeamMember scoped to their team;
+  // assigned Driver sees rows assigned to them.
+  access: {
+    read: {
+      Admin: "all",
+      TeamMember: from("claim:teams:teamId"),
+      Driver: from("user:id", "assigneeId"),
+    },
+    write: {
+      Admin: "all",
+      TeamMember: from("claim:teams:teamId"),
+      Driver: from("user:id", "assigneeId"),
+    },
+  },
+});
+
+export const contractsFeature = defineFeature("contracts", (r) => {
+  const contractAccess = { access: { roles: ["Admin", "TeamMember", "Driver"] } } as const;
+  r.crud("contract", contractEntity, {
+    write: contractAccess,
+    read: contractAccess,
+  });
+});
+```

package/agents/examples/pdf-audit-export.md

@@ -0,0 +1,270 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/pdf-audit-export. Do not edit. -->
+
+# pdf-audit-export
+
+Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and stores the bytes as a FileRef via createFileRefFromBytes.
+
+## README
+
+# PDF Audit Export
+
+A write handler exports tenant data as a PDF and keeps it as a FileRef.
+
+## What it shows
+
+- `renderTablePdf` (`@cosmicdrift/kumiko-bundled-features/renderer-pdf`) draws a table document in pure JavaScript: repeating header, weighted columns, page footer. The handler passes ready-formatted strings.
+- `createFileRefFromBytes` (`@cosmicdrift/kumiko-framework/files`) stores the bytes like an upload (validation, tenant-prefixed storage key, `fileRef.created` event); the tenant comes from the caller.
+- The result is a normal FileRef: `GET /api/files/:id` serves it with `Content-Type: application/pdf`, other tenants get 404.
+
+## Source
+
+Feature entry point: `src/feature.ts`. The export reads at most 200 inspections per call.
+
+## 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/pdf-audit-export
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// PDF Audit Export Sample — Integration Test
+//
+// Proves the whole path through real HTTP calls: inspections are written,
+// the export handler renders and stores a PDF, GET /api/files/:id serves it
+// and its text contains exactly the inspections of the requested period.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createFilesFeature,
+  createInMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { extractText, getDocumentProxy } from "unpdf";
+import { inspectionEntity, pdfAuditExportFeature } from "../feature";
+
+let stack: TestStack;
+
+const userA = createTestUser({ id: 1, tenantId: testTenantId(1), roles: ["Admin"] });
+const userB = createTestUser({ id: 2, tenantId: testTenantId(2), roles: ["Admin"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createFilesFeature(), pdfAuditExportFeature],
+    files: { storageProvider: createInMemoryFileProvider() },
+  });
+  await unsafeCreateEntityTable(stack.db, inspectionEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function addInspection(
+  inspectedOn: string,
+  result: "ok" | "defect",
+  inspector: string,
+  assetName = "Kessel 3",
+): Promise<void> {
+  await stack.http.writeOk(
+    "pdf-audit-export:write:inspection:create",
+    { assetName, inspectedOn, result, inspector },
+    userA,
+  );
+}
+
+async function download(user: typeof userA, fileRefId: string): Promise<Response> {
+  const token = await stack.jwt.sign(user);
+  return stack.app.request(`/api/files/${fileRefId}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+}
+
+describe("export-audit", () => {
+  test("stores a PDF FileRef containing only the inspections of the period and asset", async () => {
+    await addInspection("2026-01-10", "ok", "Zeile-vor-Zeitraum");
+    await addInspection("2026-02-05", "defect", "Zeile-im-Zeitraum-Eins");
+    await addInspection("2026-03-20", "ok", "Zeile-im-Zeitraum-Zwei");
+    await addInspection("2026-05-02", "ok", "Zeile-nach-Zeitraum");
+    await addInspection("2026-02-06", "ok", "Zeile-anderer-Asset", "Pumpe 7");
+
+    const { fileRefId } = await stack.http.writeOk<{ fileRefId: string }>(
+      "pdf-audit-export:write:export-audit",
+      { assetName: "Kessel 3", from: "2026-02-01", to: "2026-03-31" },
+      userA,
+    );
+
+    const res = await download(userA, fileRefId);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("application/pdf");
+    const proxy = await getDocumentProxy(new Uint8Array(await res.arrayBuffer()));
+    const { text } = await extractText(proxy, { mergePages: true });
+
+    expect(text).toContain("Prüfprotokoll Kessel 3");
+    expect(text).toContain("05.02.2026");
+    expect(text).toContain("Mangel");
+    expect(text).toContain("Zeile-im-Zeitraum-Eins");
+    expect(text).toContain("20.03.2026");
+    expect(text).toContain("Zeile-im-Zeitraum-Zwei");
+    expect(text).not.toContain("Zeile-vor-Zeitraum");
+    expect(text).not.toContain("Zeile-nach-Zeitraum");
+    expect(text).not.toContain("Zeile-anderer-Asset");
+    expect(text).toContain("Seite 1 von 1");
+  });
+
+  test("a user of another tenant gets 404 for the exported file", async () => {
+    await addInspection("2026-02-05", "ok", "Zeile-Tenant-A");
+    const { fileRefId } = await stack.http.writeOk<{ fileRefId: string }>(
+      "pdf-audit-export:write:export-audit",
+      { assetName: "Kessel 3", from: "2026-02-01", to: "2026-03-31" },
+      userA,
+    );
+
+    expect((await download(userB, fileRefId)).status).toBe(404);
+  });
+
+  test("a period without inspections still yields a PDF with the empty hint", async () => {
+    const { fileRefId } = await stack.http.writeOk<{ fileRefId: string }>(
+      "pdf-audit-export:write:export-audit",
+      { assetName: "Unbekannte Anlage", from: "2026-02-01", to: "2026-03-31" },
+      userA,
+    );
+
+    const res = await download(userA, fileRefId);
+    const proxy = await getDocumentProxy(new Uint8Array(await res.arrayBuffer()));
+    const { text } = await extractText(proxy, { mergePages: true });
+    expect(text).toContain("Keine Prüfungen im Zeitraum");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// PDF Audit Export Sample
+//
+// A write handler turns tenant data into a PDF and keeps it as a regular
+// FileRef: renderTablePdf draws the table (pure JS, no browser), then
+// createFileRefFromBytes stores the bytes through the same validation,
+// storage layout and fileRef.created event as an upload.
+
+import { renderTablePdf } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
+import {
+  createDateField,
+  createEntity,
+  createEntityExecutor,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createFileRefFromBytes } from "@cosmicdrift/kumiko-framework/files";
+import * as z from "zod";
+
+export const INSPECTION_RESULTS = ["ok", "defect"] as const;
+
+export const inspectionEntity = createEntity({
+  table: "read_sample_inspections",
+  fields: {
+    assetName: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    inspectedOn: createDateField({ required: true }),
+    result: createSelectField({ options: INSPECTION_RESULTS, required: true }),
+    inspector: createTextField({ personal: "ref" }),
+  },
+});
+
+const RESULT_LABELS: Readonly<Record<(typeof INSPECTION_RESULTS)[number], string>> = {
+  ok: "In Ordnung",
+  defect: "Mangel",
+};
+
+// The renderer takes ready-formatted strings, so date formatting stays with the caller.
+function formatGermanDate(isoDate: string): string {
+  const [year, month, day] = isoDate.split("-");
+  return `${day}.${month}.${year}`;
+}
+
+function toFileNameSegment(text: string): string {
+  return text.replaceAll(/[^A-Za-z0-9_-]+/g, "-");
+}
+
+const AUDIT_ROW_LIMIT = 200;
+
+const access = { access: { roles: ["Admin", "User"] } } as const;
+
+export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
+  r.entity("inspection", inspectionEntity);
+  const { executor: inspectionExecutor } = createEntityExecutor("inspection", inspectionEntity);
+
+  r.writeHandler(
+    "inspection:create",
+    z.object({
+      assetName: z.string().min(1),
+      inspectedOn: z.iso.date(),
+      result: z.enum(INSPECTION_RESULTS),
+      inspector: z.string().optional(),
+    }),
+    async (event, ctx) => inspectionExecutor.create(event.payload, event.user, ctx.db),
+    access,
+  );
+
+  r.writeHandler(
+    "export-audit",
+    z.object({ assetName: z.string().min(1), from: z.iso.date(), to: z.iso.date() }),
+    async (event, ctx) => {
+      const { assetName, from, to } = event.payload;
+      const inspections = await inspectionExecutor.list(
+        {
+          filters: [
+            { field: "assetName", op: "eq", value: assetName },
+            { field: "inspectedOn", op: "gte", value: from },
+            { field: "inspectedOn", op: "lte", value: to },
+          ],
+          sort: "inspectedOn",
+          sortDirection: "asc",
+          limit: AUDIT_ROW_LIMIT,
+        },
+        event.user,
+        ctx.db,
+      );
+
+      const { pdfBytes } = await renderTablePdf({
+        title: `Prüfprotokoll ${assetName}`,
+        meta: [
+          { label: "Zeitraum", value: `${formatGermanDate(from)} bis ${formatGermanDate(to)}` },
+          { label: "Prüfungen", value: String(inspections.rows.length) },
+        ],
+        columns: [{ header: "Datum" }, { header: "Ergebnis" }, { header: "Prüfer", weight: 2 }],
+        rows: inspections.rows.map((row) => [
+          formatGermanDate(String(row["inspectedOn"])),
+          RESULT_LABELS[z.enum(INSPECTION_RESULTS).parse(row["result"])],
+          String(row["inspector"] ?? ""),
+        ]),
+        emptyText: "Keine Prüfungen im Zeitraum",
+        footerText: `Prüfbericht ${assetName}`,
+        pageLabel: "Seite {page} von {pages}",
+      });
+
+      const created = await createFileRefFromBytes(ctx, {
+        fileName: `audit-${toFileNameSegment(assetName)}.pdf`,
+        mimeType: "application/pdf",
+        data: pdfBytes,
+      });
+      if (!created.isSuccess) return created;
+      return { isSuccess: true as const, data: { fileRefId: created.data.id } };
+    },
+    access,
+  );
+});
+```