@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/basic-entity.md

@@ -0,0 +1,420 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/basic-entity. Do not edit. -->
+
+# basic-entity
+
+The simplest possible CRUD demo. About six lines of actual code.
+
+## README
+
+# Basic entity
+
+Wire one event-sourced aggregate end-to-end with the framework's built-in CRUD
+helpers. The recipe ships a `task` entity with the standard verbs — create,
+update, delete, restore, list, detail — via `r.crud`, plus
+soft-delete enabled.
+
+This is the smallest useful sample: it demonstrates the path from
+`createEntity({ fields })` to a working API surface without writing any Zod
+schemas or handler bodies by hand.
+
+## What it shows
+
+- **`createEntity` with field factories** — typed text, boolean, number
+  fields with options like `required`, `sortable`, `softDelete`.
+- **`r.crud`** — entity + standard handlers in one call; skip
+  verbs in `verbs` and register explicitly when access differs per verb.
+- **Per-verb access rules** — different roles can create vs. update vs.
+  delete. Editor and User roles can write; only Admin can delete or restore.
+- **Soft delete** — `softDelete: true` on the entity gives the executor an
+  `isDeleted` column and the `delete` handler flips it instead of dropping
+  the row. `restore` flips it back.
+
+## Feature composition
+
+```
+task-management → single feature, single `task` entity, six CRUD handlers
+```
+
+No bundled features required — this is the baseline before you add
+`r.requires("tenant")`, auth, or cross-feature extensions.
+
+## Flow
+
+1. Define fields with `createEntity({ fields: { … } })`.
+2. Call `r.crud("task", taskEntity, { write, read, verbs })`.
+3. Client calls `task-management:write:task:create` → row + event appended.
+4. `delete` soft-flips `isDeleted`; `restore` flips back; `list` excludes
+   deleted rows by default.
+
+## When to reach for it
+
+You're starting a new feature with a single entity and want CRUD without
+inventing your own handlers. Replace any single line with an explicit
+`r.writeHandler({ name, schema, handler })` when you outgrow the defaults
+— see [custom-handlers](/en/samples/recipes-custom-handlers/) for that path.
+
+## Tests
+
+```bash
+bun kumiko test integration samples/basic-entity
+```
+
+Integration tests under `src/__tests__/` exercise list-with-sort,
+soft-delete + restore, and per-verb access boundaries (Editor vs Admin).
+
+## Related samples
+
+- [custom-handlers](/en/samples/recipes-custom-handlers/) — replace generated
+  CRUD helpers with explicit handlers.
+- [field-access](/en/samples/recipes-field-access/) — per-field read/write
+  rules on top of the same entity pattern.
+- [custom-fields-basic](/en/samples/recipes-custom-fields-basic/) — tenant-
+  defined extra columns without migrations.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Basic CRUD Sample — Integration Test
+// Proves: create, read, update, delete, soft delete, optimistic locking, sort
+
+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 { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { taskEntity, taskFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+const user = createTestUser({ id: 2, roles: ["User"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [taskFeature] });
+  await unsafeCreateEntityTable(stack.db, taskEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  stack.events.reset();
+});
+
+// --- Create + Read ---
+
+describe("create and read", () => {
+  test("create returns SaveContext with isNew=true", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "Buy milk",
+        description: "From the store",
+      },
+      admin,
+    );
+
+    expect(data.isNew).toBe(true);
+    expect(data.id).toBeDefined();
+    expect(data.data["title"]).toBe("Buy milk");
+    expect(data.data["version"]).toBe(1);
+  });
+
+  test("detail returns created record", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "Read me back",
+      },
+      admin,
+    );
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "tasks:query:task:detail",
+      { id: created.id },
+      admin,
+    );
+
+    expect(detail["title"]).toBe("Read me back");
+    expect(detail["version"]).toBe(1);
+  });
+
+  test("boolean default applied", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "Defaults test",
+      },
+      admin,
+    );
+
+    expect(created.data["isArchived"]).toBe(false);
+  });
+});
+
+// --- Update ---
+
+describe("update", () => {
+  test("update returns changes and previous", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "Before",
+        status: "todo",
+      },
+      admin,
+    );
+
+    const updated = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:update",
+      {
+        id: created.id,
+        changes: { title: "After" },
+        version: 1,
+      },
+      user,
+    );
+
+    expect(updated.isNew).toBe(false);
+    expect(updated.changes).toEqual({ title: "After" });
+    expect(updated.previous["title"]).toBe("Before");
+    expect(updated.data["title"]).toBe("After");
+    expect(updated.data["status"]).toBe("todo"); // unchanged field preserved
+  });
+
+  test("version increments on update", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "Versioned",
+      },
+      admin,
+    );
+
+    const updated = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:update",
+      {
+        id: created.id,
+        changes: { title: "V2" },
+        version: 1,
+      },
+      admin,
+    );
+
+    expect(updated.data["version"]).toBe(2);
+  });
+});
+
+// --- Optimistic Locking ---
+
+describe("optimistic locking", () => {
+  test("stale version causes version_conflict", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "Lock me",
+      },
+      admin,
+    );
+
+    // First update succeeds
+    await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:update",
+      {
+        id: created.id,
+        version: 1,
+        changes: { title: "V2" },
+      },
+      admin,
+    );
+
+    // Second update with stale version=1 fails
+    const error = await stack.http.writeErr(
+      "tasks:write:task:update",
+      {
+        id: created.id,
+        version: 1,
+        changes: { title: "Stale" },
+      },
+      admin,
+    );
+
+    expectErrorIncludes(error, "version_conflict");
+  });
+});
+
+// --- Soft Delete ---
+
+describe("soft delete", () => {
+  test("deleted record disappears from detail", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "Delete me",
+      },
+      admin,
+    );
+
+    await stack.http.writeOk<SaveContext>("tasks:write:task:delete", { id: created.id }, admin);
+
+    const detail = await stack.http.queryOk<null>(
+      "tasks:query:task:detail",
+      { id: created.id },
+      admin,
+    );
+    expect(detail).toBeNull();
+  });
+
+  test("deleted record disappears from list", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "Unique-Del-List-Check",
+      },
+      admin,
+    );
+
+    await stack.http.writeOk<SaveContext>("tasks:write:task:delete", { id: created.id }, admin);
+
+    const list = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "tasks:query:task:list",
+      {},
+      admin,
+    );
+    expect(list.rows.some((r) => r["title"] === "Unique-Del-List-Check")).toBe(false);
+  });
+});
+
+// --- List + Sort ---
+
+describe("list and sort", () => {
+  test("list returns rows", async () => {
+    await stack.http.writeOk<SaveContext>("tasks:write:task:create", { title: "List-A" }, admin);
+    await stack.http.writeOk<SaveContext>("tasks:write:task:create", { title: "List-B" }, admin);
+
+    const list = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "tasks:query:task:list",
+      {},
+      admin,
+    );
+    expect(list.rows.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("sort by status ASC", async () => {
+    await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      { title: "Sort-Z", status: "z-last" },
+      admin,
+    );
+    await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      { title: "Sort-A", status: "a-first" },
+      admin,
+    );
+
+    const list = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "tasks:query:task:list",
+      { sort: "status", sortDirection: "asc" },
+      admin,
+    );
+
+    const statuses = list.rows.map((r) => r["status"]).filter(Boolean) as string[];
+    const sorted = [...statuses].sort();
+    expect(statuses).toEqual(sorted);
+  });
+});
+
+// --- Access Control ---
+
+describe("access control", () => {
+  test("User role can create", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "User task",
+      },
+      user,
+    );
+    expect(data.isNew).toBe(true);
+  });
+
+  test("User role cannot delete (Admin only)", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "tasks:write:task:create",
+      {
+        title: "Protected",
+      },
+      admin,
+    );
+
+    const error = await stack.http.writeErr(
+      "tasks:write:task:delete",
+      {
+        id: created.id,
+      },
+      user,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Basic Entity Sample
+// Shows: how to wire one event-sourced aggregate end-to-end via r.crud.
+// Custom logic or per-verb access? Skip a verb in `verbs` and register explicitly.
+
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+  defineEntityDeleteHandler,
+  defineEntityRestoreHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const taskEntity = createEntity({
+  table: "read_sample_tasks",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    description: createTextField({ personal: false, reason: "is_business_data" }),
+    // sortable: true so the integration test can exercise list-with-sort.
+    status: createTextField({ personal: false, reason: "is_business_data", sortable: true }),
+    isArchived: createBooleanField({ default: false }),
+  },
+  softDelete: true,
+});
+
+const editorWrite = { access: { roles: ["Admin", "User"] } } as const;
+const adminWrite = { access: { roles: ["Admin"] } } as const;
+const openRead = {
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may list and view tasks; writes are still gated by the roles below",
+    },
+  },
+} as const;
+
+export const taskFeature = defineFeature("tasks", (r) => {
+  r.crud("task", taskEntity, {
+    write: editorWrite,
+    read: openRead,
+    verbs: { delete: false, restore: false },
+  });
+  r.writeHandler(defineEntityDeleteHandler("task", taskEntity, adminWrite));
+  r.writeHandler(defineEntityRestoreHandler("task", taskEntity, adminWrite));
+});
+```

package/agents/examples/boot-check.md

@@ -0,0 +1,122 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/boot-check. Do not edit. -->
+
+# boot-check
+
+A feature declares its own mount-invariant via r.bootCheck.
+
+## README
+
+# Boot check
+
+Declare a feature's own mount-invariant with `r.bootCheck(...)` instead of
+relying on framework-internal knowledge. The recipe reproduces the
+prompt-store integration trap: a feature ships PII-annotated
+fields but the companion feature that's supposed to govern user data was
+never mounted, and nothing caught it — until now.
+
+## What it shows
+
+- **`r.bootCheck(fn)`** — a check function that runs once at boot with a
+  ctx exposing every mounted feature. Throw to fail the boot with a clear,
+  feature-prefixed message.
+- **Conditional invariants `r.requires` can't express** — the check only
+  fails when *this* feature's own shape demands it (has a PII field), not
+  unconditionally. A plain `r.requires("user-data-hook")` would fail even
+  for a prompt-store variant with no PII fields at all.
+- **`validateBoot`** — the framework's boot-time validator, run directly
+  against a feature list. `bootCheck` has no DB dependency, so this is the
+  cheapest way to exercise it — no `setupTestStack` needed.
+
+## Feature composition
+
+```
+prompt-store   → entity with a PII field, declares the bootCheck
+user-data-hook → companion feature the check requires when PII is present
+```
+
+## Flow
+
+1. `prompt-store` defines an entity with a `pii: true` field.
+2. It registers `r.bootCheck(({ features }) => { ... })`, closing over its
+   own field definitions to decide whether the invariant applies.
+3. At boot, `validateBoot` runs every registered check. If `prompt-store` is
+   mounted without `user-data-hook`, the check throws and boot fails with
+   `[Feature prompt-store] r.bootCheck failed: ...`.
+4. Mount `user-data-hook` alongside it, and the same check passes.
+
+## When to reach for it
+
+You're writing a feature whose validity depends on *another* feature being
+mounted, but only under a condition your feature alone can evaluate (e.g.
+"only if I have PII fields", "only if I expose more than N screens"). If the
+requirement is unconditional, `r.requires`/`r.optionalRequires` is simpler
+and already covered by the boot validator.
+
+## Tests
+
+```bash
+bun test samples/recipes/boot-check/src/__tests__/feature.test.ts
+```
+
+Two cases: companion mounted → boot succeeds; companion missing → boot
+fails with the feature-prefixed message.
+
+## Source files
+
+### src/__tests__/feature.test.ts
+
+```ts
+// Boot-Check Sample — Test
+// Proves: boot succeeds when the companion feature is mounted, fails with a
+// clear, feature-prefixed message when it's missing.
+
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { promptStoreFeature, userDataHookFeature } from "../feature";
+
+describe("prompt-store bootCheck", () => {
+  test("companion mounted → boot succeeds", () => {
+    expect(() => validateBoot([userDataHookFeature, promptStoreFeature])).not.toThrow();
+  });
+
+  test("companion missing → boot fails with feature-prefixed message", () => {
+    expect(() => validateBoot([promptStoreFeature])).toThrow(
+      "[Feature prompt-store] r.bootCheck failed: prompt-store has PII fields but no user-data-hook feature is mounted",
+    );
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Boot-Check Sample
+// Shows: how a feature declares its own mount-invariant via r.bootCheck,
+// for conditional cross-feature requirements r.requires can't express.
+
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+// A prompt-store integration trap: a feature with a PII field was mounted
+// without its required companion feature, and nothing caught it at boot.
+// r.requires("user-data-hook") can't express this — it would
+// fail even for a prompt-store variant with no PII fields at all.
+const promptFields = {
+  text: createTextField({
+    personal: "self",
+    find: "none",
+  }),
+};
+
+export const promptStoreFeature = defineFeature("prompt-store", (r) => {
+  r.entity("prompt", createEntity({ fields: promptFields }));
+  r.bootCheck(({ features }) => {
+    const hasPiiField = Object.values(promptFields).some((field) => field.pii);
+    const hasUserDataHook = features.some((f) => f.name === "user-data-hook");
+    if (hasPiiField && !hasUserDataHook) {
+      throw new Error("prompt-store has PII fields but no user-data-hook feature is mounted");
+    }
+  });
+});
+
+export const userDataHookFeature = defineFeature("user-data-hook", () => {});
+```