@checkstack/catalog-backend 1.1.5 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @checkstack/catalog-backend
 
+## 1.2.0
+
+### Minor Changes
+
+- 41c77f4: feat(catalog): system triggers + update_metadata action for the Automation Platform
+
+  Ships the catalog chunk of Phase 9:
+
+  - Triggers: `catalog.created`, `catalog.updated`, `catalog.deleted`
+    — named consistently with the other plugin lifecycle triggers
+    (incident.created, dependency.created, maintenance.created, …).
+    Each carries `contextKey: (p) => p.systemId` so `wait_for_trigger`
+    can resume the right run.
+  - Action: `catalog.update_metadata` — sets or merges metadata on a
+    system (`strategy: "merge" | "replace"`). Default is `merge` so
+    untouched keys survive. Returns a `catalog.system_record` artifact
+    (`systemId`, `systemName`, `metadata`).
+
+  New hook: `catalogHooks.systemUpdated` (`{ systemId, systemName,
+changedFields }`). Emitted from both the `updateSystem` RPC handler
+  and the `update_metadata` automation action so downstream automations
+  and caches see both code paths. Emission is skipped when no tracked
+  field changed (no-op saves don't spam subscribers).
+
+  The `system.health_changed`, `system.set_maintenance`, and
+  `system.clear_maintenance` items in the original Phase 9 plan move to
+  the **healthcheck** and **maintenance** chunks respectively, where the
+  underlying data and RPCs live.
+
+### Patch Changes
+
+- Updated dependencies [e2d6f25]
+- Updated dependencies [41c77f4]
+- Updated dependencies [e1a2077]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [6d52276]
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/automation-backend@0.2.0
+  - @checkstack/common@0.12.0
+  - @checkstack/backend-api@0.18.0
+  - @checkstack/catalog-common@2.2.3
+  - @checkstack/auth-backend@0.4.31
+  - @checkstack/auth-common@0.7.2
+  - @checkstack/command-backend@0.1.31
+  - @checkstack/gitops-backend@0.3.7
+  - @checkstack/gitops-common@0.4.2
+  - @checkstack/notification-common@1.2.1
+  - @checkstack/cache-api@0.3.6
+  - @checkstack/cache-utils@0.2.11
+
+## 1.1.6
+
+### Patch Changes
+
+- @checkstack/backend-api@0.17.1
+- @checkstack/auth-backend@0.4.30
+- @checkstack/cache-api@0.3.5
+- @checkstack/command-backend@0.1.30
+- @checkstack/gitops-backend@0.3.6
+- @checkstack/cache-utils@0.2.10
+
 ## 1.1.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/catalog-backend",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -11,29 +11,32 @@
     "typecheck": "tsgo -b",
     "generate": "drizzle-kit generate",
     "lint": "bun run lint:code",
-    "lint:code": "eslint . --max-warnings 0"
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.16.0",
-    "@checkstack/cache-api": "0.3.3",
-    "@checkstack/cache-utils": "0.2.8",
-    "@checkstack/auth-common": "0.7.0",
-    "@checkstack/catalog-common": "2.2.1",
-    "@checkstack/command-backend": "0.1.28",
-    "@checkstack/auth-backend": "0.4.28",
-    "@checkstack/gitops-backend": "0.3.4",
-    "@checkstack/gitops-common": "0.4.0",
-    "@checkstack/notification-common": "1.1.1",
+    "@checkstack/backend-api": "0.17.1",
+    "@checkstack/automation-backend": "0.1.0",
+    "@checkstack/cache-api": "0.3.5",
+    "@checkstack/cache-utils": "0.2.10",
+    "@checkstack/auth-common": "0.7.1",
+    "@checkstack/catalog-common": "2.2.2",
+    "@checkstack/command-backend": "0.1.30",
+    "@checkstack/auth-backend": "0.4.30",
+    "@checkstack/gitops-backend": "0.3.6",
+    "@checkstack/gitops-common": "0.4.1",
+    "@checkstack/notification-common": "1.2.0",
     "@orpc/server": "^1.13.2",
     "drizzle-orm": "^0.45.0",
     "hono": "^4.12.14",
     "uuid": "^14.0.0",
     "zod": "^4.2.1",
-    "@checkstack/common": "0.10.0"
+    "@checkstack/common": "0.11.0"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/scripts": "0.3.2",
+    "@checkstack/scripts": "0.3.3",
+    "@checkstack/test-utils-backend": "0.1.30",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.3.5",
     "@types/node": "^20.0.0",

package/src/automations.test.ts

@@ -0,0 +1,369 @@
+/**
+ * Behaviour tests for the catalog automation triggers + actions.
+ *
+ * The triggers are dataclasses (id, payloadSchema, hook, contextKey),
+ * so we lock down their payload validation + contextKey extraction.
+ * The `update_metadata` action carries the real behaviour: shallow
+ * merge vs. replace, cache invalidation, hook emission, the
+ * "missing system" failure path, and the "race-deleted mid-update"
+ * failure path.
+ */
+import { describe, expect, it, mock } from "bun:test";
+import type { Logger } from "@checkstack/backend-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+import {
+  catalogTriggers,
+  createCatalogActions,
+  systemCreatedTrigger,
+  systemDeletedTrigger,
+  systemRecordArtifactType,
+  systemUpdatedTrigger,
+} from "./automations";
+import type { EntityService } from "./services/entity-service";
+import type { createCatalogCache } from "./cache";
+import { catalogHooks } from "./hooks";
+
+const logger = createMockLogger() as Logger;
+
+const ctxBase = {
+  runId: "run-1",
+  automationId: "auto-1",
+  contextKey: null,
+  logger,
+  getService: async <T,>(): Promise<T> => {
+    throw new Error("not used");
+  },
+};
+
+// ─── Triggers ──────────────────────────────────────────────────────────
+
+describe("catalog triggers", () => {
+  it("exposes three triggers in a stable order", () => {
+    expect(catalogTriggers).toHaveLength(3);
+    expect(catalogTriggers[0]).toBe(
+      systemCreatedTrigger as (typeof catalogTriggers)[number],
+    );
+    expect(catalogTriggers[1]).toBe(
+      systemUpdatedTrigger as (typeof catalogTriggers)[number],
+    );
+    expect(catalogTriggers[2]).toBe(
+      systemDeletedTrigger as (typeof catalogTriggers)[number],
+    );
+  });
+
+  it("validates the systemCreated payload + extracts systemId as contextKey", () => {
+    const payload = { systemId: "sys-1", systemName: "API" };
+    const parsed = systemCreatedTrigger.payloadSchema.safeParse(payload);
+    expect(parsed.success).toBe(true);
+    expect(systemCreatedTrigger.contextKey?.(payload)).toBe("sys-1");
+    expect(systemCreatedTrigger.hook).toBe(catalogHooks.systemCreated);
+  });
+
+  it("requires changedFields on the systemUpdated payload", () => {
+    const ok = systemUpdatedTrigger.payloadSchema.safeParse({
+      systemId: "sys-1",
+      systemName: "API",
+      changedFields: ["metadata"],
+    });
+    expect(ok.success).toBe(true);
+
+    const bad = systemUpdatedTrigger.payloadSchema.safeParse({
+      systemId: "sys-1",
+      systemName: "API",
+    });
+    expect(bad.success).toBe(false);
+
+    const badEnum = systemUpdatedTrigger.payloadSchema.safeParse({
+      systemId: "sys-1",
+      systemName: "API",
+      changedFields: ["unknown_field"],
+    });
+    expect(badEnum.success).toBe(false);
+  });
+
+  it("accepts an optional systemName on the systemDeleted payload", () => {
+    const withName = systemDeletedTrigger.payloadSchema.safeParse({
+      systemId: "sys-1",
+      systemName: "API",
+    });
+    const withoutName = systemDeletedTrigger.payloadSchema.safeParse({
+      systemId: "sys-1",
+    });
+    expect(withName.success).toBe(true);
+    expect(withoutName.success).toBe(true);
+  });
+});
+
+// ─── Artifact type ─────────────────────────────────────────────────────
+
+describe("systemRecordArtifactType", () => {
+  it("validates the canonical artifact shape", () => {
+    const ok = systemRecordArtifactType.schema.safeParse({
+      systemId: "sys-1",
+      systemName: "API",
+      metadata: { tier: "gold" },
+    });
+    expect(ok.success).toBe(true);
+  });
+
+  it("rejects when metadata is missing", () => {
+    const bad = systemRecordArtifactType.schema.safeParse({
+      systemId: "sys-1",
+      systemName: "API",
+    });
+    expect(bad.success).toBe(false);
+  });
+});
+
+// ─── Action: system.update_metadata ────────────────────────────────────
+
+interface FakeSystemRow {
+  id: string;
+  name: string;
+  description?: string | null;
+  metadata: Record<string, unknown> | null;
+}
+
+interface ActionFixture {
+  service: EntityService;
+  cache: ReturnType<typeof createCatalogCache>;
+  emitHookMock: ReturnType<typeof mock>;
+  updateSystemMock: ReturnType<typeof mock>;
+  getSystemMock: ReturnType<typeof mock>;
+  invalidateTopologyMock: ReturnType<typeof mock>;
+}
+
+function makeFixture(args: {
+  initialRow: FakeSystemRow | undefined;
+  /**
+   * If set, updateSystem returns this value instead of the merged
+   * row. Use `{ value: undefined }` to simulate a race-deleted row.
+   * Omit to get the default "merge + return updated row" behaviour.
+   */
+  updateResult?: { value: FakeSystemRow | undefined };
+}): ActionFixture {
+  let row = args.initialRow ? { ...args.initialRow } : undefined;
+  const getSystemMock = mock(async (_id: string) => row);
+  const updateSystemMock = mock(
+    async (id: string, data: { metadata?: Record<string, unknown> }) => {
+      if (args.updateResult) return args.updateResult.value;
+      if (row) {
+        row = { ...row, metadata: data.metadata ?? row.metadata };
+        return row;
+      }
+      return undefined;
+    },
+  );
+  const service = {
+    getSystem: getSystemMock,
+    updateSystem: updateSystemMock,
+  } as unknown as EntityService;
+
+  const invalidateTopologyMock = mock(async () => {});
+  const cache = {
+    invalidateTopology: invalidateTopologyMock,
+    // Other cache methods aren't exercised by the action; cast to the
+    // full shape so the factory's deps typecheck.
+    invalidateContacts: mock(async () => {}),
+  } as unknown as ReturnType<typeof createCatalogCache>;
+
+  const emitHookMock = mock(async () => {});
+
+  return {
+    service,
+    cache,
+    emitHookMock,
+    updateSystemMock,
+    getSystemMock,
+    invalidateTopologyMock,
+  };
+}
+
+describe("catalog.system.update_metadata", () => {
+  it("shallow-merges by default and preserves untouched keys", async () => {
+    const fx = makeFixture({
+      initialRow: {
+        id: "sys-1",
+        name: "API",
+        metadata: { tier: "gold", region: "eu-central-1" },
+      },
+    });
+    const [action] = createCatalogActions({
+      entityService: fx.service,
+      cache: fx.cache,
+      emitHook: fx.emitHookMock as never,
+    });
+
+    const result = await action!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        systemId: "sys-1",
+        strategy: "merge",
+        metadata: { tier: "platinum", owner: "platform" },
+      } as never,
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    const artifact = result.artifact as {
+      metadata: Record<string, unknown>;
+    };
+    expect(artifact.metadata).toEqual({
+      tier: "platinum",
+      region: "eu-central-1",
+      owner: "platform",
+    });
+
+    // Service was called with the merged metadata, not the partial config.
+    expect(fx.updateSystemMock).toHaveBeenCalledTimes(1);
+    const updateCall = fx.updateSystemMock.mock.calls[0]!;
+    expect(updateCall[0]).toBe("sys-1");
+    expect((updateCall[1] as { metadata: Record<string, unknown> }).metadata)
+      .toEqual({
+        tier: "platinum",
+        region: "eu-central-1",
+        owner: "platform",
+      });
+
+    expect(fx.invalidateTopologyMock).toHaveBeenCalledTimes(1);
+    expect(fx.emitHookMock).toHaveBeenCalledTimes(1);
+    const emitCall = fx.emitHookMock.mock.calls[0]!;
+    expect(emitCall[0]).toBe(catalogHooks.systemUpdated);
+    expect(emitCall[1]).toEqual({
+      systemId: "sys-1",
+      systemName: "API",
+      changedFields: ["metadata"],
+    });
+  });
+
+  it("replaces the whole metadata object when strategy=replace", async () => {
+    const fx = makeFixture({
+      initialRow: {
+        id: "sys-1",
+        name: "API",
+        metadata: { tier: "gold", region: "eu-central-1" },
+      },
+    });
+    const [action] = createCatalogActions({
+      entityService: fx.service,
+      cache: fx.cache,
+      emitHook: fx.emitHookMock as never,
+    });
+
+    const result = await action!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        systemId: "sys-1",
+        strategy: "replace",
+        metadata: { owner: "platform" },
+      } as never,
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    const artifact = result.artifact as {
+      metadata: Record<string, unknown>;
+    };
+    expect(artifact.metadata).toEqual({ owner: "platform" });
+
+    const updateCall = fx.updateSystemMock.mock.calls[0]!;
+    expect((updateCall[1] as { metadata: Record<string, unknown> }).metadata)
+      .toEqual({ owner: "platform" });
+  });
+
+  it("treats a null existing metadata as an empty object when merging", async () => {
+    const fx = makeFixture({
+      initialRow: {
+        id: "sys-1",
+        name: "API",
+        metadata: null,
+      },
+    });
+    const [action] = createCatalogActions({
+      entityService: fx.service,
+      cache: fx.cache,
+      emitHook: fx.emitHookMock as never,
+    });
+
+    const result = await action!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        systemId: "sys-1",
+        strategy: "merge",
+        metadata: { tier: "gold" },
+      } as never,
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    const artifact = result.artifact as {
+      metadata: Record<string, unknown>;
+    };
+    expect(artifact.metadata).toEqual({ tier: "gold" });
+  });
+
+  it("returns failure when the target system does not exist", async () => {
+    const fx = makeFixture({ initialRow: undefined });
+    const [action] = createCatalogActions({
+      entityService: fx.service,
+      cache: fx.cache,
+      emitHook: fx.emitHookMock as never,
+    });
+
+    const result = await action!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        systemId: "missing",
+        strategy: "merge",
+        metadata: { tier: "gold" },
+      } as never,
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/System not found/);
+    expect(fx.updateSystemMock).not.toHaveBeenCalled();
+    expect(fx.invalidateTopologyMock).not.toHaveBeenCalled();
+    expect(fx.emitHookMock).not.toHaveBeenCalled();
+  });
+
+  it("returns failure if updateSystem returns undefined (race-deleted mid-update)", async () => {
+    const fx = makeFixture({
+      initialRow: {
+        id: "sys-1",
+        name: "API",
+        metadata: {},
+      },
+      // Simulate a race: getSystem found the row, but updateSystem
+      // returned `undefined` (the row was deleted between the two
+      // queries).
+      updateResult: { value: undefined },
+    });
+    const [action] = createCatalogActions({
+      entityService: fx.service,
+      cache: fx.cache,
+      emitHook: fx.emitHookMock as never,
+    });
+
+    const result = await action!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        systemId: "sys-1",
+        strategy: "merge",
+        metadata: { tier: "gold" },
+      } as never,
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/disappeared mid-update/);
+    expect(fx.invalidateTopologyMock).not.toHaveBeenCalled();
+    expect(fx.emitHookMock).not.toHaveBeenCalled();
+  });
+});

