@checkstack/catalog-backend 0.2.24 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @checkstack/catalog-backend
 
+## 0.4.0
+
+### Minor Changes
+
+- b01078f: Added GitOps System kind extension for managing system group associations
+
+## 0.3.0
+
+### Minor Changes
+
+- 6c40b5b: Register catalog System and Group as GitOps entity kinds
+
+  - **catalog-backend**: Registers `kind: System` and `kind: Group` with the GitOps Entity Kind Registry. The catalog now supports declarative management via YAML descriptors in Git repositories. Systems and groups are reconciled using the `metadata.gitops_entity_name` marker for cross-sync identity lookup.
+  - **gitops-backend**: Wires up the delete reconciler for orphan cleanup — both automatic deletion (via `deletionPolicy: "auto"`) and manual orphan confirmation now invoke the owning plugin's `delete()` handler before removing provenance entries.
+
+- 6c40b5b: Generalized provenance system and GitOps frontend plugin
+
+  **Breaking**: `EntityKindDefinition.reconcile()` now returns `{ entityId: string }` instead of `void`. Plugins must return the plugin-specific entity ID (e.g., catalog system UUID) so the engine can store it in provenance.
+
+  - Added `entityId` column to the provenance table (non-nullable)
+  - Reconciler engine passes `existingEntityId` to plugins for updates
+  - `getProvenance` now supports lookup by `entityId` in addition to `entityName`
+  - Added provider CRUD endpoints: `createProvider`, `updateProvider`, `deleteProvider`
+  - Created `gitops-frontend` plugin with provider management, secret management, and sync status dashboard
+  - Removed `gitops_entity_name` metadata markers from catalog entities
+  - Removed `findSystemByGitOpsName`, `deleteSystemByGitOpsName` (and Group equivalents) from EntityService
+  - Added provenance-based UI locking in catalog-frontend: edit/delete/drag disabled for GitOps-managed systems and groups
+
+### Patch Changes
+
+- 6c40b5b: ### GitOps Ecosystem: Healthcheck Kind Registration (Phase 5)
+
+  **gitops-common**: Added required `resolveEntityRef` to `ReconcileContext`, enabling extension reconcilers to resolve cross-kind entity references (e.g., healthcheck refs in System extensions).
+
+  **gitops-backend**: Updated reconciler to populate `resolveEntityRef` by querying local provenance — no RPC round-trip needed.
+
+  **healthcheck-backend**: Registered `kind: Healthcheck` and `System → healthchecks` extension with the EntityKindRegistry:
+
+  - Validates strategy configs against registered strategy schemas at reconcile time
+  - Validates collector configs against registered collector schemas at reconcile time
+  - Manages system ↔ healthcheck associations with automatic stale removal
+
+  **healthcheck-frontend**: Added GitOps provenance locking to the HealthCheck IDE editor — GitOps-managed health checks show a lock banner and disable editing.
+
+  **catalog-backend**: Updated test fixtures for new required `resolveEntityRef` context field.
+
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+  - @checkstack/gitops-backend@0.1.0
+  - @checkstack/gitops-common@0.1.0
+
 ## 0.2.24
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/catalog-backend",
-  "version": "0.2.24",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -13,11 +13,13 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.11.1",
+    "@checkstack/backend-api": "0.12.0",
     "@checkstack/auth-common": "0.6.1",
     "@checkstack/catalog-common": "1.3.1",
-    "@checkstack/command-backend": "0.1.18",
-    "@checkstack/auth-backend": "0.4.17",
+    "@checkstack/command-backend": "0.1.19",
+    "@checkstack/auth-backend": "0.4.18",
+    "@checkstack/gitops-backend": "0.0.1",
+    "@checkstack/gitops-common": "0.0.1",
     "@checkstack/notification-common": "0.2.8",
     "@orpc/server": "^1.13.2",
     "drizzle-orm": "^0.45.0",

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

