@checkstack/catalog-backend 1.3.0 → 1.4.0

package/src/ai/catalog-add-system-to-group.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createCatalogAddSystemToGroupTool } from "./catalog-add-system-to-group";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["catalog.system.manage", "catalog.group.manage"],
+};
+
+function fakeRpcClient({
+  addSystemToGroup,
+}: {
+  addSystemToGroup: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ addSystemToGroup }),
+  } as unknown as RpcClient;
+}
+
+describe("catalog.addSystemToGroup tool", () => {
+  test("declares mutate effect + the system manage rule", () => {
+    const tool = createCatalogAddSystemToGroupTool();
+    expect(tool.name).toBe("catalog.addSystemToGroup");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual(["catalog.system.manage"]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun summarizes the membership and NEVER mutates", async () => {
+    const addSystemToGroup = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({ addSystemToGroup });
+    const tool = createCatalogAddSystemToGroupTool();
+    const input = { groupId: "grp1", systemId: "sys1" };
+    const preview = await tool.dryRun!({ input, principal, rpcClient });
+    expect(addSystemToGroup).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("sys1");
+    expect(preview.summary).toContain("grp1");
+    expect(preview.payload).toEqual(input);
+  });
+
+  test("execute (apply) calls addSystemToGroup with { groupId, systemId }", async () => {
+    const addSystemToGroup = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({ addSystemToGroup });
+    const tool = createCatalogAddSystemToGroupTool();
+    const input = { groupId: "grp1", systemId: "sys1" };
+    const result = await tool.execute({ input, principal, rpcClient });
+    expect(addSystemToGroup).toHaveBeenCalledWith(input);
+    expect(result).toEqual({ groupId: "grp1", systemId: "sys1", added: true });
+  });
+});

package/src/ai/catalog-add-system-to-group.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  CatalogApi,
+  catalogAccess,
+  pluginMetadata,
+} from "@checkstack/catalog-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Input for `catalog.addSystemToGroup`: the group + system to associate. */
+export const CatalogAddSystemToGroupInputSchema = z.object({
+  groupId: z.string(),
+  systemId: z.string(),
+});
+export type CatalogAddSystemToGroupInput = z.infer<
+  typeof CatalogAddSystemToGroupInputSchema
+>;
+
+/** Output returned once a human applies the membership change. */
+export interface CatalogAddSystemToGroupApplyResult {
+  groupId: string;
+  systemId: string;
+  added: true;
+}
+
+/**
+ * `catalog.addSystemToGroup` - add a system to a group.
+ *
+ * `effect: "mutate"` - a reversible membership change, so it auto-applies in AUTO
+ * mode and is confirm-gated in APPROVE mode. Membership is part of the system
+ * surface, so authorization is the `system.manage` rule (matching the contract).
+ */
+export function createCatalogAddSystemToGroupTool(): RegisteredAiTool<
+  CatalogAddSystemToGroupInput,
+  CatalogAddSystemToGroupApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: CatalogAddSystemToGroupInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<CatalogAddSystemToGroupInput>> => {
+    return {
+      summary: `Add system "${input.systemId}" to group "${input.groupId}".`,
+      payload: input,
+    };
+  };
+
+  return {
+    name: "catalog.addSystemToGroup",
+    description:
+      "Add a system to a group by their ids. Never changes membership directly; a person must approve unless the conversation is in auto mode. Find the ids with the catalog read tools first.",
+    effect: "mutate",
+    input: CatalogAddSystemToGroupInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, catalogAccess.system.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const catalogClient = rpcClient.forPlugin(CatalogApi);
+      await catalogClient.addSystemToGroup(input);
+      return { groupId: input.groupId, systemId: input.systemId, added: true };
+    },
+  };
+}