package/src/automations.ts

@@ -0,0 +1,211 @@
+/**
+ * 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, type Hook } from "@checkstack/backend-api";
+import type {
+  ActionDefinition,
+  TriggerDefinition,
+} from "@checkstack/automation-backend";
+
+import { catalogHooks } from "./hooks";
+import type { EntityService } from "./services/entity-service";
+import type { createCatalogCache } from "./cache";
+
+// ─── 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 ──────────────────────────────────────────────────────────
+
+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,
+  hook: catalogHooks.systemCreated,
+  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,
+  hook: catalogHooks.systemUpdated,
+  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,
+  hook: catalogHooks.systemDeleted,
+  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>;
+  /**
+   * `emitHook` bound during `afterPluginsReady`. Required so the
+   * action fires `systemUpdated` downstream — without it, other
+   * automations waiting on the trigger wouldn't see the change.
+   */
+  emitHook: <T>(hook: Hook<T>, payload: T) => Promise<void>;
+}
+
+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 }) => {
+      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 };
+
+      const updated = await deps.entityService.updateSystem(config.systemId, {
+        metadata: nextMetadata,
+      });
+      if (!updated) {
+        return {
+          success: false,
+          error: `System ${config.systemId} disappeared mid-update`,
+        };
+      }
+
+      await deps.cache.invalidateTopology();
+      await deps.emitHook(catalogHooks.systemUpdated, {
+        systemId: updated.id,
+        systemName: updated.name,
+        changedFields: ["metadata"],
+      });
+
+      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/hooks.ts

