@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/admin-shell/web/client-plugin.tsx

@@ -0,0 +1,26 @@
+// @runtime client
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import {
+  ADMIN_SHELL_FEATURE,
+  PLATFORM_OVERVIEW_SCREEN_ID,
+  TENANT_OVERVIEW_SCREEN_ID,
+} from "../constants";
+import { defaultTranslations } from "./i18n";
+import { PlatformOverviewScreen } from "./platform-overview-screen";
+import { TenantOverviewScreen } from "./tenant-overview-screen";
+
+export type AdminShellClientOptions = {
+  readonly translations?: TranslationsByLocale;
+};
+
+export function adminShellClient(options?: AdminShellClientOptions): ClientFeatureDefinition {
+  return {
+    name: ADMIN_SHELL_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+    components: {
+      [TENANT_OVERVIEW_SCREEN_ID]: TenantOverviewScreen,
+      [PLATFORM_OVERVIEW_SCREEN_ID]: PlatformOverviewScreen,
+    },
+  };
+}

package/src/admin-shell/web/i18n.ts

@@ -0,0 +1,16 @@
+// @runtime client
+// Client pivot of ADMIN_SHELL_I18N — same keys as server r.translations bundle.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import { ADMIN_SHELL_I18N } from "../i18n";
+
+const LOCALES = ["de", "en"] as const;
+
+export const defaultTranslations: TranslationsByLocale = Object.fromEntries(
+  LOCALES.map((locale) => [
+    locale,
+    Object.fromEntries(
+      Object.entries(ADMIN_SHELL_I18N).map(([key, value]) => [key, value[locale]]),
+    ),
+  ]),
+);

package/src/admin-shell/web/index.ts

@@ -0,0 +1,2 @@
+// @runtime client
+export { type AdminShellClientOptions, adminShellClient } from "./client-plugin";

package/src/admin-shell/web/overview-layout.tsx

@@ -0,0 +1,69 @@
+// @runtime client
+import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
+import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
+import type { ReactNode } from "react";
+
+export type OverviewCard = {
+  readonly label: string;
+  readonly value: string;
+  readonly hint?: string;
+  /** When true and hint is set, render an attention Banner inside the card. */
+  readonly attention?: boolean;
+};
+
+export type OverviewState =
+  | { readonly kind: "loading" }
+  | { readonly kind: "error"; readonly message: string }
+  | { readonly kind: "ready"; readonly cards: readonly OverviewCard[] };
+
+export function OverviewLayout({
+  testId,
+  title,
+  state,
+  loadingLabel,
+  columns = 3,
+}: {
+  readonly testId: string;
+  readonly title: string;
+  readonly state: OverviewState;
+  readonly loadingLabel: string;
+  readonly columns?: 2 | 3;
+}): ReactNode {
+  const { Banner, Card, Heading, Text } = usePrimitives();
+  const gridClass = columns === 2 ? "sm:grid-cols-2" : "sm:grid-cols-3";
+
+  return (
+    <FormScreenShell testId={testId} maxWidth="4xl" className="flex flex-col gap-6">
+      <Heading variant="page">{title}</Heading>
+
+      {state.kind === "loading" && (
+        <Text variant="small" testId={`${testId}-loading`}>
+          {loadingLabel}
+        </Text>
+      )}
+
+      {state.kind === "error" && (
+        <Banner variant="error" testId={`${testId}-error`}>
+          {state.message}
+        </Banner>
+      )}
+
+      {state.kind === "ready" && (
+        <div className={`grid grid-cols-1 gap-4 ${gridClass}`}>
+          {state.cards.map((card) => (
+            <Card key={card.label} testId={`${testId}-card`} slots={{ title: card.label }}>
+              <div className="flex flex-col gap-2" data-overview-card={card.label}>
+                <span className="text-3xl font-semibold tabular-nums">{card.value}</span>
+                {card.attention === true && card.hint !== undefined ? (
+                  <Banner variant="error">{card.hint}</Banner>
+                ) : (
+                  card.hint !== undefined && <Text variant="small">{card.hint}</Text>
+                )}
+              </div>
+            </Card>
+          ))}
+        </div>
+      )}
+    </FormScreenShell>
+  );
+}