package/src/ai/catalog-create-group.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createCatalogCreateGroupTool } from "./catalog-create-group";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["catalog.system.manage", "catalog.group.manage"],
+};
+
+const group = {
+  id: "grp1",
+  name: "Payments",
+  systemIds: [],
+  metadata: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+function fakeRpcClient({
+  createGroup,
+}: {
+  createGroup: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ createGroup }),
+  } as unknown as RpcClient;
+}
+
+describe("catalog.createGroup tool", () => {
+  test("declares mutate effect + the group manage rule", () => {
+    const tool = createCatalogCreateGroupTool();
+    expect(tool.name).toBe("catalog.createGroup");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual(["catalog.group.manage"]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun summarizes the create and NEVER creates", async () => {
+    const createGroup = mock(() => Promise.resolve(group));
+    const rpcClient = fakeRpcClient({ createGroup });
+    const tool = createCatalogCreateGroupTool();
+    const preview = await tool.dryRun!({
+      input: { name: "Payments" },
+      principal,
+      rpcClient,
+    });
+    expect(createGroup).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("Payments");
+    expect(preview.payload).toEqual({ name: "Payments" });
+  });
+
+  test("execute (apply) creates via createGroup", async () => {
+    const createGroup = mock(() => Promise.resolve(group));
+    const rpcClient = fakeRpcClient({ createGroup });
+    const tool = createCatalogCreateGroupTool();
+    const input = { name: "Payments" };
+    const result = await tool.execute({ input, principal, rpcClient });
+    expect(createGroup).toHaveBeenCalledWith(input);
+    expect(result).toEqual({ group });
+  });
+});

package/src/ai/catalog-create-group.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  CatalogApi,
+  catalogAccess,
+  pluginMetadata,
+  type Group,
+} from "@checkstack/catalog-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/**
+ * Input for `catalog.createGroup`. Mirrors the contract's (module-private)
+ * `CreateGroupInputSchema`: a group has a required name plus optional free-form
+ * metadata.
+ */
+export const CatalogCreateGroupInputSchema = z.object({
+  name: z.string().min(1),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type CatalogCreateGroupInput = z.infer<
+  typeof CatalogCreateGroupInputSchema
+>;
+
+/** Output returned once a human applies the create (the created group). */
+export interface CatalogCreateGroupApplyResult {
+  group: Group;
+}
+
+/**
+ * `catalog.createGroup` - create a new system group in the catalog.
+ *
+ * `effect: "mutate"` - a non-destructive create, so it auto-applies in AUTO mode
+ * and is confirm-gated in APPROVE mode. Authorization is the `group.manage` rule
+ * the UI create form requires.
+ */
+export function createCatalogCreateGroupTool(): RegisteredAiTool<
+  CatalogCreateGroupInput,
+  CatalogCreateGroupApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: CatalogCreateGroupInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<CatalogCreateGroupInput>> => {
+    return {
+      summary: `Create group "${input.name}".`,
+      payload: input,
+    };
+  };
+
+  return {
+    name: "catalog.createGroup",
+    description:
+      "Create a new system group in the catalog with a name and optional metadata. Never creates directly; a person must approve unless the conversation is in auto mode.",
+    effect: "mutate",
+    input: CatalogCreateGroupInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, catalogAccess.group.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const catalogClient = rpcClient.forPlugin(CatalogApi);
+      const group = await catalogClient.createGroup(input);
+      return { group };
+    },
+  };
+}

package/src/ai/catalog-create-system.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createCatalogCreateSystemTool } from "./catalog-create-system";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["catalog.system.manage", "catalog.group.manage"],
+};
+
+const system = {
+  id: "sys1",
+  name: "Checkout API",
+  description: "Handles checkout",
+  metadata: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+function fakeRpcClient({
+  createSystem,
+}: {
+  createSystem: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ createSystem }),
+  } as unknown as RpcClient;
+}
+
+describe("catalog.createSystem tool", () => {
+  test("declares mutate effect + the system manage rule", () => {
+    const tool = createCatalogCreateSystemTool();
+    expect(tool.name).toBe("catalog.createSystem");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual(["catalog.system.manage"]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun summarizes the create and NEVER creates", async () => {
+    const createSystem = mock(() => Promise.resolve(system));
+    const rpcClient = fakeRpcClient({ createSystem });
+    const tool = createCatalogCreateSystemTool();
+    const preview = await tool.dryRun!({
+      input: { name: "Checkout API" },
+      principal,
+      rpcClient,
+    });
+    expect(createSystem).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("Checkout API");
+    expect(preview.payload).toEqual({ name: "Checkout API" });
+  });
+
+  test("execute (apply) creates via createSystem", async () => {
+    const createSystem = mock(() => Promise.resolve(system));
+    const rpcClient = fakeRpcClient({ createSystem });
+    const tool = createCatalogCreateSystemTool();
+    const input = { name: "Checkout API", description: "Handles checkout" };
+    const result = await tool.execute({ input, principal, rpcClient });
+    expect(createSystem).toHaveBeenCalledWith(input);
+    expect(result).toEqual({ system });
+  });
+});

package/src/ai/catalog-create-system.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  CatalogApi,
+  catalogAccess,
+  pluginMetadata,
+  type System,
+} from "@checkstack/catalog-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/**
+ * Input for `catalog.createSystem`. Mirrors the contract's (module-private)
+ * `CreateSystemInputSchema`: a system has a required name plus optional
+ * description and free-form metadata.
+ */
+export const CatalogCreateSystemInputSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type CatalogCreateSystemInput = z.infer<
+  typeof CatalogCreateSystemInputSchema
+>;
+
+/** Output returned once a human applies the create (the created system). */
+export interface CatalogCreateSystemApplyResult {
+  system: System;
+}
+
+/**
+ * `catalog.createSystem` - create a new system (a service or resource) in the
+ * catalog.
+ *
+ * `effect: "mutate"` - a non-destructive create, so it auto-applies in AUTO mode
+ * and is confirm-gated in APPROVE mode via the propose/apply machinery. The
+ * underlying RPC uses the USER-SCOPED client passed at call time, so handler-side
+ * authorization is enforced exactly as a direct UI/RPC call. Authorization is the
+ * `system.manage` rule the UI create form requires, re-checked at propose AND
+ * apply time by the propose/apply service.
+ */
+export function createCatalogCreateSystemTool(): RegisteredAiTool<
+  CatalogCreateSystemInput,
+  CatalogCreateSystemApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: CatalogCreateSystemInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<CatalogCreateSystemInput>> => {
+    return {
+      summary: `Create system "${input.name}"${
+        input.description ? ` (${input.description})` : ""
+      }.`,
+      payload: input,
+    };
+  };
+
+  return {
+    name: "catalog.createSystem",
+    description:
+      "Create a new system (a service or resource) in the catalog with a name and optional description and metadata. Never creates directly; a person must approve unless the conversation is in auto mode.",
+    effect: "mutate",
+    input: CatalogCreateSystemInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, catalogAccess.system.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const catalogClient = rpcClient.forPlugin(CatalogApi);
+      const system = await catalogClient.createSystem(input);
+      return { system };
+    },
+  };
+}

