@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/tags-basic.md

@@ -0,0 +1,401 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/tags-basic. Do not edit. -->
+
+# tags-basic
+
+Tag and group any entity without changing it — host-agnostic, event-sourced.
+
+## README
+
+# Tags
+
+Tag and group **any** entity — without adding a column to it, writing a
+migration, or touching its feature. The recipe creates a plain `note`
+entity that knows nothing about tags, then tags and groups notes through
+the `tags` bundle alone.
+
+The result: a note can carry any number of tags, you can ask "which tags
+does this note have?" and "which notes carry this tag?", and the `note`
+row stays exactly `{ id, title }`.
+
+## What it shows
+
+- **Zero host changes** — `note` has no tag column, no `wireTagsFor`, no
+  tag awareness. Tagging works anyway, because the tags feature owns its
+  own tables.
+- **`tags:write:create-tag`** — adds a tag to the tenant's catalog
+  (`read_tags`). Takes an optional `color` (rendered as a colored chip by
+  the web UI) and an optional `scope` (empty = global, or an entity type to
+  restrict it to). Returns the tag's id.
+- **`tags:write:update-tag` / `delete-tag`** — rename / recolor / re-scope a
+  tag (optimistic-locked), or delete it (cascades over its assignments).
+- **`tags:write:assign-tag` / `remove-tag`** — link/unlink a tag and an
+  entity by `{ tagId, entityType, entityId }`. Both are idempotent:
+  re-assigning is a no-op, removing a non-existent link still succeeds.
+- **Read-layer composition, no JOIN** — "tags of a note" lists
+  `tag-assignment` filtered by `entityId`; "notes with a tag" filters by
+  `tagId`. The app composes the two reads; there is no relational pivot.
+
+## Using it — the tag flow
+
+You use the bundle by dispatching its handlers; nothing is wired into the
+tagged entity. A host needs just two calls — `write` and `query` — which any
+app dispatcher provides. The flow below is embedded from `usage.ts` and is
+run end-to-end against the real dispatcher + DB by this recipe's integration
+test (`the documented tagFlow runs …`):
+
+```ts file=<rootDir>/_samples/recipes-tags-basic/src/usage.ts
+```
+
+## Web UI — the drop-in `<TagSection>`
+
+You don't have to hand-build a tag UI. The feature ships one from its client
+subpath `@cosmicdrift/kumiko-bundled-features/tags/web`: `<TagSection>` takes an
+`entityName` + `entityId`, shows that entity's tags, and lets the user attach an
+existing tag, create-and-attach a new one, or detach — calling the same handlers
+as above. Register `tagsClient()` once (for its component + i18n), then mount it
+either way:
+
+```tsx illustration
+import { createKumikoApp } from "@cosmicdrift/kumiko-renderer-web";
+import { tagsClient, TagSection, TAGS_SECTION_EXTENSION_NAME } from "@cosmicdrift/kumiko-bundled-features/tags/web";
+
+// once, at app boot — required even for standalone use (registers i18n):
+createKumikoApp({ clientFeatures: [tagsClient()] });
+
+// standalone — drop it into any screen, no entityEdit screen needed:
+<TagSection entityName="note" entityId={noteId} />
+
+// or as an extension section in an entityEdit screen schema:
+{ kind: "extension", title: "Tags", component: { react: { __component: TAGS_SECTION_EXTENSION_NAME } } }
+```
+
+The component itself is `tags/web/tag-section.tsx`
+([source](https://github.com/CosmicDriftGameStudio/kumiko-framework/blob/main/packages/bundled-features/src/tags/web/tag-section.tsx))
+and is covered by a unit test that asserts the exact handlers it dispatches.
+
+`tagsClient()` also ships the rest of the GitLab-style surface: a standalone
+`tag-list` **management screen** (`TagManager` — the whole catalog with colors,
+scopes, and usage counts), a `<TagFilter>` header-slot control that filters any
+`entityList` by tag, and a read-only `<EntityTags>` chip row for cards/detail.
+See the [tags feature reference](/en/bundled-features/tags/) for the full set.
+
+## Feature composition
+
+```
+tags             → core bundle: tag + tag-assignment entities,
+                   create/assign/remove handlers, list queries
+note-management  → our feature: a plain `note` entity. Declares
+                   r.requires("tags") only so the bundle is mounted —
+                   the note itself is completely tag-agnostic.
+```
+
+## Why it's event-sourced, not a pivot table
+
+Kumiko is event-sourced: there are no relational pivots queried by JOIN.
+The `tag-assignment` entity is a feature-owned, event-sourced join row
+keyed by `(entityType, entityId)`, and the framework projects it into
+`read_tag_assignments` from its own events. A deterministic aggregate-id
+per `(tenant, tag, entity)` makes assigning idempotent. Cross-entity
+views (a note's tags, a tag's notes) are assembled by reading that
+projection and composing in the app — never by joining across aggregates.
+
+## Run
+
+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
+bun test src/__tests__/feature.integration.test.ts
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Tags Basic — integration test.
+//
+// Proves the host-agnostic tagging flow via the real dispatcher + DB:
+//   1. a plain `note` is created (the note feature knows nothing about tags)
+//   2. a tag is created in the catalog
+//   3. the tag is assigned to the note by (entityType, entityId)
+//   4. "tags of this note" and "notes with this tag" both read from
+//      tag-assignment — read-layer composition, no JOIN, no column on `note`
+//   5. removing the tag detaches it
+//
+// This is the smallest evidence that an entity needs zero tag-wiring.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  createTagsFeature,
+  tagAssignmentEntity,
+  tagEntity,
+} from "@cosmicdrift/kumiko-bundled-features/tags";
+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 { noteEntity, noteFeature } from "../feature";
+import { type TagClient, tagFlow } from "../usage";
+
+const admin = createTestUser({ roles: ["TenantAdmin"] });
+
+// Adapt the test stack to the host-facing TagClient the docs embed uses.
+const tagClient: TagClient = {
+  write: <T>(type: string, payload: unknown) => stack.http.writeOk<T>(type, payload, admin),
+  query: <T>(type: string, payload: unknown) => stack.http.queryOk<T>(type, payload, admin),
+};
+const tags = createTagsFeature();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [tags, noteFeature] });
+  await unsafeCreateEntityTable(stack.db, tagEntity);
+  await unsafeCreateEntityTable(stack.db, tagAssignmentEntity);
+  await unsafeCreateEntityTable(stack.db, noteEntity);
+  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_tags_notes");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_tags");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_tag_assignments");
+});
+
+async function createNote(id: string, title: string) {
+  return stack.http.writeOk("note-management:write:note:create", { id, title }, admin);
+}
+
+async function createTag(name: string): Promise<string> {
+  const tag = await stack.http.writeOk<{ id: string }>("tags:write:create-tag", { name }, admin);
+  return tag.id;
+}
+
+async function assignTag(tagId: string, entityId: string) {
+  return stack.http.writeOk(
+    "tags:write:assign-tag",
+    { tagId, entityType: "note", entityId },
+    admin,
+  );
+}
+
+// Read-layer composition: list assignments filtered on entityId → the note's
+// tag ids. No JOIN, no tag column on `note`.
+async function tagIdsOfNote(entityId: string): Promise<string[]> {
+  const res = await stack.http.queryOk<{ rows: Array<{ tagId: string }> }>(
+    "tags:query:tag-assignment:list",
+    { filter: { field: "entityId", op: "eq", value: entityId } },
+    admin,
+  );
+  return res.rows.map((r) => r.tagId);
+}
+
+describe("tags-basic recipe — assign + compose", () => {
+  // Exercises the exact code embedded on the docs page (usage.ts → tagFlow).
+  test("the documented tagFlow runs create → assign → compose → remove", async () => {
+    const noteId = "55555555-5555-4000-8000-000000000005";
+    await createNote(noteId, "Documented flow");
+
+    const result = await tagFlow(tagClient, noteId);
+
+    expect(result.tagsOfNote).toEqual([result.tagId]);
+    expect(result.notesWithTag).toEqual([noteId]);
+    // tagFlow detaches at the end → the note carries no tags afterwards.
+    expect(await tagIdsOfNote(noteId)).toEqual([]);
+  });
+
+  test("a note carries a tag without any tag-column on the note", async () => {
+    const noteId = "11111111-1111-4000-8000-000000000001";
+    await createNote(noteId, "Quarterly review");
+    const tagId = await createTag("important");
+
+    await assignTag(tagId, noteId);
+
+    expect(await tagIdsOfNote(noteId)).toEqual([tagId]);
+
+    // The note row itself stays a plain { id, title } — no tag leakage.
+    const notes = await stack.http.queryOk<{ rows: Array<Record<string, unknown>> }>(
+      "note-management:query:note:list",
+      {},
+      admin,
+    );
+    const note = notes.rows.find((r) => r["id"] === noteId);
+    expect(note?.["title"]).toBe("Quarterly review");
+    expect(note).not.toHaveProperty("tagId");
+  });
+
+  test("one tag spans multiple notes (entities-with-tag direction)", async () => {
+    await createNote("22222222-2222-4000-8000-000000000002", "Note A");
+    await createNote("33333333-3333-4000-8000-000000000003", "Note B");
+    const tagId = await createTag("project-x");
+
+    await assignTag(tagId, "22222222-2222-4000-8000-000000000002");
+    await assignTag(tagId, "33333333-3333-4000-8000-000000000003");
+
+    const res = await stack.http.queryOk<{ rows: Array<{ entityId: string }> }>(
+      "tags:query:tag-assignment:list",
+      { filter: { field: "tagId", op: "eq", value: tagId } },
+      admin,
+    );
+    expect(res.rows.map((r) => r.entityId).sort()).toEqual([
+      "22222222-2222-4000-8000-000000000002",
+      "33333333-3333-4000-8000-000000000003",
+    ]);
+  });
+
+  test("removing the tag detaches it from the note", async () => {
+    const noteId = "44444444-4444-4000-8000-000000000004";
+    await createNote(noteId, "Temp");
+    const tagId = await createTag("temp-tag");
+    await assignTag(tagId, noteId);
+    expect(await tagIdsOfNote(noteId)).toEqual([tagId]);
+
+    await stack.http.writeOk(
+      "tags:write:remove-tag",
+      { tagId, entityType: "note", entityId: noteId },
+      admin,
+    );
+    expect(await tagIdsOfNote(noteId)).toEqual([]);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// kumiko-feature-version: 1
+// Tags Basic Sample
+//
+// Shows the whole point of the `tags` bundle: tagging an entity needs ZERO
+// changes to that entity. The `note` entity below has no tag column, no
+// `wireTagsFor`, no awareness of tags at all — yet notes can be tagged and
+// grouped, because the tags feature owns its own tables (read_tags +
+// read_tag_assignments) and keys assignments by (entityType, entityId).
+//
+// Flow (see the integration test):
+//   1. App-author defines a plain `note` entity — nothing tag-specific.
+//   2. A tenant creates a tag via `tags:write:create-tag`.
+//   3. The tag is attached to a note via `tags:write:assign-tag`
+//      with { tagId, entityType: "note", entityId: <noteId> }.
+//   4. "Which tags does this note have?" / "Which notes carry this tag?"
+//      are read-layer compositions: list `tag-assignment` filtered by
+//      entityId or tagId — no JOIN, no column on `note`.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// --- Entity ---
+//
+// A plain entity. Note there is NOTHING here that mentions tags — that is the
+// feature's promise: any entity is taggable as-is.
+
+export const noteEntity = createEntity({
+  table: "read_sample_tags_notes",
+  fields: {
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 200,
+    }),
+  },
+});
+
+const noteTable = buildEntityTable("note", noteEntity);
+
+const noteExecutor = createEventStoreExecutor(noteTable, noteEntity, { entityName: "note" });
+
+// --- Feature ---
+
+export const noteFeature = defineFeature("note-management", (r) => {
+  // tags is non-optional for this recipe: the demo tags notes. The note
+  // feature itself stays completely tag-agnostic — it only declares the
+  // dependency so the bundle is mounted.
+  r.requires("tags");
+
+  r.entity("note", noteEntity);
+
+  r.writeHandler({
+    name: "note:create",
+    schema: z.object({ id: z.string(), title: z.string() }),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (event, ctx) =>
+      noteExecutor.create({ id: event.payload.id, title: event.payload.title }, event.user, ctx.db),
+  });
+
+  r.queryHandler({
+    name: "note:list",
+    schema: z.object({}),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (_query, ctx) => {
+      const rows = await ctx.db.selectMany(noteTable);
+      return { rows };
+    },
+  });
+});
+```
+
+### src/usage.ts
+
+```ts
+// Tags Basic — using the bundle.
+//
+// The tags feature is driven entirely by dispatching its handlers; nothing is
+// wired into the tagged entity. A host needs exactly two calls — write and
+// query — which any app dispatcher provides. This recipe's integration test
+// runs `tagFlow` below against the real dispatcher + DB.
+
+// The minimal surface the tag flow needs from a host dispatcher. An app's
+// client satisfies this; the integration test adapts the test stack to it.
+export type TagClient = {
+  write: <T>(type: string, payload: unknown) => Promise<T>;
+  query: <T>(type: string, payload: unknown) => Promise<T>;
+};
+
+// Create a tag, attach it to a note, read it from both directions, detach it.
+export async function tagFlow(client: TagClient, noteId: string) {
+  // 1. Create a tag in the tenant catalog → returns its id. A tag carries a
+  //    `color` (rendered as a colored chip by the web UI) and an optional
+  //    `scope`: empty = global (offer on every entity), or an entity type to
+  //    restrict it — here "note", so the picker only suggests it on notes.
+  const { id: tagId } = await client.write<{ id: string }>("tags:write:create-tag", {
+    name: "important",
+    color: "#2563eb",
+    scope: "note",
+  });
+
+  // 2. Attach it to ANY entity by (type, id) — no column on that entity
+  await client.write("tags:write:assign-tag", { tagId, entityType: "note", entityId: noteId });
+
+  // 3a. "Which tags does this note have?" — filter assignments by entityId
+  const ofNote = await client.query<{ rows: Array<{ tagId: string }> }>(
+    "tags:query:tag-assignment:list",
+    { filter: { field: "entityId", op: "eq", value: noteId } },
+  );
+
+  // 3b. "Which notes carry this tag?" — filter by tagId (no JOIN)
+  const withTag = await client.query<{ rows: Array<{ entityId: string }> }>(
+    "tags:query:tag-assignment:list",
+    { filter: { field: "tagId", op: "eq", value: tagId } },
+  );
+
+  // 4. Detach it (idempotent — removing a missing link still succeeds)
+  await client.write("tags:write:remove-tag", { tagId, entityType: "note", entityId: noteId });
+
+  return {
+    tagId,
+    tagsOfNote: ofNote.rows.map((r) => r.tagId),
+    notesWithTag: withTag.rows.map((r) => r.entityId),
+  };
+}
+```

package/agents/examples/tenant-isolation.md

@@ -0,0 +1,173 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/tenant-isolation. Do not edit. -->
+
+# tenant-isolation
+
+Multi-tenant separation. Your data stays your data.
+
+## README
+
+# Tenant Isolation
+
+Multi-tenant data isolation by default.
+
+## What it shows
+
+- Tenant filter on ordinary handlers
+- What breaks if you forget tenancy (and how the framework prevents it)
+
+## 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/tenant-isolation
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Tenant Isolation Sample — Integration Test
+// Proves: tenant_id scopes all data, cross-tenant access returns nothing
+
+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 { noteEntity, noteFeature } from "../feature";
+
+let stack: TestStack;
+
+const tenantAAdmin = TestUsers.admin;
+const tenantBAdmin = createTestUser({ id: 2, tenantId: "00000000-0000-4000-8000-000000000002" });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [noteFeature] });
+  await unsafeCreateEntityTable(stack.db, noteEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  stack.events.reset();
+});
+
+describe("tenant isolation", () => {
+  test("tenant A cannot see tenant B's data via detail", async () => {
+    const noteA = await stack.http.writeOk<SaveContext>(
+      "notes:write:note:create",
+      {
+        title: "Tenant A secret",
+        content: "Confidential",
+      },
+      tenantAAdmin,
+    );
+
+    // Tenant B tries to read Tenant A's note
+    const detail = await stack.http.queryOk<null>(
+      "notes:query:note:detail",
+      { id: noteA.id },
+      tenantBAdmin,
+    );
+
+    expect(detail).toBeNull();
+  });
+
+  test("tenant B cannot see tenant A's data in list", async () => {
+    await stack.http.writeOk<SaveContext>(
+      "notes:write:note:create",
+      {
+        title: "Only-For-A",
+      },
+      tenantAAdmin,
+    );
+
+    // Tenant B lists — should not see Tenant A's notes
+    const listB = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "notes:query:note:list",
+      {},
+      tenantBAdmin,
+    );
+
+    expect(listB.rows.some((r) => r["title"] === "Only-For-A")).toBe(false);
+  });
+
+  test("each tenant sees only their own data", async () => {
+    await stack.http.writeOk<SaveContext>(
+      "notes:write:note:create",
+      { title: "A-Note" },
+      tenantAAdmin,
+    );
+    await stack.http.writeOk<SaveContext>(
+      "notes:write:note:create",
+      { title: "B-Note" },
+      tenantBAdmin,
+    );
+
+    const listA = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "notes:query:note:list",
+      {},
+      tenantAAdmin,
+    );
+    const listB = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "notes:query:note:list",
+      {},
+      tenantBAdmin,
+    );
+
+    expect(listA.rows.some((r) => r["title"] === "A-Note")).toBe(true);
+    expect(listA.rows.some((r) => r["title"] === "B-Note")).toBe(false);
+
+    expect(listB.rows.some((r) => r["title"] === "B-Note")).toBe(true);
+    expect(listB.rows.some((r) => r["title"] === "A-Note")).toBe(false);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const noteEntity = createEntity({
+  table: "read_sample_notes",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    content: createTextField({ personal: false, reason: "is_business_data" }),
+  },
+});
+
+const adminWrite = { access: { roles: ["Admin"] } } as const;
+const openRead = {
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may list and view notes in their own tenant (tenant " +
+        "isolation, not per-user); writes are still gated by adminWrite",
+    },
+  },
+} as const;
+
+export const noteFeature = defineFeature("notes", (r) => {
+  r.crud("note", noteEntity, {
+    write: adminWrite,
+    read: openRead,
+    verbs: { update: false, delete: false, restore: false },
+  });
+});
+```