package/src/admin-shell/web/overview-query.ts

@@ -0,0 +1,15 @@
+// @runtime client
+import type { Dispatcher, QueryResult } from "@cosmicdrift/kumiko-headless";
+import { isOverviewQueryAllowed, type OverviewWorkspaceKind } from "../overview-allowlist";
+
+export async function overviewQuery<T>(
+  kind: OverviewWorkspaceKind,
+  dispatcher: Dispatcher,
+  queryName: string,
+  payload: Record<string, unknown>,
+): Promise<QueryResult<T>> {
+  if (!isOverviewQueryAllowed(kind, queryName)) {
+    throw new Error(`admin-shell:overview query not allowlisted: ${queryName}`);
+  }
+  return dispatcher.query<T>(queryName, payload);
+}

package/src/admin-shell/web/platform-overview-screen.tsx

@@ -0,0 +1,90 @@
+// @runtime client
+
+import { useDispatcher, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useEffect, useState } from "react";
+import { JobQueries } from "../../jobs/constants";
+import { TenantQueries } from "../../tenant/constants";
+import { UserQueries } from "../../user/constants";
+import { OverviewLayout, type OverviewState } from "./overview-layout";
+import { overviewQuery } from "./overview-query";
+
+export function PlatformOverviewScreen(): ReactNode {
+  const t = useTranslation();
+  const dispatcher = useDispatcher();
+  const [state, setState] = useState<OverviewState>({ kind: "loading" });
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async (): Promise<void> => {
+      const tenantsRes = await overviewQuery<{ readonly total: number }>(
+        "platform",
+        dispatcher,
+        TenantQueries.list,
+        { totalCount: true },
+      );
+      if (cancelled) return;
+      if (!tenantsRes.isSuccess) {
+        setState({ kind: "error", message: tenantsRes.error.message });
+        return;
+      }
+
+      const usersRes = await overviewQuery<{ readonly total: number }>(
+        "platform",
+        dispatcher,
+        UserQueries.list,
+        { totalCount: true },
+      );
+      if (cancelled) return;
+      if (!usersRes.isSuccess) {
+        setState({ kind: "error", message: usersRes.error.message });
+        return;
+      }
+
+      const failedJobsRes = await overviewQuery<{ readonly total: number }>(
+        "platform",
+        dispatcher,
+        JobQueries.list,
+        { status: "failed", totalCount: true },
+      );
+      if (cancelled) return;
+      if (!failedJobsRes.isSuccess) {
+        setState({ kind: "error", message: failedJobsRes.error.message });
+        return;
+      }
+
+      setState({
+        kind: "ready",
+        cards: [
+          {
+            label: t("admin-shell:overview.tenants"),
+            value: String(tenantsRes.data.total),
+          },
+          {
+            label: t("admin-shell:overview.users"),
+            value: String(usersRes.data.total),
+          },
+          {
+            label: t("admin-shell:overview.failedJobs"),
+            value: String(failedJobsRes.data.total),
+            hint:
+              failedJobsRes.data.total > 0 ? t("admin-shell:overview.failedJobsHint") : undefined,
+            attention: failedJobsRes.data.total > 0,
+          },
+        ],
+      });
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [dispatcher, t]);
+
+  return (
+    <OverviewLayout
+      testId="platform-overview-screen"
+      title={t("admin-shell:overview.platformTitle")}
+      state={state}
+      loadingLabel={t("admin-shell:overview.loading")}
+      columns={3}
+    />
+  );
+}

package/src/admin-shell/web/tenant-overview-screen.tsx