package/src/ai/catalog-delete-group.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createCatalogDeleteGroupTool } from "./catalog-delete-group";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["catalog.system.manage", "catalog.group.manage"],
+};
+
+const group = {
+  id: "grp1",
+  name: "Payments",
+  systemIds: [],
+  metadata: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+function fakeRpcClient({
+  getGroups,
+  deleteGroup,
+}: {
+  getGroups: ReturnType<typeof mock>;
+  deleteGroup: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ getGroups, deleteGroup }),
+  } as unknown as RpcClient;
+}
+
+describe("catalog.deleteGroup tool", () => {
+  test("declares destructive effect + the group manage rule", () => {
+    const tool = createCatalogDeleteGroupTool();
+    expect(tool.name).toBe("catalog.deleteGroup");
+    expect(tool.effect).toBe("destructive");
+    expect(tool.requiredAccessRules).toEqual(["catalog.group.manage"]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun resolves the target and NEVER deletes", async () => {
+    const getGroups = mock(() => Promise.resolve([group]));
+    const deleteGroup = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({ getGroups, deleteGroup });
+    const tool = createCatalogDeleteGroupTool();
+    const preview = await tool.dryRun!({
+      input: { id: "grp1" },
+      principal,
+      rpcClient,
+    });
+    expect(deleteGroup).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("Payments");
+    expect(preview.summary).toContain("permanent");
+    expect(preview.payload).toEqual({ id: "grp1" });
+  });
+
+  test("dryRun throws a clear error when the id is unknown", async () => {
+    const rpcClient = fakeRpcClient({
+      getGroups: mock(() => Promise.resolve([group])),
+      deleteGroup: mock(),
+    });
+    const tool = createCatalogDeleteGroupTool();
+    await expect(
+      tool.dryRun!({ input: { id: "nope" }, principal, rpcClient }),
+    ).rejects.toThrow(/No group found/);
+  });
+
+  test("execute (apply) deletes via deleteGroup with the POSITIONAL id", async () => {
+    const deleteGroup = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({
+      getGroups: mock(() => Promise.resolve([group])),
+      deleteGroup,
+    });
+    const tool = createCatalogDeleteGroupTool();
+    const result = await tool.execute({
+      input: { id: "grp1" },
+      principal,
+      rpcClient,
+    });
+    expect(deleteGroup).toHaveBeenCalledWith("grp1");
+    expect(result).toEqual({ id: "grp1", deleted: true });
+  });
+});

package/src/ai/catalog-delete-group.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  CatalogApi,
+  catalogAccess,
+  pluginMetadata,
+} from "@checkstack/catalog-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Input for `catalog.deleteGroup`: the group id to remove. */
+export const CatalogDeleteGroupInputSchema = z.object({
+  id: z.string(),
+});
+export type CatalogDeleteGroupInput = z.infer<
+  typeof CatalogDeleteGroupInputSchema
+>;
+
+/** Output returned once a human applies the deletion. */
+export interface CatalogDeleteGroupApplyResult {
+  id: string;
+  deleted: true;
+}
+
+/**
+ * `catalog.deleteGroup` - delete a group by id.
+ *
+ * `effect: "destructive"` - deletion is irreversible, so it ALWAYS routes through
+ * the propose/apply confirm card in BOTH permission modes. `dryRun` resolves the
+ * target group (via `getGroups()`, since there is no single-group fetch) so the
+ * confirm card names exactly what will be removed; `execute` (reached only via
+ * `apply`) performs the delete via the contract's POSITIONAL string id.
+ */
+export function createCatalogDeleteGroupTool(): RegisteredAiTool<
+  CatalogDeleteGroupInput,
+  CatalogDeleteGroupApplyResult
+> {
+  const dryRun = async ({
+    input,
+    rpcClient,
+  }: {
+    input: CatalogDeleteGroupInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<CatalogDeleteGroupInput>> => {
+    const catalogClient = rpcClient.forPlugin(CatalogApi);
+    const groups = await catalogClient.getGroups();
+    const group = groups.find((g) => g.id === input.id);
+    if (!group) {
+      throw new Error(
+        `No group found with id "${input.id}". List groups first to get a valid id.`,
+      );
+    }
+    return {
+      summary: `Delete group "${group.name}". This is permanent and also removes its system memberships.`,
+      payload: { id: input.id },
+    };
+  };
+
+  return {
+    name: "catalog.deleteGroup",
+    description:
+      "Delete a group by id. DESTRUCTIVE and irreversible - it also removes the group's system memberships. Never deletes directly; a person must approve the confirmation. Find the id with the catalog read tools first.",
+    effect: "destructive",
+    input: CatalogDeleteGroupInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, catalogAccess.group.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const catalogClient = rpcClient.forPlugin(CatalogApi);
+      await catalogClient.deleteGroup(input.id);
+      return { id: input.id, deleted: true };
+    },
+  };
+}

package/src/ai/catalog-delete-system.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createCatalogDeleteSystemTool } from "./catalog-delete-system";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["catalog.system.manage", "catalog.group.manage"],
+};
+
+const system = {
+  id: "sys1",
+  name: "Checkout API",
+  description: "Handles checkout",
+  metadata: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+function fakeRpcClient({
+  getSystem,
+  deleteSystem,
+}: {
+  getSystem: ReturnType<typeof mock>;
+  deleteSystem: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ getSystem, deleteSystem }),
+  } as unknown as RpcClient;
+}
+
+describe("catalog.deleteSystem tool", () => {
+  test("declares destructive effect + the system manage rule", () => {
+    const tool = createCatalogDeleteSystemTool();
+    expect(tool.name).toBe("catalog.deleteSystem");
+    expect(tool.effect).toBe("destructive");
+    expect(tool.requiredAccessRules).toEqual(["catalog.system.manage"]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun resolves the target and NEVER deletes", async () => {
+    const getSystem = mock(() => Promise.resolve(system));
+    const deleteSystem = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({ getSystem, deleteSystem });
+    const tool = createCatalogDeleteSystemTool();
+    const preview = await tool.dryRun!({
+      input: { id: "sys1" },
+      principal,
+      rpcClient,
+    });
+    expect(getSystem).toHaveBeenCalledWith({ systemId: "sys1" });
+    expect(deleteSystem).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("Checkout API");
+    expect(preview.summary).toContain("permanent");
+    expect(preview.payload).toEqual({ id: "sys1" });
+  });
+
+  test("dryRun throws a clear error when the id is unknown", async () => {
+    const rpcClient = fakeRpcClient({
+      getSystem: mock(() => Promise.resolve(null)),
+      deleteSystem: mock(),
+    });
+    const tool = createCatalogDeleteSystemTool();
+    await expect(
+      tool.dryRun!({ input: { id: "nope" }, principal, rpcClient }),
+    ).rejects.toThrow(/No system found/);
+  });
+
+  test("execute (apply) deletes via deleteSystem with the POSITIONAL id", async () => {
+    const deleteSystem = mock(() => Promise.resolve({ success: true }));
+    const rpcClient = fakeRpcClient({
+      getSystem: mock(() => Promise.resolve(system)),
+      deleteSystem,
+    });
+    const tool = createCatalogDeleteSystemTool();
+    const result = await tool.execute({
+      input: { id: "sys1" },
+      principal,
+      rpcClient,
+    });
+    expect(deleteSystem).toHaveBeenCalledWith("sys1");
+    expect(result).toEqual({ id: "sys1", deleted: true });
+  });
+});