@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/feature-toggles.md

@@ -0,0 +1,263 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/feature-toggles. Do not edit. -->
+
+# feature-toggles
+
+Runtime feature-toggle flip — two toggleable features, one registers a cross-feature hook on the other; disabling either has the documented effect without reboot.
+
+## README
+
+# Feature Toggles
+
+Runtime global feature toggles without reboot.
+
+## What it shows
+
+- Dispatcher gate → `feature_disabled` when a feature is off
+- Cross-feature hooks skipped when a dependency toggle is off
+
+## 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/feature-toggles
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  createFeatureTogglesFeature,
+  GlobalFeatureToggleRuntime,
+  globalFeatureStateTable,
+} from "@cosmicdrift/kumiko-bundled-features/feature-toggles";
+import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createLateBoundHolder } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createProductAuditFeature,
+  createProductFeature,
+  productAuditEntity,
+  productAuditTable,
+  productEntity,
+  productTable,
+} from "../feature";
+
+let stack: TestStack;
+let runtime: GlobalFeatureToggleRuntime;
+
+beforeAll(async () => {
+  let effective: () => ReadonlySet<string> = () => new Set();
+  const runtimeHolder = createLateBoundHolder<GlobalFeatureToggleRuntime>("runtime");
+
+  stack = await setupTestStack({
+    features: [
+      createProductFeature(),
+      createProductAuditFeature(),
+      createFeatureTogglesFeature({ getRuntime: () => runtimeHolder.get() }),
+    ],
+    effectiveFeatures: () => effective(),
+    systemHooks: [],
+  });
+
+  await unsafePushTables(stack.db, { globalFeatureStateTable });
+  await unsafeCreateEntityTable(stack.db, productEntity);
+  await unsafeCreateEntityTable(stack.db, productAuditEntity, "product-audit");
+
+  runtime = new GlobalFeatureToggleRuntime(stack.db, stack.registry);
+  await runtime.initialize();
+  effective = runtime.effectiveFeatures;
+  runtimeHolder.set(runtime);
+});
+
+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"],
+});
+
+async function createProduct(name: string) {
+  return stack.http.write("product:write:product:create", { name }, admin);
+}
+
+describe("feature-toggles showcase", () => {
+  test("runtime flip: product on → create works + audit-hook fires; off → 403; on → works again", async () => {
+    // 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);
+
+    // OFF
+    runtime.apply("product", false);
+    const denied = await createProduct("beta");
+    const deniedBody = (await denied.json()) as {
+      isSuccess: boolean;
+      error?: { code: string };
+    };
+    expect(deniedBody.error?.code).toBe("feature_disabled");
+
+    // ON again
+    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);
+  });
+
+  test("cross-feature hook: disabling product-audit skips its hook but product keeps working", async () => {
+    runtime.apply("product-audit", false);
+
+    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);
+    // Audit hook owned by product-audit — silently skipped.
+    const auditRows = await selectMany(stack.db, productAuditTable);
+    expect(auditRows.length).toBe(0);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Feature-Toggles Showcase — two toggleable features that prove the two
+// operator-visible gate points in one test:
+//
+//   1. Dispatcher-gate on the owner feature's handler (403 feature_disabled)
+//   2. Hook-filter on a cross-feature r.hook({ allOf }) (skipped when hook-owner off)
+//
+// The feature-toggles bundled-feature itself is loaded in the integration
+// test so the canonical wiring (runtime accessor + effectiveFeatures
+// callback + set-handler) is exercised as documentation, not just in the
+// framework's own tests.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createBooleanField,
+  createEntity,
+  createSystemUser,
+  createTextField,
+  defineFeature,
+  type FeatureDefinition,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+// product — toggleable, default on. Owns the `product` entity and a
+// create-handler. Wire-path: event-store executor → projection table →
+// lifecycle pipeline (that's where the cross-feature hook below gets
+// invoked from).
+export const productEntity = createEntity({
+  table: "read_products",
+  fields: {
+    name: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 100,
+    }),
+    active: createBooleanField({ default: true }),
+  },
+});
+export const productTable = buildEntityTable("product", productEntity);
+const productCrud = createEventStoreExecutor(productTable, productEntity, {
+  entityName: "product",
+});
+
+export function createProductFeature(): FeatureDefinition {
+  return defineFeature("product", (r) => {
+    r.systemScope();
+    r.toggleable({ default: true });
+    r.entity("product", productEntity);
+    r.writeHandler(
+      "product:create",
+      z.object({ name: z.string().min(1).max(100) }),
+      async (event, ctx) => {
+        if (!ctx.systemDb) {
+          throw new InternalError({
+            message: "product:create requires ctx.systemDb — is r.systemScope() still set?",
+          });
+        }
+        const db = ctx.systemDb.acknowledgeCrossTenant(
+          "product catalog is system-wide, not tenant-scoped",
+        );
+        return productCrud.create(event.payload, event.user, db);
+      },
+      { access: { roles: ["SystemAdmin"] } },
+    );
+  });
+}
+
+// product-audit — toggleable, default on. Registers a cross-feature
+// r.hook({ allOf: "product" }) on product's postSave. When this feature is globally off,
+// the hook is silently skipped; product's own write-handler keeps working.
+// When product itself is off, the handler is gated before any write
+// happens — the hook never has anything to react to.
+export const productAuditEntity = createEntity({
+  table: "read_product_audits",
+  fields: {
+    productName: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 100,
+    }),
+  },
+});
+export const productAuditTable = buildEntityTable("product-audit", productAuditEntity);
+const productAuditCrud = createEventStoreExecutor(productAuditTable, productAuditEntity, {
+  entityName: "product-audit",
+});
+
+export function createProductAuditFeature(): FeatureDefinition {
+  return defineFeature("product-audit", (r) => {
+    r.systemScope();
+    r.toggleable({ default: true });
+    r.entity("product-audit", productAuditEntity);
+
+    r.hook("postSave", { allOf: "product" }, async (result, ctx) => {
+      if (result.kind !== "save" || !result.isNew) return;
+      if (!ctx.systemDb) return;
+      const name = (result.changes as Record<string, unknown>)["name"] as string | undefined;
+      if (!name) return;
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        "audit sink is system-wide, mirrors the system-wide product catalog",
+      );
+      // Cross-feature audit sink is itself an r.entity projection — write it via
+      // the executor (system actor, no human caller) so the row is event-backed
+      // and survives a rebuild, not a direct method-form insert.
+      await productAuditCrud.create({ productName: name }, createSystemUser(SYSTEM_TENANT_ID), db);
+    });
+  });
+}
+```

package/agents/examples/field-access.md

@@ -0,0 +1,271 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/field-access. Do not edit. -->
+
+# field-access
+
+Field-level access control. When entity-level roles aren't granular enough.
+
+## README
+
+# Field-level access
+
+Restrict individual fields by role — separate read and write rules per
+field, no `if` branches in the handler. This recipe ships an `employee`
+entity where `salary` is visible to Admin and Accounting (only Admin
+writes) and `internalNotes` is Admin-only on both sides.
+
+The framework strips fields the caller cannot read on the way out and
+rejects writes that touch fields the caller cannot write. Your handler
+never sees a forbidden field on input, never produces one on output.
+
+## What it shows
+
+- **`access: { read, write }` on a field factory** — two independent
+  rules per field, both expressed as role lists.
+- **Read-side filtering** — querying as `Employee` returns the row
+  without the `salary` and `internalNotes` keys; querying as
+  `Accounting` returns `salary` but not `internalNotes`.
+- **Write-side enforcement** — a write payload that includes
+  `internalNotes` from a non-Admin role fails with
+  `field_access_denied` and the offending field path.
+- **No handler-level branching** — the same `r.queryHandler` body
+  serves all three roles; the framework filters output per call.
+
+## Feature composition
+
+```
+hr → employee entity with field-level access on salary + internalNotes
+```
+
+Single feature, no bundled dependencies — field access is declared on
+the field factories inside `createEntity`.
+
+## Flow
+
+1. Admin creates an employee with all fields populated.
+2. Accounting reads detail → sees `salary`, not `internalNotes`.
+3. Employee reads detail → sees `name`/`email` only.
+4. Accounting tries to write `salary` → `field_access_denied` (read-only).
+5. Employee updates `name` → succeeds (unrestricted field).
+
+## When to reach for it
+
+Sensitive columns that a feature still needs to expose — phone numbers,
+salary figures, internal compliance notes. The whole row stays usable
+for everyone; specific fields disappear for callers without the
+right role.
+
+## 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
+bun kumiko test integration samples/field-access
+```
+
+Or from the recipe directory:
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Covers all three roles reading and writing, including the expected
+`field_access_denied` response shape.
+
+## Related samples
+
+- [basic-entity](/en/samples/recipes-basic-entity/) — start here if you
+  need standard CRUD before adding field rules.
+- [custom-handlers](/en/samples/recipes-custom-handlers/) — explicit
+  handlers when generated CRUD is not enough.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Field Access Sample — Integration Test
+// Proves: field-level read/write restrictions per role
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { EntityId, 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 { employeeEntity, employeeFeature } from "../feature";
+
+let stack: TestStack;
+
+const adminUser = TestUsers.admin;
+const accountingUser = createTestUser({ id: 2, roles: ["Accounting"] });
+const employeeUser = createTestUser({ id: 3, roles: ["Employee"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [employeeFeature] });
+  await unsafeCreateEntityTable(stack.db, employeeEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function seedEmployee(): Promise<EntityId> {
+  const data = await stack.http.writeOk<SaveContext>(
+    "hr:write:employee:create",
+    {
+      name: "Test Employee",
+      email: "test@company.de",
+      salary: 75000,
+      internalNotes: "Top performer",
+    },
+    adminUser,
+  );
+  return data.id;
+}
+
+describe("read access: field filtering per role", () => {
+  test("Admin sees all fields", async () => {
+    const id = await seedEmployee();
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "hr:query:employee:detail",
+      { id },
+      adminUser,
+    );
+
+    expect(detail["name"]).toBe("Test Employee");
+    expect(detail["salary"]).toBe(75000);
+    expect(detail["internalNotes"]).toBe("Top performer");
+  });
+
+  test("Accounting sees salary but not internalNotes", async () => {
+    const id = await seedEmployee();
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "hr:query:employee:detail",
+      { id },
+      accountingUser,
+    );
+
+    expect(detail["name"]).toBe("Test Employee");
+    expect(detail["salary"]).toBe(75000);
+    expect(detail["internalNotes"]).toBeUndefined();
+  });
+
+  test("Employee sees neither salary nor internalNotes", async () => {
+    const id = await seedEmployee();
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "hr:query:employee:detail",
+      { id },
+      employeeUser,
+    );
+
+    expect(detail["name"]).toBe("Test Employee");
+    expect(detail["salary"]).toBeUndefined();
+    expect(detail["internalNotes"]).toBeUndefined();
+  });
+});
+
+describe("write access: field-level write restrictions", () => {
+  test("Admin can write salary", async () => {
+    const id = await seedEmployee();
+    const updated = await stack.http.writeOk<SaveContext>(
+      "hr:write:employee:update",
+      {
+        id,
+        changes: { salary: 80000 },
+        version: 1,
+      },
+      adminUser,
+    );
+
+    expect(updated.data["salary"]).toBe(80000);
+  });
+
+  test("Accounting cannot write salary (read-only)", async () => {
+    const id = await seedEmployee();
+    const error = await stack.http.writeErr(
+      "hr:write:employee:update",
+      {
+        id,
+        changes: { salary: 99999 },
+        version: 1,
+      },
+      accountingUser,
+    );
+
+    expectErrorIncludes(error, "field_access_denied");
+  });
+
+  test("Employee cannot write salary", async () => {
+    const id = await seedEmployee();
+    const error = await stack.http.writeErr(
+      "hr:write:employee:update",
+      {
+        id,
+        changes: { salary: 1000000 },
+        version: 1,
+      },
+      employeeUser,
+    );
+
+    expectErrorIncludes(error, "field_access_denied");
+  });
+
+  test("Employee can write unrestricted fields", async () => {
+    const id = await seedEmployee();
+    const updated = await stack.http.writeOk<SaveContext>(
+      "hr:write:employee:update",
+      {
+        id,
+        changes: { name: "Updated Name" },
+        version: 1,
+      },
+      employeeUser,
+    );
+
+    expect(updated.data["name"]).toBe("Updated Name");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import {
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const employeeEntity = createEntity({
+  table: "read_sample_employees",
+  fields: {
+    name: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    email: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    salary: createNumberField({
+      access: { read: ["Admin", "Accounting"], write: ["Admin"] },
+    }),
+    internalNotes: createTextField({
+      personal: { of: "id" },
+      find: "none",
+      access: { read: ["Admin"], write: ["Admin"] },
+    }),
+  },
+});
+
+const allRoles = { access: { roles: ["Admin", "Accounting", "Employee"] } } as const;
+
+export const employeeFeature = defineFeature("hr", (r) => {
+  r.crud("employee", employeeEntity, {
+    write: allRoles,
+    read: allRoles,
+    verbs: { delete: false, list: false, restore: false },
+  });
+});
+```