@@ -0,0 +1,90 @@
+// @runtime client
+
+import { useDispatcher, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useEffect, useState } from "react";
+import { ConfigQueries } from "../../config/constants";
+import { TenantQueries } from "../../tenant/constants";
+import { OverviewLayout, type OverviewState } from "./overview-layout";
+import { overviewQuery } from "./overview-query";
+
+export function TenantOverviewScreen(): ReactNode {
+  const t = useTranslation();
+  const dispatcher = useDispatcher();
+  const [state, setState] = useState<OverviewState>({ kind: "loading" });
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async (): Promise<void> => {
+      const invitationsRes = await overviewQuery<readonly unknown[]>(
+        "tenant",
+        dispatcher,
+        TenantQueries.invitations,
+        {},
+      );
+      if (cancelled) return;
+      if (!invitationsRes.isSuccess) {
+        setState({ kind: "error", message: invitationsRes.error.message });
+        return;
+      }
+
+      const membersRes = await overviewQuery<readonly unknown[]>(
+        "tenant",
+        dispatcher,
+        TenantQueries.members,
+        {},
+      );
+      if (cancelled) return;
+      if (!membersRes.isSuccess) {
+        setState({ kind: "error", message: membersRes.error.message });
+        return;
+      }
+
+      const readinessRes = await overviewQuery<{ readonly missing: readonly unknown[] }>(
+        "tenant",
+        dispatcher,
+        ConfigQueries.readiness,
+        {},
+      );
+      if (cancelled) return;
+      if (!readinessRes.isSuccess) {
+        setState({ kind: "error", message: readinessRes.error.message });
+        return;
+      }
+
+      setState({
+        kind: "ready",
+        cards: [
+          {
+            label: t("admin-shell:overview.pendingInvitations"),
+            value: String(invitationsRes.data.length),
+          },
+          {
+            label: t("admin-shell:overview.members"),
+            value: String(membersRes.data.length),
+          },
+          {
+            label: t("admin-shell:overview.missingConfig"),
+            value: String(readinessRes.data.missing.length),
+            hint:
+              readinessRes.data.missing.length > 0
+                ? t("admin-shell:overview.missingConfigHint")
+                : undefined,
+            attention: readinessRes.data.missing.length > 0,
+          },
+        ],
+      });
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [dispatcher, t]);
+
+  return (
+    <OverviewLayout
+      testId="tenant-overview-screen"
+      title={t("admin-shell:overview.tenantTitle")}
+      state={state}
+      loadingLabel={t("admin-shell:overview.loading")}
+    />
+  );
+}