@@ -0,0 +1,454 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { z } from "zod";
+import { CHECKSTACK_API_VERSION } from "@checkstack/gitops-common";
+import type {
+  EntityKindDefinition,
+  ReconcileContext,
+} from "@checkstack/gitops-common";
+
+/**
+ * Tests for the catalog-backend's GitOps entity kind registrations.
+ *
+ * These tests exercise the reconcile/delete logic in isolation by
+ * reconstructing the same kind definitions that catalog-backend registers
+ * with the entity kind extension point.
+ *
+ * The generic entityId pattern: reconcile() returns { entityId }, the
+ * reconciler engine stores it in provenance, and passes it back as
+ * existingEntityId on subsequent reconciles.
+ */
+
+// ─── Mock EntityService ────────────────────────────────────────────────────
+
+interface MockSystem {
+  id: string;
+  name: string;
+  description?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface MockGroup {
+  id: string;
+  name: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+function createMockEntityService() {
+  const systems: MockSystem[] = [];
+  const groups: MockGroup[] = [];
+
+  return {
+    systems,
+    groups,
+    createSystem: mock(async (data: { name: string; description?: string }) => {
+      const system: MockSystem = {
+        id: `sys-${systems.length + 1}`,
+        name: data.name,
+        description: data.description,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      systems.push(system);
+      return system;
+    }),
+    updateSystem: mock(async (id: string, data: Partial<{ name: string; description?: string }>) => {
+      const system = systems.find((s) => s.id === id);
+      if (system) {
+        Object.assign(system, data);
+      }
+      return system;
+    }),
+    deleteSystem: mock(async (id: string) => {
+      const idx = systems.findIndex((s) => s.id === id);
+      if (idx >= 0) systems.splice(idx, 1);
+    }),
+    createGroup: mock(async (data: { name: string }) => {
+      const group: MockGroup = {
+        id: `grp-${groups.length + 1}`,
+        name: data.name,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+      groups.push(group);
+      return group;
+    }),
+    updateGroup: mock(async (id: string, data: Partial<{ name: string }>) => {
+      const group = groups.find((g) => g.id === id);
+      if (group) {
+        Object.assign(group, data);
+      }
+      return group;
+    }),
+    deleteGroup: mock(async (id: string) => {
+      const idx = groups.findIndex((g) => g.id === id);
+      if (idx >= 0) groups.splice(idx, 1);
+    }),
+    addSystemToGroup: mock(async (props: { groupId: string; systemId: string }) => {}),
+    removeSystemFromGroup: mock(async (props: { groupId: string; systemId: string }) => {}),
+    getGroupsForSystem: mock(async (systemId: string) => {
+      return [] as { groupId: string, systemId: string }[];
+    }),
+  };
+}
+
+// ─── Test Context ──────────────────────────────────────────────────────────
+
+const mockContext: ReconcileContext = {
+  logger: {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  },
+  resolveEntityRef: async () => undefined,
+};
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe("Catalog GitOps Kind: System", () => {
+  let mockService: ReturnType<typeof createMockEntityService>;
+
+  const systemSpecSchema = z.object({});
+  type SystemSpec = z.infer<typeof systemSpecSchema>;
+
+  function buildSystemKind(
+    svc: ReturnType<typeof createMockEntityService>,
+  ): EntityKindDefinition<SystemSpec> {
+    return {
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema: systemSpecSchema,
+      reconcile: async ({ entity, existingEntityId, context }) => {
+        const displayName = entity.metadata.title ?? entity.metadata.name;
+        const description = entity.metadata.description;
+
+        if (existingEntityId) {
+          await svc.updateSystem(existingEntityId, {
+            name: displayName,
+            description,
+          });
+          context.logger.info(`Updated system (id: ${existingEntityId})`);
+          return { entityId: existingEntityId };
+        }
+
+        const system = await svc.createSystem({
+          name: displayName,
+          description,
+        });
+        context.logger.info(`Created system (id: ${system.id})`);
+        return { entityId: system.id };
+      },
+      delete: async ({ entityId }) => {
+        if (entityId) await svc.deleteSystem(entityId);
+      },
+    };
+  }
+
+  beforeEach(() => {
+    mockService = createMockEntityService();
+  });
+
+  it("creates a new system and returns entityId", async () => {
+    const kind = buildSystemKind(mockService);
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        metadata: {
+          name: "payment-service",
+          title: "Payment Service",
+          description: "Handles payments",
+        },
+        spec: {},
+      },
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("sys-1");
+    expect(mockService.createSystem).toHaveBeenCalledTimes(1);
+    expect(mockService.systems).toHaveLength(1);
+    expect(mockService.systems[0].name).toBe("Payment Service");
+    expect(mockService.systems[0].description).toBe("Handles payments");
+  });
+
+  it("uses metadata.description for the catalog description", async () => {
+    const kind = buildSystemKind(mockService);
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        metadata: {
+          name: "api-gateway",
+          description: "Gateway description",
+        },
+        spec: {},
+      },
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("sys-1");
+    expect(mockService.systems[0].description).toBe("Gateway description");
+  });
+
+  it("falls back to metadata.name when title is missing", async () => {
+    const kind = buildSystemKind(mockService);
+
+    await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        metadata: { name: "my-service" },
+        spec: {},
+      },
+      context: mockContext,
+    });
+
+    expect(mockService.systems[0].name).toBe("my-service");
+  });
+
+  it("updates an existing system using existingEntityId", async () => {
+    const kind = buildSystemKind(mockService);
+
+    // Pre-populate a system
+    mockService.systems.push({
+      id: "sys-existing",
+      name: "Old Name",
+      description: "Old description",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "System",
+        metadata: {
+          name: "payment-service",
+          title: "Payment Service v2",
+          description: "Updated description",
+        },
+        spec: {},
+      },
+      existingEntityId: "sys-existing",
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("sys-existing");
+    expect(mockService.createSystem).not.toHaveBeenCalled();
+    expect(mockService.updateSystem).toHaveBeenCalledTimes(1);
+    expect(mockService.systems[0].name).toBe("Payment Service v2");
+    expect(mockService.systems[0].description).toBe("Updated description");
+  });
+
+  it("deletes a system by entityId", async () => {
+    const kind = buildSystemKind(mockService);
+
+    mockService.systems.push({
+      id: "sys-del",
+      name: "To Delete",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    await kind.delete!({
+      entityName: "old-service",
+      entityId: "sys-del",
+      context: mockContext,
+    });
+
+    expect(mockService.deleteSystem).toHaveBeenCalledWith("sys-del");
+    expect(mockService.systems).toHaveLength(0);
+  });
+
+  it("skips delete when entityId is missing", async () => {
+    const kind = buildSystemKind(mockService);
+
+    await kind.delete!({
+      entityName: "unknown-service",
+      context: mockContext,
+    });
+
+    expect(mockService.deleteSystem).not.toHaveBeenCalled();
+  });
+});
+
+describe("Catalog GitOps Kind Extension: System -> groups", () => {
+  let mockService: ReturnType<typeof createMockEntityService>;
+
+  beforeEach(() => {
+    mockService = createMockEntityService();
+  });
+
+  it("associates system with groups and removes stale ones", async () => {
+    // We mock getGroupsForSystem to return one existing association
+    mockService.getGroupsForSystem.mockResolvedValueOnce([
+      { groupId: "grp-stale", systemId: "sys-1" }
+    ]);
+
+    const mockExtContext: ReconcileContext = {
+      ...mockContext,
+      resolveEntityRef: mock(async ({ entityName }) => {
+        if (entityName === "new-group") return "grp-new";
+        return undefined;
+      }),
+    };
+
+    // Simulate the inline reconcile logic from index.ts
+    const reconcileExt = async ({ extensionSpec, entityId, context }: any) => {
+      if (!extensionSpec || extensionSpec.length === 0) return;
+
+      const desiredGroupIds = new Set<string>();
+
+      for (const entry of extensionSpec) {
+        const groupId = await context.resolveEntityRef({
+          kind: entry.kind,
+          entityName: entry.name,
+        });
+        if (groupId) {
+          desiredGroupIds.add(groupId);
+          await mockService.addSystemToGroup({ groupId, systemId: entityId });
+        }
+      }
+
+      const currentAssociations = await mockService.getGroupsForSystem(entityId);
+      for (const existing of currentAssociations) {
+        if (!desiredGroupIds.has(existing.groupId)) {
+          await mockService.removeSystemFromGroup({
+            groupId: existing.groupId,
+            systemId: entityId,
+          });
+        }
+      }
+    };
+
+    await reconcileExt({
+      entity: { metadata: { name: "my-system" } },
+      extensionSpec: [{ kind: "Group", name: "new-group" }],
+      entityId: "sys-1",
+      context: mockExtContext,
+    });
+
+    expect(mockService.addSystemToGroup).toHaveBeenCalledWith({
+      groupId: "grp-new",
+      systemId: "sys-1",
+    });
+
+    expect(mockService.removeSystemFromGroup).toHaveBeenCalledWith({
+      groupId: "grp-stale",
+      systemId: "sys-1",
+    });
+  });
+});
+
+describe("Catalog GitOps Kind: Group", () => {
+  let mockService: ReturnType<typeof createMockEntityService>;
+
+  const groupSpecSchema = z.object({});
+  type GroupSpec = z.infer<typeof groupSpecSchema>;
+
+  function buildGroupKind(
+    svc: ReturnType<typeof createMockEntityService>,
+  ): EntityKindDefinition<GroupSpec> {
+    return {
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Group",
+      specSchema: groupSpecSchema,
+      reconcile: async ({ entity, existingEntityId, context }) => {
+        const displayName = entity.metadata.title ?? entity.metadata.name;
+
+        if (existingEntityId) {
+          await svc.updateGroup(existingEntityId, { name: displayName });
+          context.logger.info(`Updated group (id: ${existingEntityId})`);
+          return { entityId: existingEntityId };
+        }
+
+        const group = await svc.createGroup({ name: displayName });
+        context.logger.info(`Created group (id: ${group.id})`);
+        return { entityId: group.id };
+      },
+      delete: async ({ entityId }) => {
+        if (entityId) await svc.deleteGroup(entityId);
+      },
+    };
+  }
+
+  beforeEach(() => {
+    mockService = createMockEntityService();
+  });
+
+  it("creates a new group and returns entityId", async () => {
+    const kind = buildGroupKind(mockService);
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Group",
+        metadata: {
+          name: "platform-team",
+          title: "Platform Team",
+        },
+        spec: {},
+      },
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("grp-1");
+    expect(mockService.createGroup).toHaveBeenCalledTimes(1);
+    expect(mockService.groups).toHaveLength(1);
+    expect(mockService.groups[0].name).toBe("Platform Team");
+  });
+
+  it("updates an existing group using existingEntityId", async () => {
+    const kind = buildGroupKind(mockService);
+
+    mockService.groups.push({
+      id: "grp-existing",
+      name: "Old Group",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Group",
+        metadata: {
+          name: "platform-team",
+          title: "Platform Engineering",
+        },
+        spec: {},
+      },
+      existingEntityId: "grp-existing",
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("grp-existing");
+    expect(mockService.createGroup).not.toHaveBeenCalled();
+    expect(mockService.updateGroup).toHaveBeenCalledTimes(1);
+    expect(mockService.groups[0].name).toBe("Platform Engineering");
+  });
+
+  it("deletes a group by entityId", async () => {
+    const kind = buildGroupKind(mockService);
+
+    mockService.groups.push({
+      id: "grp-del",
+      name: "To Delete",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    await kind.delete!({
+      entityName: "old-team",
+      entityId: "grp-del",
+      context: mockContext,
+    });
+
+    expect(mockService.deleteGroup).toHaveBeenCalledWith("grp-del");
+    expect(mockService.groups).toHaveLength(0);
+  });
+});

package/src/index.ts

@@ -17,6 +17,9 @@ import { authHooks } from "@checkstack/auth-backend";
 import { resolveRoute, type InferClient, extractErrorMessage} from "@checkstack/common";
 import { registerSearchProvider } from "@checkstack/command-backend";
 import { EntityService } from "./services/entity-service";
+import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
+import { CHECKSTACK_API_VERSION, entityRefSchema } from "@checkstack/gitops-common";
+import { z } from "zod";
 
 // Database schema is still needed for types in creating the router
 import * as schema from "./schema";
@@ -31,6 +34,146 @@ export default createBackendPlugin({
   register(env) {
     env.registerAccessRules(catalogAccessRules);
 
+    // ─── GitOps Entity Kind Registration ───────────────────────────────
+    // Mutable DB reference — populated during init(), consumed by reconcile closures.
+    // Safe because reconcile is only called during sync (afterPluginsReady), by which
+    // point init() has already completed.
+    let gitopsDb: SafeDatabase<typeof schema> | undefined;
+
+    const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
+
+    // Register kind: System
+    kindRegistry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema: z.object({}),
+      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;
+
+        if (existingEntityId) {
+          await entityService.updateSystem(existingEntityId, {
+            name: displayName,
+            description,
+          });
+          context.logger.info(
+            `GitOps: updated System "${displayName}" (id: ${existingEntityId})`,
+          );
+          return { entityId: existingEntityId };
+        }
+
+        const system = await entityService.createSystem({
+          name: displayName,
+          description,
+        });
+        context.logger.info(
+          `GitOps: created System "${displayName}" (id: ${system.id})`,
+        );
+        return { entityId: system.id };
+      },
+      delete: async ({ entityId, context }) => {
+        if (!gitopsDb) throw new Error("Catalog database not initialized");
+        if (!entityId) return;
+        const entityService = new EntityService(gitopsDb);
+        await entityService.deleteSystem(entityId);
+        context.logger.info(`GitOps: deleted System (id: ${entityId})`);
+      },
+    });
+
+    // Register kind extension: System -> groups
+    kindRegistry.registerKindExtension({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      namespace: "groups",
+      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 desiredGroupIds = new Set<string>();
+
+        for (const entry of extensionSpec) {
+          const groupId = await context.resolveEntityRef({
+            kind: entry.kind,
+            entityName: entry.name,
+          });
+
+          if (!groupId) {
+            throw new Error(
+              `Cannot resolve ${entry.kind} ref "${entry.name}" — ensure the entity exists`
+            );
+          }
+
+          desiredGroupIds.add(groupId);
+
+          await entityService.addSystemToGroup({
+            groupId: groupId,
+            systemId: systemEntityId,
+          });
+
+          context.logger.info(
+            `GitOps: associated System "${entity.metadata.name}" with Group "${entry.name}" (${groupId})`
+          );
+        }
+
+        // Remove stale associations not in the spec
+        const currentAssociations = await entityService.getGroupsForSystem(systemEntityId);
+        for (const existing of currentAssociations) {
+          if (!desiredGroupIds.has(existing.groupId)) {
+            await entityService.removeSystemFromGroup({
+              groupId: existing.groupId,
+              systemId: systemEntityId,
+            });
+            context.logger.info(
+              `GitOps: removed stale association ${existing.groupId} from System "${entity.metadata.name}"`
+            );
+          }
+        }
+      },
+    });
+
+    // Register kind: Group
+    kindRegistry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Group",
+      specSchema: z.object({}),
+      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;
+
+        if (existingEntityId) {
+          await entityService.updateGroup(existingEntityId, {
+            name: displayName,
+          });
+          context.logger.info(
+            `GitOps: updated Group "${displayName}" (id: ${existingEntityId})`,
+          );
+          return { entityId: existingEntityId };
+        }
+
+        const group = await entityService.createGroup({
+          name: displayName,
+        });
+        context.logger.info(
+          `GitOps: created Group "${displayName}" (id: ${group.id})`,
+        );
+        return { entityId: group.id };
+      },
+      delete: async ({ entityId, context }) => {
+        if (!gitopsDb) throw new Error("Catalog database not initialized");
+        if (!entityId) return;
+        const entityService = new EntityService(gitopsDb);
+        await entityService.deleteGroup(entityId);
+        context.logger.info(`GitOps: deleted Group (id: ${entityId})`);
+      },
+    });
+
     env.registerInit({
       schema,
       deps: {
@@ -42,6 +185,9 @@ export default createBackendPlugin({
       init: async ({ database, rpc, rpcClient, logger }) => {
         logger.debug("Initializing Catalog Backend...");
 
+        // Populate the mutable DB reference for GitOps reconcile closures
+        gitopsDb = database as SafeDatabase<typeof schema>;
+
         const typedDb = database as SafeDatabase<typeof schema>;
 
         // Get notification client for group management and sending notifications

package/src/services/entity-service.ts

@@ -144,6 +144,15 @@ export class EntityService {
     await this.database.delete(schema.groups).where(eq(schema.groups.id, id));
   }
 
+  async getGroupsForSystem(systemId: string) {
+    const associations = await this.database
+      .select()
+      .from(schema.systemsGroups)
+      .where(eq(schema.systemsGroups.systemId, systemId));
+
+    return associations;
+  }
+
   async addSystemToGroup(props: { groupId: string; systemId: string }) {
     const { groupId, systemId } = props;
     await this.database