@checkstack/catalog-backend 1.3.1 → 1.4.1

package/src/catalog-gitops-kinds.test.ts

@@ -35,13 +35,69 @@ interface MockGroup {
   updatedAt: Date;
 }
 
+interface MockEnvironment {
+  id: string;
+  name: string;
+  description?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
 function createMockEntityService() {
   const systems: MockSystem[] = [];
   const groups: MockGroup[] = [];
+  const environments: MockEnvironment[] = [];
 
   return {
     systems,
     groups,
+    environments,
+    createEnvironment: mock(
+      async (data: {
+        name: string;
+        description?: string;
+        metadata?: Record<string, unknown>;
+      }) => {
+        const environment: MockEnvironment = {
+          id: `env-${environments.length + 1}`,
+          name: data.name,
+          description: data.description,
+          metadata: data.metadata,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        };
+        environments.push(environment);
+        return environment;
+      },
+    ),
+    updateEnvironment: mock(
+      async (
+        id: string,
+        data: Partial<{
+          name: string;
+          description?: string;
+          metadata?: Record<string, unknown>;
+        }>,
+      ) => {
+        const environment = environments.find((e) => e.id === id);
+        if (environment) Object.assign(environment, data);
+        return environment;
+      },
+    ),
+    deleteEnvironment: mock(async (id: string) => {
+      const idx = environments.findIndex((e) => e.id === id);
+      if (idx >= 0) environments.splice(idx, 1);
+    }),
+    addSystemToEnvironment: mock(
+      async (_props: { environmentId: string; systemId: string }) => {},
+    ),
+    removeSystemFromEnvironment: mock(
+      async (_props: { environmentId: string; systemId: string }) => {},
+    ),
+    getEnvironmentsForSystem: mock(async (_systemId: string) => {
+      return [] as { environmentId: string; systemId: string }[];
+    }),
     createSystem: mock(async (data: { name: string; description?: string }) => {
       const system: MockSystem = {
         id: `sys-${systems.length + 1}`,
@@ -454,3 +510,235 @@ describe("Catalog GitOps Kind: Group", () => {
     expect(mockService.groups).toHaveLength(0);
   });
 });
+
+describe("Catalog GitOps Kind: Environment", () => {
+  let mockService: ReturnType<typeof createMockEntityService>;
+
+  const environmentSpecSchema = z.object({
+    fields: z.record(z.string(), z.unknown()).optional(),
+  });
+  type EnvironmentSpec = z.infer<typeof environmentSpecSchema>;
+
+  function buildEnvironmentKind(
+    svc: ReturnType<typeof createMockEntityService>,
+  ): EntityKindDefinition<EnvironmentSpec> {
+    return {
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Environment",
+      specSchema: environmentSpecSchema,
+      reconcile: async ({ entity, existingEntityId, context }) => {
+        const displayName = entity.metadata.title ?? entity.metadata.name;
+        const description = entity.metadata.description;
+        const metadata = entity.spec.fields ?? {};
+
+        if (existingEntityId) {
+          await svc.updateEnvironment(existingEntityId, {
+            name: displayName,
+            description,
+            metadata,
+          });
+          context.logger.info(`Updated environment (id: ${existingEntityId})`);
+          return { entityId: existingEntityId };
+        }
+
+        const environment = await svc.createEnvironment({
+          name: displayName,
+          description,
+          metadata,
+        });
+        context.logger.info(`Created environment (id: ${environment.id})`);
+        return { entityId: environment.id };
+      },
+      delete: async ({ entityId }) => {
+        if (entityId) await svc.deleteEnvironment(entityId);
+      },
+    };
+  }
+
+  beforeEach(() => {
+    mockService = createMockEntityService();
+  });
+
+  it("creates a new environment with free-form custom fields", async () => {
+    const kind = buildEnvironmentKind(mockService);
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Environment",
+        metadata: {
+          name: "production",
+          title: "Production",
+          description: "Live traffic",
+        },
+        spec: { fields: { baseUrl: "https://prod.example.com", tier: "1" } },
+      },
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("env-1");
+    expect(mockService.createEnvironment).toHaveBeenCalledTimes(1);
+    expect(mockService.environments).toHaveLength(1);
+    expect(mockService.environments[0].name).toBe("Production");
+    expect(mockService.environments[0].description).toBe("Live traffic");
+    expect(mockService.environments[0].metadata).toEqual({
+      baseUrl: "https://prod.example.com",
+      tier: "1",
+    });
+  });
+
+  it("defaults metadata to {} when spec.fields is absent", async () => {
+    const kind = buildEnvironmentKind(mockService);
+
+    await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Environment",
+        metadata: { name: "staging" },
+        spec: {},
+      },
+      context: mockContext,
+    });
+
+    expect(mockService.environments[0].name).toBe("staging");
+    expect(mockService.environments[0].metadata).toEqual({});
+  });
+
+  it("updates an existing environment using existingEntityId", async () => {
+    const kind = buildEnvironmentKind(mockService);
+
+    mockService.environments.push({
+      id: "env-existing",
+      name: "Old",
+      metadata: { region: "eu" },
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Environment",
+        metadata: { name: "production", title: "Production v2" },
+        spec: { fields: { region: "us" } },
+      },
+      existingEntityId: "env-existing",
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("env-existing");
+    expect(mockService.createEnvironment).not.toHaveBeenCalled();
+    expect(mockService.updateEnvironment).toHaveBeenCalledTimes(1);
+    expect(mockService.environments[0].name).toBe("Production v2");
+    expect(mockService.environments[0].metadata).toEqual({ region: "us" });
+  });
+
+  it("deletes an environment by entityId", async () => {
+    const kind = buildEnvironmentKind(mockService);
+
+    mockService.environments.push({
+      id: "env-del",
+      name: "To Delete",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    await kind.delete!({
+      entityName: "old-env",
+      entityId: "env-del",
+      context: mockContext,
+    });
+
+    expect(mockService.deleteEnvironment).toHaveBeenCalledWith("env-del");
+    expect(mockService.environments).toHaveLength(0);
+  });
+
+  it("skips delete when entityId is missing", async () => {
+    const kind = buildEnvironmentKind(mockService);
+
+    await kind.delete!({
+      entityName: "unknown-env",
+      context: mockContext,
+    });
+
+    expect(mockService.deleteEnvironment).not.toHaveBeenCalled();
+  });
+});
+
+describe("Catalog GitOps Kind Extension: System -> environments", () => {
+  let mockService: ReturnType<typeof createMockEntityService>;
+
+  beforeEach(() => {
+    mockService = createMockEntityService();
+  });
+
+  it("associates system with environments and removes stale ones", async () => {
+    mockService.getEnvironmentsForSystem.mockResolvedValueOnce([
+      { environmentId: "env-stale", systemId: "sys-1" },
+    ]);
+
+    const mockExtContext: ReconcileContext = {
+      ...mockContext,
+      resolveEntityRef: mock(async ({ entityName }) => {
+        if (entityName === "new-env") return "env-new";
+        return undefined;
+      }),
+    };
+
+    // Simulate the inline reconcile logic from index.ts
+    const reconcileExt = async ({
+      extensionSpec,
+      entityId,
+      context,
+    }: {
+      extensionSpec?: { kind: string; name: string }[];
+      entityId: string;
+      context: ReconcileContext;
+    }) => {
+      if (!extensionSpec || extensionSpec.length === 0) return;
+
+      const desiredEnvironmentIds = new Set<string>();
+
+      for (const entry of extensionSpec) {
+        const environmentId = await context.resolveEntityRef({
+          kind: entry.kind,
+          entityName: entry.name,
+        });
+        if (environmentId) {
+          desiredEnvironmentIds.add(environmentId);
+          await mockService.addSystemToEnvironment({
+            environmentId,
+            systemId: entityId,
+          });
+        }
+      }
+
+      const currentAssociations =
+        await mockService.getEnvironmentsForSystem(entityId);
+      for (const existing of currentAssociations) {
+        if (!desiredEnvironmentIds.has(existing.environmentId)) {
+          await mockService.removeSystemFromEnvironment({
+            environmentId: existing.environmentId,
+            systemId: entityId,
+          });
+        }
+      }
+    };
+
+    await reconcileExt({
+      extensionSpec: [{ kind: "Environment", name: "new-env" }],
+      entityId: "sys-1",
+      context: mockExtContext,
+    });
+
+    expect(mockService.addSystemToEnvironment).toHaveBeenCalledWith({
+      environmentId: "env-new",
+      systemId: "sys-1",
+    });
+
+    expect(mockService.removeSystemFromEnvironment).toHaveBeenCalledWith({
+      environmentId: "env-stale",
+      systemId: "sys-1",
+    });
+  });
+});

package/src/index.ts

@@ -3,6 +3,12 @@ import {
   type SafeDatabase,
 } from "@checkstack/backend-api";
 import { coreServices } from "@checkstack/backend-api";
+import {
+  aiToolExtensionPoint,
+  aiToolProjectionExtensionPoint,
+  deferredProjectionExecute,
+} from "@checkstack/ai-backend";
+import { buildCatalogAiTools } from "./ai/register-ai-tools";
 import {
   automationActionExtensionPoint,
   automationArtifactTypeExtensionPoint,
@@ -289,6 +295,109 @@ export default createBackendPlugin({
       },
     });
 
+    // Register kind: Environment (mirror "Group")
+    kindRegistry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Environment",
+      // Free-form custom fields. `z.record` keeps GitOps in step with the
+      // free-form metadata decision (v1): fields surface in templating verbatim.
+      specSchema: z.object({
+        fields: z.record(z.string(), z.unknown()).optional(),
+      }),
+      reconcile: async ({ entity, existingEntityId, context }) => {
+        if (!gitopsDb) throw new Error("Catalog database not initialized");
+        const entityService = new EntityService(gitopsDb);
+        const displayName = entity.metadata.title ?? entity.metadata.name;
+        const description = entity.metadata.description;
+        const metadata = entity.spec.fields ?? {};
+
+        if (existingEntityId) {
+          await entityService.updateEnvironment(existingEntityId, {
+            name: displayName,
+            description,
+            metadata,
+          });
+          context.logger.info(
+            `GitOps: updated Environment "${displayName}" (id: ${existingEntityId})`,
+          );
+          return { entityId: existingEntityId };
+        }
+
+        const environment = await entityService.createEnvironment({
+          name: displayName,
+          description,
+          metadata,
+        });
+        context.logger.info(
+          `GitOps: created Environment "${displayName}" (id: ${environment.id})`,
+        );
+        return { entityId: environment.id };
+      },
+      delete: async ({ entityId, context }) => {
+        if (!gitopsDb) throw new Error("Catalog database not initialized");
+        if (!entityId) return;
+        const entityService = new EntityService(gitopsDb);
+        await entityService.deleteEnvironment(entityId);
+        context.logger.info(`GitOps: deleted Environment (id: ${entityId})`);
+      },
+    });
+
+    // Register kind extension: System -> environments (mirror System -> groups)
+    kindRegistry.registerKindExtension({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      namespace: "environments",
+      specSchema: z.array(entityRefSchema).optional(),
+      reconcile: async ({ entity, extensionSpec, entityId, context }) => {
+        if (!gitopsDb) throw new Error("Catalog database not initialized");
+        if (!extensionSpec || extensionSpec.length === 0) return;
+
+        const entityService = new EntityService(gitopsDb);
+        const systemEntityId = entityId;
+
+        const desiredEnvironmentIds = new Set<string>();
+
+        for (const entry of extensionSpec) {
+          const environmentId = await context.resolveEntityRef({
+            kind: entry.kind,
+            entityName: entry.name,
+          });
+
+          if (!environmentId) {
+            throw new Error(
+              `Cannot resolve ${entry.kind} ref "${entry.name}" — ensure the entity exists`,
+            );
+          }
+
+          desiredEnvironmentIds.add(environmentId);
+
+          await entityService.addSystemToEnvironment({
+            environmentId,
+            systemId: systemEntityId,
+          });
+
+          context.logger.info(
+            `GitOps: associated System "${entity.metadata.name}" with Environment "${entry.name}" (${environmentId})`,
+          );
+        }
+
+        // Remove stale associations not in the spec
+        const currentAssociations =
+          await entityService.getEnvironmentsForSystem(systemEntityId);
+        for (const existing of currentAssociations) {
+          if (!desiredEnvironmentIds.has(existing.environmentId)) {
+            await entityService.removeSystemFromEnvironment({
+              environmentId: existing.environmentId,
+              systemId: systemEntityId,
+            });
+            context.logger.info(
+              `GitOps: removed stale association ${existing.environmentId} from System "${entity.metadata.name}"`,
+            );
+          }
+        }
+      },
+    });
+
     env.registerInit({
       schema,
       deps: {
@@ -331,6 +440,46 @@ export default createBackendPlugin({
         });
         rpc.registerRouter(catalogRouter, catalogContract);
 
+        // Register this plugin's AI tools (system + group + membership) into
+        // the AI registry via the extension point - owned here, not in
+        // ai-backend. The tools go through the USER-SCOPED client passed at
+        // call time, so handler-side authorization is enforced exactly as a
+        // direct UI/RPC call.
+        const aiToolExt = env.getExtensionPoint(aiToolExtensionPoint);
+        for (const tool of buildCatalogAiTools()) {
+          aiToolExt.registerTool(tool, pluginMetadata);
+        }
+
+        // Expose this plugin's OWN read-only AI projections of the existing
+        // `getSystems` / `getGroups` queries via aiToolProjectionExtensionPoint
+        // - owned here, not in ai-backend. The projected read tools are routed
+        // by the transport (MCP / chat) AS the principal, so the procedures'
+        // own contract access rules gate them; `deferredProjectionExecute` is
+        // the fail-closed net if a transport ever forgot to route.
+        const aiProjectionExt = env.getExtensionPoint(
+          aiToolProjectionExtensionPoint,
+        );
+        aiProjectionExt.expose({
+          procedure: catalogContract.getSystems,
+          sourcePluginMetadata: pluginMetadata,
+          procedureKey: "getSystems",
+          name: "catalog.listSystems",
+          description:
+            "List all systems (services/resources) with their ids and names. Read-only. Use this to resolve a system name to its id.",
+          effect: "read",
+          execute: deferredProjectionExecute,
+        });
+        aiProjectionExt.expose({
+          procedure: catalogContract.getGroups,
+          sourcePluginMetadata: pluginMetadata,
+          procedureKey: "getGroups",
+          name: "catalog.listGroups",
+          description:
+            "List all system groups with ids and names. Read-only.",
+          effect: "read",
+          execute: deferredProjectionExecute,
+        });
+
         // Register catalog systems as searchable in the command palette
         registerSearchProvider({
           pluginMetadata,

package/src/router.test.ts

@@ -134,6 +134,89 @@ describe("Catalog Router - GitOps Provenance Enforcement", () => {
     expect((error as any).code).toBe("FORBIDDEN");
   });
 
+  it("throws CONFLICT when creating a system whose name already exists", async () => {
+    // getSystemByName (the first/only select before the guard throws) finds a
+    // system already using this name.
+    (mockDb as { select: ReturnType<typeof mock> }).select.mockReturnValueOnce({
+      from: () => ({
+        where: () =>
+          Promise.resolve([
+            {
+              id: "existing",
+              name: "Payments",
+              description: null,
+              metadata: {},
+              createdAt: new Date(),
+              updatedAt: new Date(),
+            },
+          ]),
+      }),
+    });
+    const context = createMockRpcContext({ user: mockUser });
+
+    let error;
+    try {
+      await call(router.createSystem, { name: "Payments" }, { context });
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeDefined();
+    expect((error as any).code).toBe("CONFLICT");
+    expect((error as any).message).toContain("already exists");
+  });
+
+  it("throws CONFLICT when renaming a system to a name another system uses", async () => {
+    mockGitOpsClient.getProvenance.mockResolvedValueOnce(null);
+    // 1st select: getSystem(id) finds the system being renamed.
+    // 2nd select: getSystemByName(newName) finds a DIFFERENT system.
+    (mockDb as { select: ReturnType<typeof mock> }).select
+      .mockReturnValueOnce({
+        from: () => ({
+          where: () =>
+            Promise.resolve([
+              {
+                id: "sys-1",
+                name: "Old",
+                description: null,
+                metadata: {},
+                createdAt: new Date(),
+                updatedAt: new Date(),
+              },
+            ]),
+        }),
+      })
+      .mockReturnValueOnce({
+        from: () => ({
+          where: () =>
+            Promise.resolve([
+              {
+                id: "other",
+                name: "Taken",
+                description: null,
+                metadata: {},
+                createdAt: new Date(),
+                updatedAt: new Date(),
+              },
+            ]),
+        }),
+      });
+    const context = createMockRpcContext({ user: mockUser });
+
+    let error;
+    try {
+      await call(
+        router.updateSystem,
+        { id: "sys-1", data: { name: "Taken" } },
+        { context },
+      );
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeDefined();
+    expect((error as any).code).toBe("CONFLICT");
+    expect((error as any).message).toContain("already exists");
+  });
+
   it("allows adding an unlocked system to a group, even if the group is locked", async () => {
     mockGitOpsClient.getProvenance.mockResolvedValueOnce(null);
     
@@ -145,4 +228,28 @@ describe("Catalog Router - GitOps Provenance Enforcement", () => {
       expect(e.code).not.toBe("FORBIDDEN");
     }
   });
+
+  it("maps a DB unique violation (concurrent create race) to CONFLICT", async () => {
+    // The pre-insert name check finds no clash...
+    (mockDb as { select: ReturnType<typeof mock> }).select.mockReturnValueOnce({
+      from: () => ({ where: () => Promise.resolve([]) }),
+    });
+    // ...but the INSERT loses a race and the DB's unique index rejects it.
+    (mockDb as { insert: ReturnType<typeof mock> }).insert = mock(() => ({
+      values: () => ({
+        returning: () => Promise.reject({ code: "23505" }),
+      }),
+    }));
+    const context = createMockRpcContext({ user: mockUser });
+
+    let error;
+    try {
+      await call(router.createSystem, { name: "Payments" }, { context });
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeDefined();
+    expect((error as any).code).toBe("CONFLICT");
+    expect((error as any).message).toContain("already exists");
+  });
 });