package/src/agent-tools/__tests__/tool-catalog.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createSelectField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  EntityDefinition,
+  QueryHandlerDef,
+  ReferenceFieldDef,
+} from "@cosmicdrift/kumiko-framework/engine/types";
+import { buildToolCatalog } from "../tool-catalog";
+import type { RegistrySearchView } from "../types";
+
+const vendorEntity = createEntity({
+  fields: {
+    name: createTextField({ searchable: true, filterable: true }),
+    iban: createTextField({ filterable: true }),
+    notes: createTextField(),
+    status: createSelectField({ options: ["active", "archived"] as const, filterable: true }),
+  },
+});
+
+const invoiceEntity = createEntity({
+  fields: {
+    vendorId: { type: "reference", entity: "vendor", filterable: true } satisfies ReferenceFieldDef,
+    description: createTextField({ searchable: true }),
+  },
+});
+
+const FAKE_HANDLER = {} as QueryHandlerDef;
+
+type EntityFixture = {
+  readonly qn: string;
+  readonly entityName: string;
+  readonly entity: EntityDefinition;
+  readonly searchableFields: readonly string[];
+};
+
+/** Handler-first fake: one entry per MOUNTED `:list` handler, mirroring what
+ *  `registry.getAllQueryHandlers()` + `getHandlerEntity()` would return for a real app. There is
+ *  no `getAllEntities()` here on purpose — an entity with no fixture is exactly "no list handler
+ *  mounted", the case `buildToolCatalog` must skip. */
+function fakeRegistry(fixtures: readonly EntityFixture[]): RegistrySearchView {
+  const byQn = new Map(fixtures.map((f) => [f.qn, FAKE_HANDLER]));
+  const entityByQn = new Map(fixtures.map((f) => [f.qn, f.entityName]));
+  const entityByName = new Map(fixtures.map((f) => [f.entityName, f.entity]));
+  const searchableByName = new Map(fixtures.map((f) => [f.entityName, f.searchableFields]));
+
+  return {
+    getAllQueryHandlers: () => byQn,
+    getHandlerEntity: (qn) => entityByQn.get(qn),
+    getEntity: (entityName) => entityByName.get(entityName),
+    getSearchableFields: (entityName) => searchableByName.get(entityName) ?? [],
+  };
+}
+
+function vendorFixture(searchableFields: readonly string[] = []): EntityFixture {
+  return {
+    qn: "vendor-feature:query:vendor:list",
+    entityName: "vendor",
+    entity: vendorEntity,
+    searchableFields,
+  };
+}
+
+function invoiceFixture(searchableFields: readonly string[] = []): EntityFixture {
+  return {
+    qn: "invoice-feature:query:invoice:list",
+    entityName: "invoice",
+    entity: invoiceEntity,
+    searchableFields,
+  };
+}
+
+describe("buildToolCatalog", () => {
+  test("generates a search_<entity> tool only when searchable fields exist", () => {
+    const registry = fakeRegistry([vendorFixture(["name"]), invoiceFixture(["description"])]);
+    const catalog = buildToolCatalog(registry);
+    const names = catalog.tools.map((t) => t.name);
+
+    expect(names).toContain("search_vendor");
+    expect(names).toContain("search_invoice");
+  });
+
+  test("skips search_<entity> when the entity has no searchable fields", () => {
+    const registry = fakeRegistry([vendorFixture([])]);
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.tools.map((t) => t.name)).not.toContain("search_vendor");
+  });
+
+  test("skips an entity entirely when it has no mounted :list handler", () => {
+    // getHandlerEntity resolves it, but the qn doesn't end in ":<entity>:list" — e.g. a
+    // :detail handler picked up by a naive "any handler mentioning this entity" scan.
+    const registry: RegistrySearchView = {
+      getAllQueryHandlers: () => new Map([["vendor-feature:query:vendor:detail", FAKE_HANDLER]]),
+      getHandlerEntity: () => "vendor",
+      getEntity: () => vendorEntity,
+      getSearchableFields: () => ["name"],
+    };
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.tools).toEqual([]);
+  });
+
+  test("generates one find_<entity>_by_<field> tool per filterable field", () => {
+    const registry = fakeRegistry([vendorFixture(["name"])]);
+    const catalog = buildToolCatalog(registry);
+    const names = catalog.tools.map((t) => t.name);
+
+    expect(names).toContain("find_vendor_by_name");
+    expect(names).toContain("find_vendor_by_iban");
+    expect(names).toContain("find_vendor_by_status");
+    expect(names).not.toContain("find_vendor_by_notes"); // not filterable
+  });
+
+  test("select field becomes a string schema with an enum of its options", () => {
+    const registry = fakeRegistry([vendorFixture()]);
+    const catalog = buildToolCatalog(registry);
+    const statusTool = catalog.tools.find((t) => t.name === "find_vendor_by_status");
+
+    expect(statusTool?.inputSchema).toEqual({
+      type: "object",
+      properties: { status: { type: "string", enum: ["active", "archived"] } },
+      required: ["status"],
+      additionalProperties: false,
+    });
+  });
+
+  test("reference field becomes a string schema describing the referenced entity", () => {
+    const registry = fakeRegistry([invoiceFixture()]);
+    const catalog = buildToolCatalog(registry);
+    const vendorIdTool = catalog.tools.find((t) => t.name === "find_invoice_by_vendorId");
+
+    expect(vendorIdTool?.inputSchema).toEqual({
+      type: "object",
+      properties: {
+        vendorId: { type: "string", description: 'ID referencing "vendor"' },
+      },
+      required: ["vendorId"],
+      additionalProperties: false,
+    });
+  });
+
+  test("search tool description lists every searchable field", () => {
+    const registry = fakeRegistry([vendorFixture(["name", "iban"])]);
+    const catalog = buildToolCatalog(registry);
+    const searchTool = catalog.tools.find((t) => t.name === "search_vendor");
+
+    expect(searchTool?.description).toContain("name, iban");
+  });
+
+  test("empty registry produces an empty catalog", () => {
+    const registry = fakeRegistry([]);
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.tools).toEqual([]);
+    expect(catalog.dispatchTable.size).toBe(0);
+  });
+
+  test("dispatchTable maps search_<entity> to a search descriptor carrying the real qn", () => {
+    const registry = fakeRegistry([vendorFixture(["name"])]);
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.dispatchTable.get("search_vendor")).toEqual({
+      kind: "search",
+      entityName: "vendor",
+      qn: "vendor-feature:query:vendor:list",
+    });
+  });
+
+  test("dispatchTable maps find_<entity>_by_<field> to a findBy descriptor carrying the real qn", () => {
+    const registry = fakeRegistry([vendorFixture()]);
+    const catalog = buildToolCatalog(registry);
+    expect(catalog.dispatchTable.get("find_vendor_by_iban")).toEqual({
+      kind: "findBy",
+      entityName: "vendor",
+      fieldName: "iban",
+      qn: "vendor-feature:query:vendor:list",
+    });
+  });
+});

