@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/README.md

@@ -45,7 +45,11 @@ export const taskFeature = defineFeature("tasks", (r) => {
   // control, all explicit via the options below.
   r.crud("task", taskEntity, {
     write: { access: { roles: ["User"] } },
-    read: { access: { openToAll: true } },
+    read: {
+      access: {
+        openToAll: { reason: "any signed-in user may list and view tasks; only writes are role-gated" },
+      },
+    },
   });
 
   // Read-model fed from task events, rebuildable via the CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.269.2",
+  "version": "0.273.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.269.2",
+    "@cosmicdrift/kumiko-types": "0.273.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.269.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.273.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/anonymous-access.integration.test.ts

@@ -66,7 +66,7 @@ const shopFeature = defineFeature("anonshop", (r) => {
       const rows = await selectMany(ctx.db, productTable);
       return rows;
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   // Anonymous can place a guest order.

package/src/__tests__/error-contract.integration.test.ts

@@ -149,7 +149,7 @@ const errorFeature = defineFeature("errctr", (r) => {
     async (event) => {
       throw new NotFoundError("item", event.payload.id);
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   // InternalError auto-wrap: handler raises an unexpected TypeError; the

package/src/__tests__/fixtures/migrate-cross-tenant/manual-only.expected.ts

@@ -0,0 +1,44 @@
+import {
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineEntityRestoreHandler,
+  registerEntityCrud,
+} from "../../../engine/entity-handlers";
+import { legacyReportEntity } from "./legacy-report.entity";
+import { widgetEntity } from "./widget.entity";
+
+const access = { roles: ["SystemAdmin"] };
+const someFlag = process.env.WIDGET_CROSS_TENANT === "true";
+
+const sysadminAccess = { access, crossTenant: true };
+
+export function registerWidget(r) {
+  r.writeHandler(defineEntityCreateHandler("widget", widgetEntity, { ...sysadminAccess }));
+
+  registerEntityCrud(r, "widget", widgetEntity, {
+    write: { access, crossTenant: true },
+    read: { access },
+  });
+
+  r.writeHandler(
+    defineEntityRestoreHandler("widget", widgetEntity, {
+      access,
+      crossTenant: true,
+      escapeHatch: { reason: "legacy grant, needs review" },
+    }),
+  );
+
+  r.queryHandler(
+    defineEntityListHandler("legacy-report", legacyReportEntity, {
+      access,
+      crossTenant: someFlag,
+    }),
+  );
+
+  r.queryHandler(
+    defineEntityListHandler("widget-summary", widgetEntity, {
+      access,
+      crossTenant: false,
+    }),
+  );
+}

package/src/__tests__/fixtures/migrate-cross-tenant/manual-only.input.ts

@@ -0,0 +1,44 @@
+import {
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineEntityRestoreHandler,
+  registerEntityCrud,
+} from "../../../engine/entity-handlers";
+import { legacyReportEntity } from "./legacy-report.entity";
+import { widgetEntity } from "./widget.entity";
+
+const access = { roles: ["SystemAdmin"] };
+const someFlag = process.env.WIDGET_CROSS_TENANT === "true";
+
+const sysadminAccess = { access, crossTenant: true };
+
+export function registerWidget(r) {
+  r.writeHandler(defineEntityCreateHandler("widget", widgetEntity, { ...sysadminAccess }));
+
+  registerEntityCrud(r, "widget", widgetEntity, {
+    write: { access, crossTenant: true },
+    read: { access },
+  });
+
+  r.writeHandler(
+    defineEntityRestoreHandler("widget", widgetEntity, {
+      access,
+      crossTenant: true,
+      escapeHatch: { reason: "legacy grant, needs review" },
+    }),
+  );
+
+  r.queryHandler(
+    defineEntityListHandler("legacy-report", legacyReportEntity, {
+      access,
+      crossTenant: someFlag,
+    }),
+  );
+
+  r.queryHandler(
+    defineEntityListHandler("widget-summary", widgetEntity, {
+      access,
+      crossTenant: false,
+    }),
+  );
+}

package/src/__tests__/fixtures/migrate-cross-tenant/rewrite.expected.ts

@@ -0,0 +1,41 @@
+import {
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineEntityWriteHandler,
+} from "../../../engine/entity-handlers";
+import { exportJobEntity } from "./export-job.entity";
+import { noteEntity } from "./note.entity";
+
+const access = { roles: ["SystemAdmin"] };
+
+export function registerExportJob(r) {
+  r.queryHandler(
+    defineEntityListHandler("export-job", exportJobEntity, {
+      access,
+      escapeHatch: { reason: "export-job:list reads export-job rows across every tenant (migrated from crossTenant: true; state the operator use case here)" },
+      description: "Lists export jobs across every tenant for operator support",
+    }),
+  );
+
+  r.writeHandler(
+    defineEntityUpdateHandler("export-job", exportJobEntity, {
+      access,
+      escapeHatch: { reason: "export-job:update writes export-job rows across every tenant (migrated from crossTenant: true; state the operator use case here)" },
+    }),
+  );
+
+  r.writeHandler(
+    defineEntityWriteHandler("note:delete", noteEntity, {
+      access,
+      escapeHatch: { reason: "note:delete writes note rows across every tenant (migrated from crossTenant: true; state the operator use case here)" },
+    }),
+  );
+
+  r.queryHandler(
+    defineEntityDetailHandler("export-job", exportJobEntity, {
+      access,
+      escapeHatch: { reason: "export-job:detail reads export-job rows across every tenant (migrated from crossTenant: true; state the operator use case here)" },
+    }),
+  );
+}

package/src/__tests__/fixtures/migrate-cross-tenant/rewrite.input.ts

@@ -0,0 +1,41 @@
+import {
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineEntityWriteHandler,
+} from "../../../engine/entity-handlers";
+import { exportJobEntity } from "./export-job.entity";
+import { noteEntity } from "./note.entity";
+
+const access = { roles: ["SystemAdmin"] };
+
+export function registerExportJob(r) {
+  r.queryHandler(
+    defineEntityListHandler("export-job", exportJobEntity, {
+      access,
+      crossTenant: true,
+      description: "Lists export jobs across every tenant for operator support",
+    }),
+  );
+
+  r.writeHandler(
+    defineEntityUpdateHandler("export-job", exportJobEntity, {
+      access,
+      crossTenant: true,
+    }),
+  );
+
+  r.writeHandler(
+    defineEntityWriteHandler("note:delete", noteEntity, {
+      access,
+      crossTenant: true,
+    }),
+  );
+
+  r.queryHandler(
+    defineEntityDetailHandler("export-job", exportJobEntity, {
+      access,
+      crossTenant: true,
+    }),
+  );
+}

package/src/__tests__/fixtures/migrate-open-to-all/manual-only.expected.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+export const listWidgets = {
+  name: "widget:list",
+  schema: z.object({}),
+  description: "Lists all widgets; visible to everyone",
+  access: { openToAll: true },
+  handler: async () => [],
+};
+
+export const legacyPing = {
+  name: "legacy:ping",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async () => "pong",
+};

package/src/__tests__/fixtures/migrate-open-to-all/manual-only.input.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+export const listWidgets = {
+  name: "widget:list",
+  schema: z.object({}),
+  description: "Lists all widgets; visible to everyone",
+  access: { openToAll: true },
+  handler: async () => [],
+};
+
+export const legacyPing = {
+  name: "legacy:ping",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async () => "pong",
+};

package/src/__tests__/fixtures/migrate-open-to-all/test-nested-shorthand.expected.ts

@@ -0,0 +1,12 @@
+export const config = {
+  verbAccess: {
+    create: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    list: { roles: ["admin"] },
+  },
+  read: {
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+  },
+  write: {
+    access: { roles: ["admin"] },
+  },
+};

package/src/__tests__/fixtures/migrate-open-to-all/test-nested-shorthand.input.ts

@@ -0,0 +1,12 @@
+export const config = {
+  verbAccess: {
+    create: { openToAll: true },
+    list: { roles: ["admin"] },
+  },
+  read: {
+    access: { openToAll: true },
+  },
+  write: {
+    access: { roles: ["admin"] },
+  },
+};

package/src/__tests__/fixtures/migrate-open-to-all/test-simple.expected.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+
+export const listHandler = {
+  name: "widget:list",
+  schema: z.object({}),
+  access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+};

package/src/__tests__/fixtures/migrate-open-to-all/test-simple.input.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+
+export const listHandler = {
+  name: "widget:list",
+  schema: z.object({}),
+  access: { openToAll: true },
+};

package/src/__tests__/full-stack.integration.test.ts

@@ -174,14 +174,14 @@ const userFeature = defineFeature("users", (r) => {
       sortDirection: z.enum(["asc", "desc"]).optional(),
     }),
     async (query, ctx) => userExecutor(ctx).list(query.payload, query.user, ctx.db),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.queryHandler(
     "user:detail",
     z.object({ id: z.uuid() }),
     async (query, ctx) => userExecutor(ctx).detail(query.payload, query.user, ctx.db),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.hook("postSave", { allOf: user }, async (result) => {

package/src/__tests__/migrate-cross-tenant-codemod.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { migrateCrossTenantSource } from "../scripts/codemod/migrate-cross-tenant";
+
+const FIXTURES_DIR = join(import.meta.dir, "fixtures", "migrate-cross-tenant");
+const PLACEHOLDER_PREFIXES = ["todo:", "fixme:", "tbd:"];
+
+function readFixture(name: string): { input: string; expected: string } {
+  return {
+    input: readFileSync(join(FIXTURES_DIR, `${name}.input.ts`), "utf8"),
+    expected: readFileSync(join(FIXTURES_DIR, `${name}.expected.ts`), "utf8"),
+  };
+}
+
+describe("migrateCrossTenantSource", () => {
+  it("rewrites crossTenant: true to escapeHatch: { reason } for every recognized entity-handler call shape", () => {
+    const { input, expected } = readFixture("rewrite");
+    const result = migrateCrossTenantSource(input, "export-job.handlers.ts");
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(4);
+    expect(result.manual).toHaveLength(0);
+
+    const byLine = new Map(result.rewrites.map((r) => [r.line, r]));
+
+    expect(byLine.get(16)?.after).toBe(
+      'escapeHatch: { reason: "export-job:list reads export-job rows across every tenant (migrated from crossTenant: true; state the operator use case here)" }',
+    );
+    expect(byLine.get(24)?.after).toBe(
+      'escapeHatch: { reason: "export-job:update writes export-job rows across every tenant (migrated from crossTenant: true; state the operator use case here)" }',
+    );
+    expect(byLine.get(31)?.after).toBe(
+      'escapeHatch: { reason: "note:delete writes note rows across every tenant (migrated from crossTenant: true; state the operator use case here)" }',
+    );
+    expect(byLine.get(38)?.after).toBe(
+      'escapeHatch: { reason: "export-job:detail reads export-job rows across every tenant (migrated from crossTenant: true; state the operator use case here)" }',
+    );
+  });
+
+  it("derives handlerName from the call for both the verb-in-name and verb-in-arg factory shapes", () => {
+    const { input } = readFixture("rewrite");
+    const result = migrateCrossTenantSource(input, "export-job.handlers.ts");
+
+    for (const rewrite of result.rewrites) {
+      expect(rewrite.after).toMatch(/^escapeHatch: \{ reason: "/);
+    }
+    expect(result.rewrites.map((r) => r.line)).toEqual([16, 24, 31, 38]);
+  });
+
+  it("leaves a spread/shared access object, a registerEntityCrud write/read block, an already-declared escapeHatch, and a non-literal crossTenant for manual review", () => {
+    const { input, expected } = readFixture("manual-only");
+    const result = migrateCrossTenantSource(input, "widget.handlers.ts");
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(0);
+    expect(result.manual).toHaveLength(4);
+
+    const byLine = new Map(result.manual.map((m) => [m.line, m]));
+
+    expect(byLine.get(13)?.why).toBe(
+      "crossTenant is not set directly in a handler call (e.g. a spread/shared object) — give each consuming handler its own escapeHatch reason",
+    );
+    expect(byLine.get(13)?.handlerName).toBeUndefined();
+
+    expect(byLine.get(19)?.why).toBe(
+      'under registerEntityCrud("widget", ...) → write: multiple verbs share this crossTenant — set escapeHatch per verb manually, one reason each',
+    );
+
+    expect(byLine.get(26)?.why).toBe(
+      "this object already declares escapeHatch — merge the two manually and remove crossTenant",
+    );
+    expect(byLine.get(26)?.handlerName).toBe("widget");
+
+    expect(byLine.get(34)?.why).toBe(
+      "crossTenant is not a literal boolean (`someFlag`) — replace manually with escapeHatch: { reason }",
+    );
+    expect(byLine.get(34)?.handlerName).toBe("legacy-report");
+  });
+
+  it("ignores crossTenant: false — no rewrite, no manual entry, output unchanged", () => {
+    const { input } = readFixture("manual-only");
+    const result = migrateCrossTenantSource(input, "widget.handlers.ts");
+
+    expect(input).toContain("crossTenant: false");
+    expect(result.manual.some((m) => m.line === 41)).toBe(false);
+    expect(result.rewrites.some((r) => r.line === 41)).toBe(false);
+    expect(result.output).toContain("crossTenant: false");
+  });
+
+  it("never generates a placeholder reason and never leaves a rewritten reason empty", () => {
+    const { input } = readFixture("rewrite");
+    const result = migrateCrossTenantSource(input, "export-job.handlers.ts");
+
+    for (const rewrite of result.rewrites) {
+      const match = rewrite.after.match(/reason: "([^"]*)"/);
+      expect(match).not.toBeNull();
+      const reason = match?.[1] ?? "";
+      expect(reason.length).toBeGreaterThan(0);
+      const lower = reason.toLowerCase();
+      for (const prefix of PLACEHOLDER_PREFIXES) {
+        expect(lower.startsWith(prefix)).toBe(false);
+      }
+    }
+  });
+});

package/src/__tests__/migrate-open-to-all-codemod.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { migrateOpenToAllSource } from "../scripts/codemod/migrate-open-to-all";
+
+const FIXTURES_DIR = join(import.meta.dir, "fixtures", "migrate-open-to-all");
+const DEFAULT_REASON = "test handler callable by any signed-in test user";
+
+function readFixture(name: string): { input: string; expected: string } {
+  return {
+    input: readFileSync(join(FIXTURES_DIR, `${name}.input.ts`), "utf8"),
+    expected: readFileSync(join(FIXTURES_DIR, `${name}.expected.ts`), "utf8"),
+  };
+}
+
+describe("migrateOpenToAllSource", () => {
+  it("rewrites a top-level openToAll: true in a *.test.ts file to the default test reason", () => {
+    const { input, expected } = readFixture("test-simple");
+    const result = migrateOpenToAllSource(input, "widget-list.test.ts", {
+      testReason: DEFAULT_REASON,
+    });
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(1);
+    expect(result.rewrites[0]?.after).toBe(`openToAll: { reason: "${DEFAULT_REASON}" }`);
+    expect(result.manual).toHaveLength(0);
+  });
+
+  it("rewrites openToAll: true under a __tests__/ path even without a .test.ts suffix", () => {
+    const { input, expected } = readFixture("test-simple");
+    const result = migrateOpenToAllSource(input, "packages/framework/__tests__/widget-list.ts", {
+      testReason: DEFAULT_REASON,
+    });
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(1);
+  });
+
+  it("honors a custom --test-reason for test files", () => {
+    const { input } = readFixture("test-simple");
+    const result = migrateOpenToAllSource(input, "widget-list.test.ts", {
+      testReason: "custom reason for this suite",
+    });
+
+    expect(result.output).toContain(
+      'access: { openToAll: { reason: "custom reason for this suite" } }',
+    );
+  });
+
+  it("rewrites nested shorthand openToAll: true (verbAccess, read.access) in test files", () => {
+    const { input, expected } = readFixture("test-nested-shorthand");
+    const result = migrateOpenToAllSource(input, "config.test.ts", { testReason: DEFAULT_REASON });
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(2);
+    expect(result.manual).toHaveLength(0);
+  });
+
+  it("leaves non-test files untouched and reports manual sites with derived handler name + description", () => {
+    const { input, expected } = readFixture("manual-only");
+    const result = migrateOpenToAllSource(input, "handlers.ts", { testReason: DEFAULT_REASON });
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(0);
+    expect(result.manual).toHaveLength(2);
+
+    const withDescription = result.manual.find((m) => m.handlerName === "widget:list");
+    expect(withDescription).toBeDefined();
+    expect(withDescription?.description).toBe("Lists all widgets; visible to everyone");
+    expect(withDescription?.line).toBe(7);
+
+    const withoutDescription = result.manual.find((m) => m.handlerName === "legacy:ping");
+    expect(withoutDescription).toBeDefined();
+    expect(withoutDescription?.description).toBeUndefined();
+    expect(withoutDescription?.line).toBe(14);
+  });
+
+  it("never rewrites in a non-test file, even when a description is present", () => {
+    const { input } = readFixture("manual-only");
+    const result = migrateOpenToAllSource(input, "handlers.ts", { testReason: DEFAULT_REASON });
+
+    expect(result.output).toContain("access: { openToAll: true }");
+  });
+});

package/src/__tests__/related-list-parent-filter.integration.test.ts

@@ -0,0 +1,103 @@
+// A relatedList section with `parentFilter` sends the parent id as
+// `payload.filter: { field, op: "eq", value: parentId }` instead of a
+// bespoke top-level key (related-list-section.tsx) — proving it against the
+// generic `<entity>:list` query end-to-end means proving `filter` and
+// `search` combine correctly in the real executor, over real HTTP, exactly
+// as the renderer's own request would look.
+//
+// Bun.SQL-only setup via setupTestStack.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineFeature,
+} from "../engine";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../stack";
+
+const itemEntity = createEntity({
+  table: "akte_items",
+  fields: {
+    name: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      required: true,
+      searchable: true,
+    }),
+    orderId: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+
+const ordersFeature = defineFeature("akteorders", (r) => {
+  r.entity("item", itemEntity);
+  r.writeHandler(defineEntityCreateHandler("item", itemEntity, { access: { roles: ["Admin"] } }));
+  r.queryHandler(defineEntityListHandler("item", itemEntity, { access: { roles: ["Admin"] } }));
+});
+
+describe("relatedList parentFilter against the generic <entity>:list query", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [ordersFeature] });
+    await unsafeCreateEntityTable(stack.db, itemEntity);
+
+    await stack.http.writeOk(
+      "akteorders:write:item:create",
+      { name: "Alice Corp", orderId: "order-1" },
+      TestUsers.admin,
+    );
+    await stack.http.writeOk(
+      "akteorders:write:item:create",
+      { name: "Bob LLC", orderId: "order-1" },
+      TestUsers.admin,
+    );
+    await stack.http.writeOk(
+      "akteorders:write:item:create",
+      { name: "Alice Two", orderId: "order-2" },
+      TestUsers.admin,
+    );
+    // Search indexing is async — drain the event dispatcher before any
+    // query below relies on `search` finding these rows.
+    await stack.eventDispatcher?.runOnce();
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("filter: eq on the parent id returns only that parent's rows", async () => {
+    const res = await stack.http.query(
+      "akteorders:query:item:list",
+      { filter: { field: "orderId", op: "eq", value: "order-1" } },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { rows: Array<Record<string, unknown>> } };
+    const names = body.data.rows.map((r) => r["name"]).sort();
+    expect(names).toEqual(["Alice Corp", "Bob LLC"]);
+  });
+
+  test("filter combined with search narrows within the parent's own rows only", async () => {
+    const res = await stack.http.query(
+      "akteorders:query:item:list",
+      { filter: { field: "orderId", op: "eq", value: "order-1" }, search: "alice" },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { rows: Array<Record<string, unknown>> } };
+    // "Alice Two" matches the search term but belongs to order-2 — the
+    // parent filter must exclude it even though search alone would find it.
+    expect(body.data.rows.map((r) => r["name"])).toEqual(["Alice Corp"]);
+  });
+
+  test("search alone (no filter) would find both Alice rows across parents — proves the filter is what narrows them", async () => {
+    const res = await stack.http.query(
+      "akteorders:query:item:list",
+      { search: "alice" },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { rows: Array<Record<string, unknown>> } };
+    expect(body.data.rows.map((r) => r["name"]).sort()).toEqual(["Alice Corp", "Alice Two"]);
+  });
+});