@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/relations.md

@@ -0,0 +1,280 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/relations. Do not edit. -->
+
+# relations
+
+belongsTo, hasMany, manyToMany — the good stuff.
+
+## README
+
+# Relations
+
+Parent-child relations with cascade / restrict.
+
+## What it shows
+
+- Relation declarations between entities
+- Delete behaviour (cascade vs restrict)
+
+## 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/relations
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Relations Sample — Integration Test
+// Proves: hasMany relations, cascade delete, restrict delete
+
+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 { createCascadeDeleteHook } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  memberEntity,
+  memberTable,
+  relationsFeature,
+  taskEntity,
+  taskTable,
+  teamEntity,
+} from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [relationsFeature] });
+  await unsafeCreateEntityTable(stack.db, teamEntity);
+  await unsafeCreateEntityTable(stack.db, memberEntity);
+  await unsafeCreateEntityTable(stack.db, taskEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  stack.events.reset();
+});
+
+describe("restrict: team cannot be deleted with members", () => {
+  test("delete team with members fails", async () => {
+    const team = await stack.http.writeOk<SaveContext>(
+      "org:write:team:create",
+      { name: "Engineering" },
+      admin,
+    );
+    await stack.http.writeOk<SaveContext>(
+      "org:write:member:create",
+      {
+        name: "Alice",
+        teamId: team.id,
+      },
+      admin,
+    );
+
+    // Cascade hook would block this — test via hook directly
+    const cascadeHook = createCascadeDeleteHook(stack.registry, new Map([["member", memberTable]]));
+
+    await expect(
+      cascadeHook.fn(
+        {
+          kind: "delete",
+          id: team.id,
+          data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+          entityName: "team",
+        },
+        { db: stack.db },
+      ),
+    ).rejects.toMatchObject({ code: "conflict", details: { reason: "delete_restricted" } });
+  });
+
+  test("delete empty team succeeds", async () => {
+    const team = await stack.http.writeOk<SaveContext>(
+      "org:write:team:create",
+      { name: "Empty Team" },
+      admin,
+    );
+
+    const cascadeHook = createCascadeDeleteHook(stack.registry, new Map([["member", memberTable]]));
+
+    await expect(
+      cascadeHook.fn(
+        {
+          kind: "delete",
+          id: team.id,
+          data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+          entityName: "team",
+        },
+        { db: stack.db },
+      ),
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe("cascade: deleting member removes tasks", () => {
+  test("member's tasks are deleted when member is deleted", async () => {
+    const team = await stack.http.writeOk<SaveContext>(
+      "org:write:team:create",
+      { name: "Cascade Team" },
+      admin,
+    );
+    const member = await stack.http.writeOk<SaveContext>(
+      "org:write:member:create",
+      {
+        name: "Bob",
+        teamId: team.id,
+      },
+      admin,
+    );
+
+    const task1 = await stack.http.writeOk<SaveContext>(
+      "org:write:task:create",
+      {
+        title: "Task A",
+        memberId: member.id,
+      },
+      admin,
+    );
+    const task2 = await stack.http.writeOk<SaveContext>(
+      "org:write:task:create",
+      {
+        title: "Task B",
+        memberId: member.id,
+      },
+      admin,
+    );
+
+    // Run cascade hook
+    const cascadeHook = createCascadeDeleteHook(stack.registry, new Map([["task", taskTable]]));
+
+    await cascadeHook.fn(
+      {
+        kind: "delete",
+        id: member.id,
+        data: { tenantId: "00000000-0000-4000-8000-000000000001" },
+        entityName: "member",
+      },
+      { db: stack.db },
+    );
+
+    // Tasks should be gone
+    const detail1 = await stack.http.queryOk<null>(
+      "org:query:task:detail",
+      { id: task1.id },
+      admin,
+    );
+    const detail2 = await stack.http.queryOk<null>(
+      "org:query:task:detail",
+      { id: task2.id },
+      admin,
+    );
+    expect(detail1).toBeNull();
+    expect(detail2).toBeNull();
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const teamEntity = createEntity({
+  table: "read_sample_teams",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+  },
+});
+
+export const memberEntity = createEntity({
+  table: "read_sample_members",
+  fields: {
+    name: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    teamId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+    role: createTextField({ personal: false, reason: "is_business_data" }),
+  },
+});
+
+export const taskEntity = createEntity({
+  table: "read_sample_member_tasks",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    memberId: createTextField({ personal: "ref", required: true }),
+  },
+});
+
+export const teamTable = buildEntityTable("team", teamEntity);
+export const memberTable = buildEntityTable("member", memberEntity);
+export const taskTable = buildEntityTable("task", taskEntity);
+
+const adminWrite = { access: { roles: ["Admin"] } } as const;
+const openRead = {
+  access: {
+    openToAll: {
+      reason: "any signed-in user may read a task by id; writes are still gated by adminWrite",
+    },
+  },
+} as const;
+const createOnly = {
+  update: false,
+  delete: false,
+  restore: false,
+  list: false,
+  detail: false,
+} as const;
+
+export const relationsFeature = defineFeature("org", (r) => {
+  const team = r.entity("team", teamEntity);
+  const member = r.entity("member", memberEntity);
+
+  r.relation(team, "members", {
+    type: "hasMany",
+    target: "member",
+    foreignKey: "teamId",
+    onDelete: "restrict",
+  });
+
+  r.relation(member, "tasks", {
+    type: "hasMany",
+    target: "task",
+    foreignKey: "memberId",
+    onDelete: "cascade",
+  });
+
+  r.crud("team", teamEntity, {
+    write: adminWrite,
+    verbs: createOnly,
+    registerEntity: false,
+  });
+  r.crud("member", memberEntity, {
+    write: adminWrite,
+    verbs: createOnly,
+    registerEntity: false,
+  });
+  r.crud("task", taskEntity, {
+    write: adminWrite,
+    read: openRead,
+    verbs: { ...createOnly, detail: true },
+  });
+});
+```

package/agents/examples/screens-nav.md

@@ -0,0 +1,353 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/screens-nav. Do not edit. -->
+
+# screens-nav
+
+r.screen() + r.nav() — entityList/entityEdit/custom screens, cross-feature nav parents, FieldCondition<TData>, boot-validator behaviour.
+
+## README
+
+# Screens Nav
+
+Register screens and navigation.
+
+## What it shows
+
+- `r.screen` + `r.nav` with cross-feature parents
+- How the admin shell discovers the tree
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/screens-nav
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.test.ts
+
+```ts
+// Screens + Nav Showcase — Unit Test (no DB / HTTP needed).
+// Proves the Framework surface that M1's ui-core Phase 4 + Phase 5 consume:
+//   - registry exposes screens + navs with qualified ids
+//   - cross-feature nav parents resolve
+//   - convenience indexes (getScreensByEntity / getTopLevelNavs /
+//     getNavsByParent) enable zero-reverse-index tree walks
+//   - declarative FieldCondition ({ field, eq/ne } | boolean) lands on EditFieldSpec
+//   - normalizeEditField / normalizeListColumn collapse the string shorthand
+//   - validateBoot catches the common author mistakes (unknown field,
+//     custom screen without a renderer component)
+
+import { describe, expect, test } from "bun:test";
+import {
+  createRegistry,
+  defineFeature,
+  isFieldsEditSection,
+  normalizeEditField,
+  normalizeListColumn,
+  validateBoot as validateBootRaw,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { withBootValidatorFixture } from "@cosmicdrift/kumiko-framework/testing";
+import { bookEntity, createBookshopAdminFeature, createBookshopFeature } from "../feature";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+const bookshop = createBookshopFeature();
+const bookshopAdmin = createBookshopAdminFeature();
+const registry = createRegistry([bookshop, bookshopAdmin]);
+
+describe("screens-nav showcase — registry state", () => {
+  test("validateBoot accepts the full registered app", () => {
+    expect(() => validateBoot([bookshop, bookshopAdmin])).not.toThrow();
+  });
+
+  test("raw validateBoot (no fixture) still enforces entityList sortable/defaultSort/i18n rules", () => {
+    expect(() => validateBootRaw([bookshop, bookshopAdmin])).toThrow(/i18n|sortable|defaultSort/);
+  });
+
+  test("all three screen variants registered with qualified ids", () => {
+    expect(registry.getScreen("bookshop:screen:book-list")?.id).toBe("bookshop:screen:book-list");
+    expect(registry.getScreen("bookshop:screen:book-edit")?.id).toBe("bookshop:screen:book-edit");
+    expect(registry.getScreen("bookshop-admin:screen:audit-log")?.id).toBe(
+      "bookshop-admin:screen:audit-log",
+    );
+  });
+
+  test("getScreensByEntity indexes entityList + entityEdit, excludes custom", () => {
+    const byBook = registry.getScreensByEntity("book");
+    expect(byBook.map((s) => s.id).sort()).toEqual([
+      "bookshop:screen:book-edit",
+      "bookshop:screen:book-list",
+    ]);
+    // Custom screens (no entity) are never indexed here.
+    for (const s of byBook) expect(s.type).not.toBe("custom");
+  });
+});
+
+describe("screens-nav showcase — nav tree", () => {
+  test("getTopLevelNavs returns only parent-less entries, qualified id", () => {
+    const tops = registry.getTopLevelNavs();
+    expect(tops.map((n) => n.id)).toEqual(["bookshop:nav:main"]);
+  });
+
+  test("cross-feature nav parent: bookshop-admin hangs under bookshop:nav:main", () => {
+    const children = registry.getNavsByParent("bookshop:nav:main");
+    // Two direct children — one from bookshop, one from bookshop-admin.
+    // The registry preserves registration order (bookshop first, admin
+    // second), so that's how they come back; the renderer sorts by `order`
+    // at tree-assembly time.
+    expect(children.map((n) => n.id)).toEqual(["bookshop:nav:books", "bookshop-admin:nav:audit"]);
+  });
+
+  test("nav entries preserve screen/access/icon/order from the declaration", () => {
+    const books = registry.getNav("bookshop:nav:books");
+    expect(books).toMatchObject({
+      label: "bookshop:nav.books",
+      parent: "bookshop:nav:main",
+      screen: "bookshop:screen:book-list",
+      order: 10,
+    });
+    const audit = registry.getNav("bookshop-admin:nav:audit");
+    expect(audit?.access).toEqual({ roles: ["Admin"] });
+  });
+
+  test("feature.navs (unregistered) keeps the short id side-by-side with the qualified registry-side", () => {
+    // Same NavDefinition — different perspective. feature-author-side uses
+    // short ids (stable across feature-renames via auto-prefix), the
+    // registry mutates `id` to qualified for downstream consumers.
+    expect(bookshop.navs["main"]?.id).toBe("main");
+    expect(registry.getNav("bookshop:nav:main")?.id).toBe("bookshop:nav:main");
+  });
+});
+
+describe("screens-nav showcase — field specs", () => {
+  test("normalizeEditField collapses string shorthand into the object form", () => {
+    // String form: just a field reference — downstream consumers treat
+    // it the same as the full object with no overrides.
+    expect(normalizeEditField("title")).toEqual({ field: "title" });
+    // Object form is returned verbatim.
+    const condition = { field: "published", eq: true } as const;
+    expect(normalizeEditField({ field: "price", readOnly: condition, span: 1 })).toEqual({
+      field: "price",
+      readOnly: condition,
+      span: 1,
+    });
+  });
+
+  test("normalizeListColumn collapses string columns too", () => {
+    expect(normalizeListColumn("author")).toEqual({ field: "author" });
+    const renderer = { format: "currency", symbol: "€" } as const;
+    expect(normalizeListColumn({ field: "price", renderer })).toEqual({
+      field: "price",
+      renderer,
+    });
+  });
+
+  test("declarative FieldCondition survives registry storage intact", () => {
+    const screen = registry.getScreen("bookshop:screen:book-edit");
+    if (screen?.type !== "entityEdit") throw new Error("expected entityEdit");
+    const basicsSection = screen.layout.sections[0];
+    const publishingSection = screen.layout.sections[1];
+    if (!basicsSection || !isFieldsEditSection(basicsSection)) {
+      throw new Error("expected fields section");
+    }
+    if (!publishingSection || !isFieldsEditSection(publishingSection)) {
+      throw new Error("expected fields section");
+    }
+    const priceField = normalizeEditField(publishingSection.fields[0]!);
+    expect(priceField.readOnly).toEqual({ field: "published", eq: true });
+    const authorField = normalizeEditField(basicsSection.fields[1]!);
+    expect(authorField.visible).toEqual({ field: "published", eq: false });
+  });
+});
+
+describe("screens-nav showcase — boot-validator catches author mistakes", () => {
+  test("unknown field in entityEdit section fails boot with a useful message", () => {
+    // Typo-protection: field refs must exist on the entity. Mis-spelled
+    // column names would otherwise silently vanish from the form.
+    const broken = defineFeature("broken-shop", (r) => {
+      r.entity("book", bookEntity);
+      r.screen({
+        id: "book-edit",
+        type: "entityEdit",
+        entity: "book",
+        layout: {
+          sections: [
+            { title: "s", fields: ["title", "tittle"] }, // typo
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([broken])).toThrow(/field "tittle"/);
+  });
+
+  test("custom screen needs at least one platform renderer", () => {
+    // A custom screen with an empty renderer object is structurally empty
+    // — ui-core would have nothing to mount. Caught at boot.
+    const broken = defineFeature("empty-custom", (r) => {
+      r.screen({ id: "blank", type: "custom", renderer: {} });
+    });
+    expect(() => validateBoot([broken])).toThrow(/react nor a native component/);
+  });
+
+  test("nav with dangling screen ref fails boot", () => {
+    const broken = defineFeature("ghost-ref", (r) => {
+      r.nav({ id: "lost", label: "x", screen: "does-not:screen:exist" });
+    });
+    expect(() => validateBoot([broken])).toThrow(/references screen "does-not:screen:exist"/);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Screens + Nav Showcase — two features prove:
+//   1. All three screen variants (entityList, entityEdit, custom) register
+//      through r.screen()
+//   2. Field-level conditionals (visible/readOnly/required) use declarative
+//      FieldCondition ({ field, eq/ne } | boolean) — JSON-safe for schema
+//      injection and ui-core evaluation at render time
+//   3. Level-4 slots + Level-2 renderers are plain-data shapes — engine
+//      stores them verbatim, ui-core resolves at mount-time
+//   4. r.nav() flattens into a registry-wide tree whose parent refs can
+//      cross feature boundaries (bookshop-admin hangs a nav under
+//      bookshop's main group — no import, no coupling)
+//
+// The rendering is ui-core's job (M1 Phase 4/5); this sample focuses on
+// the Framework surface — registration + boot-validation + registry
+// lookups the renderer will consume.
+
+import {
+  createBooleanField,
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const bookEntity = createEntity({
+  table: "read_books",
+  fields: {
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 200,
+    }),
+    author: createTextField({
+      personal: { of: "id" },
+      find: "none",
+      required: true,
+      maxLength: 100,
+    }),
+    price: createNumberField({ required: true }),
+    published: createBooleanField({ default: false }),
+  },
+});
+
+export function createBookshopFeature(): FeatureDefinition {
+  return defineFeature("bookshop", (r) => {
+    r.systemScope();
+    r.entity("book", bookEntity);
+
+    // entityList — columns carry string shorthand and the object form
+    // side by side; the framework normalizes both through
+    // normalizeListColumn() at ui-core's iteration time.
+    r.screen({
+      id: "book-list",
+      type: "entityList",
+      entity: "book",
+      columns: [
+        "title",
+        "author",
+        {
+          field: "price",
+          renderer: { format: "currency", symbol: "€" },
+        },
+        "published",
+      ],
+    });
+
+    // entityEdit — sections + spans + declarative conditionals + slots.
+    r.screen({
+      id: "book-edit",
+      type: "entityEdit",
+      entity: "book",
+      layout: {
+        sections: [
+          {
+            title: "bookshop:section.basics",
+            columns: 2,
+            // Demonstrates the declarative FieldCondition MECHANIC (data-gate
+            // on another field) — role-gates are not expressible here; use
+            // field-level access on the entity for those.
+            fields: ["title", { field: "author", visible: { field: "published", eq: false } }],
+          },
+          {
+            title: "bookshop:section.publishing",
+            columns: 2,
+            fields: [
+              {
+                field: "price",
+                readOnly: { field: "published", eq: true },
+                span: 1,
+              },
+              { field: "published", span: 1 },
+            ],
+          },
+        ],
+      },
+      slots: {
+        afterForm: { react: { __component: "BookHistorySidebar" } },
+      },
+      access: { roles: ["Admin", "Editor"] },
+    });
+
+    r.nav({
+      id: "main",
+      label: "bookshop:nav.main",
+      icon: "book-open",
+      order: 10,
+    });
+    r.nav({
+      id: "books",
+      label: "bookshop:nav.books",
+      icon: "list",
+      parent: "bookshop:nav:main",
+      screen: "bookshop:screen:book-list",
+      order: 10,
+    });
+  });
+}
+
+export function createBookshopAdminFeature(): FeatureDefinition {
+  return defineFeature("bookshop-admin", (r) => {
+    r.systemScope();
+
+    r.screen({
+      id: "audit-log",
+      type: "custom",
+      renderer: { react: { __component: "AuditLogScreen" } },
+      access: { roles: ["Admin"] },
+    });
+
+    r.nav({
+      id: "audit",
+      label: "bookshop-admin:nav.audit",
+      icon: "shield",
+      parent: "bookshop:nav:main",
+      screen: "bookshop-admin:screen:audit-log",
+      access: { roles: ["Admin"] },
+      order: 20,
+    });
+  });
+}
+```