package/src/agent-tools/__tests__/tool-dispatch.integration.test.ts

@@ -0,0 +1,100 @@
+// Proves the property the unit tests can't: dispatchToolCall runs through the
+// REAL <entity>:list handler + permission pipeline, not a fake. Two things a
+// hand-rolled recording dispatcher would happily hide:
+//   - tenant isolation: tenant A's find_by_iban call must never surface
+//     tenant B's row, even when both tenants have the exact same IBAN value.
+//   - cap enforcement: a caller without the list handler's required role
+//     gets denied, not an empty-but-"ok" result.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { buildToolCatalog } from "../tool-catalog";
+import { dispatchToolCall } from "../tool-dispatch";
+
+const vendorEntity = createEntity({
+  table: "agent_tools_test_vendors",
+  fields: {
+    name: createTextField({ required: true, searchable: true, filterable: true }),
+    iban: createTextField({ required: true, filterable: true }),
+  },
+});
+
+const vendorFeature = defineFeature("agent-tools-test-vendor", (r) => {
+  r.crud("vendor", vendorEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: { roles: ["Reader"] } },
+  });
+});
+
+const VENDOR_CREATE_QN = "agent-tools-test-vendor:write:vendor:create";
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [vendorFeature] });
+  await unsafeCreateEntityTable(stack.db, vendorEntity);
+  await createEventsTable(stack.db);
+}, 20000);
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM agent_tools_test_vendors");
+});
+
+const TENANT_B = "00000000-0000-4000-8000-0000000000bb";
+
+const adminA = createTestUser({ roles: ["Admin"] });
+const adminB = createTestUser({ roles: ["Admin"], tenantId: TENANT_B });
+const readerA = createTestUser({ roles: ["Reader"], id: adminA.id, tenantId: adminA.tenantId });
+const noRoleA = createTestUser({ roles: [], id: adminA.id, tenantId: adminA.tenantId });
+
+describe("dispatchToolCall — real <entity>:list pipeline", () => {
+  test("find_vendor_by_iban never leaks another tenant's row, even on an identical IBAN", async () => {
+    await stack.dispatcher.write(VENDOR_CREATE_QN, { name: "Acme A", iban: "DE-SAME" }, adminA);
+    await stack.dispatcher.write(VENDOR_CREATE_QN, { name: "Acme B", iban: "DE-SAME" }, adminB);
+
+    const catalog = buildToolCatalog(stack.registry);
+    const result = await dispatchToolCall(
+      stack.dispatcher,
+      readerA,
+      "find_vendor_by_iban",
+      { iban: "DE-SAME" },
+      catalog.dispatchTable,
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("unreachable");
+    const rows = (result.data as { rows: readonly { name: unknown }[] }).rows;
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.name).toBe("Acme A");
+  });
+
+  test("a caller without the list handler's required role gets denied, not an empty ok result", async () => {
+    await stack.dispatcher.write(VENDOR_CREATE_QN, { name: "Acme A", iban: "DE-SAME" }, adminA);
+
+    const catalog = buildToolCatalog(stack.registry);
+    const result = await dispatchToolCall(
+      stack.dispatcher,
+      noRoleA,
+      "find_vendor_by_iban",
+      { iban: "DE-SAME" },
+      catalog.dispatchTable,
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.error).toContain("access denied");
+  });
+});