@checkstack/catalog-backend 1.1.6 → 1.3.0

package/src/automations.ts

@@ -0,0 +1,254 @@
+/**
+ * Catalog triggers + actions registered with the Automation Platform.
+ *
+ * Triggers re-expose the existing `catalogHooks` as automation entry
+ * points (`system.created`, `system.updated`, `system.deleted`).
+ * Actions wrap the existing `EntityService` so operators can mutate
+ * systems from automation flows (e.g. "when an incident is resolved,
+ * clear the system's `incident_severity` metadata field").
+ *
+ * `system.set_maintenance` / `system.clear_maintenance` are NOT in
+ * this file — those wrap maintenance-backend RPCs and ship as part of
+ * the maintenance Phase 9 chunk. `system.health_changed` is owned by
+ * the healthcheck chunk where the aggregation data lives.
+ *
+ * Action handlers call `entityService.updateSystem` directly and then
+ * invalidate the catalog topology cache + emit the `systemUpdated`
+ * hook themselves. The router handler does the same thing for
+ * RPC-driven edits; centralising it in the service would be a
+ * separate refactor (covered elsewhere). For now, both paths emit the
+ * hook so downstream automations + cache subscribers see the change.
+ */
+import { z } from "zod";
+import { Versioned } from "@checkstack/backend-api";
+import type {
+  ActionDefinition,
+  TriggerDefinition,
+} from "@checkstack/automation-backend";
+import {
+  makeEntityDrivenTriggerSetup,
+  type EntityHandle,
+} from "@checkstack/automation-backend";
+import type { EntityService } from "./services/entity-service";
+import type { createCatalogCache } from "./cache";
+import {
+  toCatalogSystemState,
+  writeCatalogSystemEntity,
+  type CatalogSystemState,
+} from "./catalog-entity";
+
+// ─── Payload schemas — match the hook payloads exactly ─────────────────
+
+const systemCreatedPayloadSchema = z.object({
+  systemId: z.string(),
+  systemName: z.string(),
+});
+
+const systemUpdatedPayloadSchema = z.object({
+  systemId: z.string(),
+  systemName: z.string(),
+  changedFields: z.array(z.enum(["name", "description", "metadata"])),
+});
+
+const systemDeletedPayloadSchema = z.object({
+  systemId: z.string(),
+  systemName: z.string().optional(),
+});
+
+// ─── Triggers ──────────────────────────────────────────────────────────
+
+// These triggers are ENTITY-DRIVEN (§10.4): the `catalog-system` entity's
+// change deriver fires `catalog.created/.updated/.deleted` via Stage-1
+// routing, so they no longer subscribe to a hook. A no-op `setup` keeps
+// them in the editor's trigger catalog without re-introducing a hook.
+export const systemCreatedTrigger: TriggerDefinition<
+  z.infer<typeof systemCreatedPayloadSchema>
+> = {
+  id: "created",
+  displayName: "System Created",
+  description: "Fires when a new system is added to the catalog",
+  category: "Catalog",
+  icon: "Activity",
+  payloadSchema: systemCreatedPayloadSchema,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof systemCreatedPayloadSchema>
+  >(),
+  contextKey: (p) => p.systemId,
+};
+
+export const systemUpdatedTrigger: TriggerDefinition<
+  z.infer<typeof systemUpdatedPayloadSchema>
+> = {
+  id: "updated",
+  displayName: "System Updated",
+  description: "Fires when a system's name, description, or metadata changes",
+  category: "Catalog",
+  icon: "Activity",
+  payloadSchema: systemUpdatedPayloadSchema,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof systemUpdatedPayloadSchema>
+  >(),
+  contextKey: (p) => p.systemId,
+};
+
+export const systemDeletedTrigger: TriggerDefinition<
+  z.infer<typeof systemDeletedPayloadSchema>
+> = {
+  id: "deleted",
+  displayName: "System Deleted",
+  description: "Fires when a system is removed from the catalog",
+  category: "Catalog",
+  icon: "Activity",
+  payloadSchema: systemDeletedPayloadSchema,
+  setup: makeEntityDrivenTriggerSetup<
+    z.infer<typeof systemDeletedPayloadSchema>
+  >(),
+  contextKey: (p) => p.systemId,
+};
+
+export const catalogTriggers: TriggerDefinition<unknown>[] = [
+  systemCreatedTrigger as TriggerDefinition<unknown>,
+  systemUpdatedTrigger as TriggerDefinition<unknown>,
+  systemDeletedTrigger as TriggerDefinition<unknown>,
+];
+
+// ─── Action: system.update_metadata ────────────────────────────────────
+
+const systemUpdateMetadataConfigSchema = z.object({
+  systemId: z.string().min(1).describe("Target system id"),
+  /**
+   * Strategy for combining `metadata` with the system's existing
+   * metadata object:
+   *   - `merge` (default): shallow-merge — preserves untouched keys.
+   *   - `replace`: overwrite the entire metadata object.
+   */
+  strategy: z.enum(["merge", "replace"]).default("merge"),
+  metadata: z
+    .record(z.string(), z.unknown())
+    .describe("New metadata key-value pairs"),
+});
+
+export type SystemUpdateMetadataConfig = z.infer<
+  typeof systemUpdateMetadataConfigSchema
+>;
+
+const systemRecordArtifactSchema = z.object({
+  systemId: z.string(),
+  systemName: z.string(),
+  metadata: z.record(z.string(), z.unknown()),
+});
+
+export type SystemRecordArtifact = z.infer<typeof systemRecordArtifactSchema>;
+
+export const systemRecordArtifactType = {
+  id: "system_record",
+  displayName: "System Record",
+  description: "Snapshot of a system after an automation-driven change",
+  schema: systemRecordArtifactSchema,
+} as const;
+
+export interface CatalogActionDeps {
+  entityService: EntityService;
+  cache: ReturnType<typeof createCatalogCache>;
+  /**
+   * Resolver for the reactive `catalog-system` entity (§10.4). The
+   * `update_metadata` action mirrors its edit here; the entity's change
+   * deriver fires the `catalog.updated` trigger event downstream (the old
+   * `systemUpdated` hook emission was removed).
+   */
+  getSystemEntity?: () => EntityHandle<CatalogSystemState> | undefined;
+}
+
+export function createCatalogActions(
+  deps: CatalogActionDeps,
+): ActionDefinition<unknown, unknown>[] {
+  const updateMetadata: ActionDefinition<
+    SystemUpdateMetadataConfig,
+    SystemRecordArtifact
+  > = {
+    id: "update_metadata",
+    displayName: "Update System Metadata",
+    description:
+      "Set or merge metadata keys on a system. Useful for cross-plugin state (e.g. flagging a system from an automation).",
+    category: "Catalog",
+    icon: "FilePenLine",
+    config: new Versioned({
+      version: 1,
+      schema: systemUpdateMetadataConfigSchema,
+    }),
+    produces: "catalog.system_record",
+    execute: async ({ config, logger, runId }) => {
+      const existing = await deps.entityService.getSystem(config.systemId);
+      if (!existing) {
+        return {
+          success: false,
+          error: `System not found: ${config.systemId}`,
+        };
+      }
+
+      const existingMetadata =
+        (existing.metadata as Record<string, unknown> | null) ?? {};
+      const nextMetadata =
+        config.strategy === "replace"
+          ? config.metadata
+          : { ...existingMetadata, ...config.metadata };
+
+      // Drive the update through the reactive `catalog-system` entity (§10.4);
+      // the REAL `updateSystem` runs INSIDE `apply`, so `prev` is snapshotted
+      // before the write and the deriver fires `catalog.updated`. If the row
+      // was race-deleted mid-update, `apply` falls back to the pre-write
+      // state so the diff is a no-op (no spurious `catalog.updated`), and the
+      // failure is surfaced from the captured `updated`.
+      // Capture the post-write row in a holder so TS control-flow tracks the
+      // assignment made inside the async `apply` closure (a plain `let`
+      // mutated in a closure is invisible to CFA and would narrow to `never`).
+      const captured: {
+        row: Awaited<ReturnType<typeof deps.entityService.updateSystem>> | null;
+      } = { row: null };
+      await writeCatalogSystemEntity({
+        handle: deps.getSystemEntity?.(),
+        systemId: config.systemId,
+        // Run-secret masking choke point: this action resolves config
+        // (including `metadata` values) against the run scope, which can
+        // contain run-resolved secrets. Passing `runId` masks any such secret
+        // in the `entity_transitions` rows + the cluster-wide `ENTITY_CHANGED`.
+        opts: { runId },
+        apply: async () => {
+          const row = await deps.entityService.updateSystem(config.systemId, {
+            metadata: nextMetadata,
+          });
+          captured.row = row ?? null;
+          return toCatalogSystemState({
+            name: row?.name ?? existing.name,
+            description: row?.description ?? existing.description,
+            metadata: row ? nextMetadata : existingMetadata,
+          });
+        },
+      });
+      const updated = captured.row;
+      if (!updated) {
+        return {
+          success: false,
+          error: `System ${config.systemId} disappeared mid-update`,
+        };
+      }
+
+      await deps.cache.invalidateTopology();
+
+      logger.info(
+        `Automation updated metadata on system ${updated.id} (${config.strategy})`,
+      );
+      return {
+        success: true,
+        externalId: updated.id,
+        artifact: {
+          systemId: updated.id,
+          systemName: updated.name,
+          metadata: nextMetadata,
+        },
+      };
+    },
+  };
+
+  return [updateMetadata as ActionDefinition<unknown, unknown>];
+}