@@ -14,6 +14,20 @@ export const catalogHooks = {
     systemName: string;
   }>("catalog.system.created"),
 
+  /**
+   * Emitted when a system's name, description, or metadata changes.
+   *
+   * `changedFields` lists the keys the caller actually set on the
+   * update (excluding `id`), so subscribers can route on field-level
+   * changes (e.g. "only react to metadata edits") without diffing the
+   * full record.
+   */
+  systemUpdated: createHook<{
+    systemId: string;
+    systemName: string;
+    changedFields: Array<"name" | "description" | "metadata">;
+  }>("catalog.system.updated"),
+
   /**
    * Emitted when a system is deleted.
    * Plugins can subscribe (work-queue mode) to clean up related data.

package/src/index.ts

@@ -3,6 +3,11 @@ import {
   type SafeDatabase,
 } from "@checkstack/backend-api";
 import { coreServices } from "@checkstack/backend-api";
+import {
+  automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
+  automationTriggerExtensionPoint,
+} from "@checkstack/automation-backend";
 import {
   catalogAccessRules,
   catalogAccess,
@@ -27,6 +32,12 @@ import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
 import { CHECKSTACK_API_VERSION, entityRefSchema, GitOpsApi } from "@checkstack/gitops-common";
 import { z } from "zod";
 
+import {
+  catalogTriggers,
+  createCatalogActions,
+  systemRecordArtifactType,
+} from "./automations";
+
 // Database schema is still needed for types in creating the router
 import * as schema from "./schema";
 
@@ -40,6 +51,21 @@ export default createBackendPlugin({
   register(env) {
     env.registerAccessRules(catalogAccessRules);
 
+    // ─── Automation Platform: triggers + artifact type ─────────────────
+    // Buffered behind the extension point until automation-backend's
+    // register() runs. The action factory is wired in afterPluginsReady
+    // below — that's where `emitHook` becomes available, which the
+    // `update_metadata` action needs in order to fire `systemUpdated`.
+    const automationTriggers = env.getExtensionPoint(
+      automationTriggerExtensionPoint,
+    );
+    for (const trigger of catalogTriggers) {
+      automationTriggers.registerTrigger(trigger, pluginMetadata);
+    }
+    env
+      .getExtensionPoint(automationArtifactTypeExtensionPoint)
+      .registerArtifactType(systemRecordArtifactType, pluginMetadata);
+
     // ─── 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
@@ -271,7 +297,14 @@ export default createBackendPlugin({
         logger.debug("✅ Catalog Backend initialized.");
       },
       // Phase 3: Safe to make RPC calls after all plugins are ready
-      afterPluginsReady: async ({ database, rpcClient, logger, onHook }) => {
+      afterPluginsReady: async ({
+        database,
+        rpcClient,
+        logger,
+        onHook,
+        emitHook,
+        cacheManager,
+      }) => {
         const typedDb = database as SafeDatabase<typeof schema>;
         const notificationClient = rpcClient.forPlugin(NotificationApi);
 
@@ -282,13 +315,29 @@ export default createBackendPlugin({
         // provisioning happens server-side from this signal.
         await bootstrapNotificationTargets(typedDb, notificationClient, logger);
 
+        // Register automation actions now that `emitHook` is available
+        // — the `update_metadata` action needs to fire `systemUpdated`
+        // downstream so other automations + caches react to the change.
+        const automationActions = env.getExtensionPoint(
+          automationActionExtensionPoint,
+        );
+        const entityService = new EntityService(typedDb);
+        const cache = createCatalogCache({ cacheManager, logger });
+        for (const action of createCatalogActions({
+          entityService,
+          cache,
+          emitHook,
+        })) {
+          automationActions.registerAction(action, pluginMetadata);
+        }
+
         // Subscribe to user deletion to clean up user contacts
         onHook(
           authHooks.userDeleted,
           async ({ userId }) => {
             logger.debug(`Cleaning up contacts for deleted user: ${userId}`);
-            const entityService = new EntityService(typedDb);
-            await entityService.deleteContactsByUserId(userId);
+            const userCleanupService = new EntityService(typedDb);
+            await userCleanupService.deleteContactsByUserId(userId);
             logger.debug(`Cleaned up contacts for user: ${userId}`);
           },
           { mode: "work-queue", workerGroup: "user-cleanup" },

package/src/router.ts

@@ -243,7 +243,7 @@ export const createCatalogRouter = ({
     };
   });
 
-  const updateSystem = os.updateSystem.handler(async ({ input }) => {
+  const updateSystem = os.updateSystem.handler(async ({ input, context }) => {
     await enforceNotGitOpsLocked("System", input.id);
     // Convert null to undefined and filter out fields
     const cleanData: Partial<{
@@ -251,11 +251,19 @@ export const createCatalogRouter = ({
       description?: string;
       metadata?: Record<string, unknown>;
     }> = {};
-    if (input.data.name !== undefined) cleanData.name = input.data.name;
-    if (input.data.description !== undefined)
+    const changedFields: Array<"name" | "description" | "metadata"> = [];
+    if (input.data.name !== undefined) {
+      cleanData.name = input.data.name;
+      changedFields.push("name");
+    }
+    if (input.data.description !== undefined) {
       cleanData.description = input.data.description ?? undefined;
-    if (input.data.metadata !== undefined)
+      changedFields.push("description");
+    }
+    if (input.data.metadata !== undefined) {
       cleanData.metadata = input.data.metadata ?? undefined;
+      changedFields.push("metadata");
+    }
 
     const result = await entityService.updateSystem(input.id, cleanData);
     if (!result) {
@@ -269,6 +277,17 @@ export const createCatalogRouter = ({
     if (input.data.name !== undefined) {
       await upsertSystemResource({ id: result.id, name: result.name });
     }
+
+    // Emit only when a tracked field actually changed (skip no-op
+    // updates so automations don't fire on every save-with-no-diff).
+    if (changedFields.length > 0) {
+      await context.emitHook(catalogHooks.systemUpdated, {
+        systemId: result.id,
+        systemName: result.name,
+        changedFields,
+      });
+    }
+
     return result as typeof result & {
       metadata: Record<string, unknown> | null;
     };

package/tsconfig.json

@@ -10,6 +10,9 @@
     {
       "path": "../auth-common"
     },
+    {
+      "path": "../automation-backend"
+    },
     {
       "path": "../backend-api"
     },
@@ -39,6 +42,9 @@
     },
     {
       "path": "../notification-common"
+    },
+    {
+      "path": "../test-utils-backend"
     }
   ]
 }