package/src/catalog-entity.test.ts

@@ -0,0 +1,308 @@
+import { describe, it, expect } from "bun:test";
+import type {
+  EntityChanged,
+  EntityHandle,
+} from "@checkstack/automation-backend";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+
+import {
+  CATALOG_GROUP_ENTITY_KIND,
+  CATALOG_GROUP_TRIGGER_EVENTS,
+  CATALOG_SYSTEM_ENTITY_KIND,
+  CATALOG_SYSTEM_TRIGGER_EVENTS,
+  catalogSystemChangeToPayload,
+  createCatalogGroupEntityRead,
+  createCatalogSystemEntityRead,
+  deriveCatalogGroupTriggerEvents,
+  deriveCatalogSystemTriggerEvents,
+  removeCatalogEntity,
+  toCatalogGroupState,
+  toCatalogSystemState,
+  writeCatalogGroupEntity,
+  writeCatalogSystemEntity,
+  type CatalogGroupState,
+  type CatalogSystemState,
+} from "./catalog-entity";
+import {
+  systemCreatedTrigger,
+  systemDeletedTrigger,
+  systemUpdatedTrigger,
+} from "./automations";
+import type { EntityService } from "./services/entity-service";
+
+function change(overrides: Partial<EntityChanged> = {}): EntityChanged {
+  return {
+    kind: CATALOG_SYSTEM_ENTITY_KIND,
+    id: "sys-1",
+    prev: { name: "old", description: null, metadata: {} },
+    next: { name: "new", description: null, metadata: {} },
+    delta: { name: "new" },
+    changedFields: ["name"],
+    actor: SYSTEM_ACTOR,
+    occurredAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe("CATALOG_SYSTEM_TRIGGER_EVENTS (must equal the trigger qualifiedIds)", () => {
+  it("emits the registered system trigger qualifiedIds, not the dotted hook ids", () => {
+    // The catalog system triggers have ids `created`/`updated`/`deleted`
+    // (pluginId `catalog`), so the deriver MUST emit `catalog.created` etc.,
+    // NOT the dotted hook ids `catalog.system.created`.
+    expect(CATALOG_SYSTEM_TRIGGER_EVENTS.created).toBe("catalog.created");
+    expect(CATALOG_SYSTEM_TRIGGER_EVENTS.updated).toBe("catalog.updated");
+    expect(CATALOG_SYSTEM_TRIGGER_EVENTS.deleted).toBe("catalog.deleted");
+  });
+});
+
+describe("deriveCatalogSystemTriggerEvents", () => {
+  it("maps a create (prev === null) to system.created", () => {
+    expect(
+      deriveCatalogSystemTriggerEvents(
+        change({ prev: null, next: { name: "n", description: null, metadata: {} } }),
+      ),
+    ).toEqual([CATALOG_SYSTEM_TRIGGER_EVENTS.created]);
+  });
+  it("maps a tombstone (next === null) to system.deleted", () => {
+    expect(
+      deriveCatalogSystemTriggerEvents(change({ next: null })),
+    ).toEqual([CATALOG_SYSTEM_TRIGGER_EVENTS.deleted]);
+  });
+  it("maps a field update to system.updated", () => {
+    expect(deriveCatalogSystemTriggerEvents(change())).toEqual([
+      CATALOG_SYSTEM_TRIGGER_EVENTS.updated,
+    ]);
+  });
+});
+
+describe("catalogSystemChangeToPayload — payloadSchema parity", () => {
+  it("a create payload validates against the created trigger's payloadSchema", () => {
+    const payload = catalogSystemChangeToPayload(
+      change({
+        prev: null,
+        next: { name: "new", description: null, metadata: {} },
+        delta: { name: "new" },
+        changedFields: ["name", "description", "metadata"],
+      }),
+    );
+    const parsed = systemCreatedTrigger.payloadSchema.parse(payload);
+    expect(parsed.systemId).toBe("sys-1");
+    expect(parsed.systemName).toBe("new");
+  });
+
+  it("an update payload validates against the updated trigger's payloadSchema with changedFields", () => {
+    const payload = catalogSystemChangeToPayload(
+      change({ changedFields: ["name", "metadata"] }),
+    );
+    const parsed = systemUpdatedTrigger.payloadSchema.parse(payload);
+    expect(parsed.systemId).toBe("sys-1");
+    expect(parsed.systemName).toBe("new");
+    expect(parsed.changedFields).toEqual(["name", "metadata"]);
+  });
+
+  it("a delete payload validates against the deleted trigger's payloadSchema (systemName omitted on tombstone)", () => {
+    const payload = catalogSystemChangeToPayload(change({ next: null }));
+    const parsed = systemDeletedTrigger.payloadSchema.parse(payload);
+    expect(parsed.systemId).toBe("sys-1");
+    expect(parsed.systemName).toBeUndefined();
+  });
+
+  it("drops non-enum changedFields (only name/description/metadata survive)", () => {
+    const payload = catalogSystemChangeToPayload(
+      change({ changedFields: ["name", "ownerId", "metadata"] }),
+    );
+    const parsed = systemUpdatedTrigger.payloadSchema.parse(payload);
+    expect(parsed.changedFields).toEqual(["name", "metadata"]);
+  });
+});
+
+describe("deriveCatalogGroupTriggerEvents", () => {
+  it("maps a create to group.created", () => {
+    expect(
+      deriveCatalogGroupTriggerEvents(
+        change({
+          kind: CATALOG_GROUP_ENTITY_KIND,
+          prev: null,
+          next: { name: "g", metadata: {} },
+        }),
+      ),
+    ).toEqual([CATALOG_GROUP_TRIGGER_EVENTS.created]);
+  });
+  it("maps a tombstone to group.deleted", () => {
+    expect(
+      deriveCatalogGroupTriggerEvents(
+        change({ kind: CATALOG_GROUP_ENTITY_KIND, next: null }),
+      ),
+    ).toEqual([CATALOG_GROUP_TRIGGER_EVENTS.deleted]);
+  });
+  it("fires nothing on a group update (no group.updated hook)", () => {
+    expect(
+      deriveCatalogGroupTriggerEvents(
+        change({
+          kind: CATALOG_GROUP_ENTITY_KIND,
+          prev: { name: "a", metadata: {} },
+          next: { name: "b", metadata: {} },
+        }),
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("toCatalogSystemState / toCatalogGroupState", () => {
+  it("projects a system, normalising null description + metadata", () => {
+    expect(
+      toCatalogSystemState({
+        name: "API",
+        description: undefined,
+        metadata: undefined,
+      }),
+    ).toEqual({ name: "API", description: null, metadata: {} });
+  });
+
+  it("projects a group, normalising null metadata", () => {
+    expect(
+      toCatalogGroupState({ name: "Team A", metadata: null }),
+    ).toEqual({ name: "Team A", metadata: {} });
+  });
+});
+
+describe("createCatalogSystemEntityRead", () => {
+  it("routes the batched read straight to the service (plugin-backed)", async () => {
+    const seen: ReadonlyArray<string>[] = [];
+    const service = {
+      async getManySystemEntityStates(ids: ReadonlyArray<string>) {
+        seen.push(ids);
+        return {
+          "sys-1": { name: "API", description: null, metadata: { tier: "1" } },
+        };
+      },
+    } as unknown as EntityService;
+    const read = createCatalogSystemEntityRead(service);
+    const out = await read(["sys-1", "sys-2"]);
+    expect(seen).toEqual([["sys-1", "sys-2"]]);
+    expect(out["sys-1"]).toEqual({
+      name: "API",
+      description: null,
+      metadata: { tier: "1" },
+    });
+  });
+});
+
+describe("createCatalogGroupEntityRead", () => {
+  it("routes the batched read straight to the service (plugin-backed)", async () => {
+    const seen: ReadonlyArray<string>[] = [];
+    const service = {
+      async getManyGroupEntityStates(ids: ReadonlyArray<string>) {
+        seen.push(ids);
+        return { "g-1": { name: "Team A", metadata: {} } };
+      },
+    } as unknown as EntityService;
+    const read = createCatalogGroupEntityRead(service);
+    const out = await read(["g-1"]);
+    expect(seen).toEqual([["g-1"]]);
+    expect(out["g-1"]).toEqual({ name: "Team A", metadata: {} });
+  });
+});
+
+describe("writeCatalogSystemEntity", () => {
+  it("drives the write through handle.mutate keyed by system id", async () => {
+    const calls: Array<{ id: string; next: CatalogSystemState }> = [];
+    const handle = {
+      kind: CATALOG_SYSTEM_ENTITY_KIND,
+      async mutate(input: {
+        id: string;
+        apply: () => Promise<CatalogSystemState>;
+      }) {
+        const next = await input.apply();
+        calls.push({ id: input.id, next });
+        return next;
+      },
+    } as unknown as EntityHandle<CatalogSystemState>;
+    let applied = false;
+    await writeCatalogSystemEntity({
+      handle,
+      systemId: "sys-9",
+      apply: async () => {
+        applied = true;
+        return { name: "API", description: null, metadata: {} };
+      },
+    });
+    expect(applied).toBe(true);
+    expect(calls).toEqual([
+      { id: "sys-9", next: { name: "API", description: null, metadata: {} } },
+    ]);
+  });
+
+  it("still runs the plugin write when no handle is wired", async () => {
+    let applied = false;
+    await writeCatalogSystemEntity({
+      handle: undefined,
+      systemId: "sys-9",
+      apply: async () => {
+        applied = true;
+        return { name: "API", description: null, metadata: {} };
+      },
+    });
+    expect(applied).toBe(true);
+  });
+});
+
+describe("writeCatalogGroupEntity", () => {
+  it("drives the write through handle.mutate keyed by group id", async () => {
+    const calls: Array<{ id: string; next: CatalogGroupState }> = [];
+    const handle = {
+      kind: CATALOG_GROUP_ENTITY_KIND,
+      async mutate(input: {
+        id: string;
+        apply: () => Promise<CatalogGroupState>;
+      }) {
+        const next = await input.apply();
+        calls.push({ id: input.id, next });
+        return next;
+      },
+    } as unknown as EntityHandle<CatalogGroupState>;
+    await writeCatalogGroupEntity({
+      handle,
+      groupId: "g-1",
+      apply: async () => ({ name: "Team A", metadata: { tier: "1" } }),
+    });
+    expect(calls).toEqual([
+      { id: "g-1", next: { name: "Team A", metadata: { tier: "1" } } },
+    ]);
+  });
+});
+
+describe("removeCatalogEntity", () => {
+  it("tombstones via handle.remove({ apply })", async () => {
+    const removed: string[] = [];
+    let deleted = false;
+    const handle = {
+      kind: CATALOG_SYSTEM_ENTITY_KIND,
+      async remove(input: { id: string; apply: () => Promise<void> }) {
+        await input.apply();
+        removed.push(input.id);
+      },
+    } as unknown as EntityHandle<Record<string, unknown>>;
+    await removeCatalogEntity({
+      handle,
+      id: "sys-9",
+      apply: async () => {
+        deleted = true;
+      },
+    });
+    expect(deleted).toBe(true);
+    expect(removed).toEqual(["sys-9"]);
+  });
+
+  it("still runs the delete when no handle is wired", async () => {
+    let deleted = false;
+    await removeCatalogEntity({
+      handle: undefined,
+      id: "x",
+      apply: async () => {
+        deleted = true;
+      },
+    });
+    expect(deleted).toBe(true);
+  });
+});