@checkstack/automation-backend 0.2.0

package/src/extension-points.ts

@@ -0,0 +1,88 @@
+import {
+  createExtensionPoint,
+  createServiceRef,
+} from "@checkstack/backend-api";
+import type { PluginMetadata } from "@checkstack/common";
+import type {
+  ActionDefinition,
+  ArtifactTypeDefinition,
+  TriggerDefinition,
+} from "./action-types";
+import type { ActionRegistry } from "./action-registry";
+import type { ArtifactTypeRegistry } from "./artifact-type-registry";
+import type { TriggerRegistry } from "./trigger-registry";
+import type { ArtifactStore } from "./artifact-store";
+
+/**
+ * Extension point for registering automation triggers — entry points that
+ * fire automations when their underlying event arrives.
+ */
+export interface AutomationTriggerExtensionPoint {
+  registerTrigger<TPayload, TConfig = void>(
+    definition: TriggerDefinition<TPayload, TConfig>,
+    pluginMetadata: PluginMetadata,
+  ): void;
+}
+
+export const automationTriggerExtensionPoint =
+  createExtensionPoint<AutomationTriggerExtensionPoint>(
+    "automation.triggerExtensionPoint",
+  );
+
+/**
+ * Extension point for registering automation actions — callable work the
+ * automation editor exposes to operators.
+ */
+export interface AutomationActionExtensionPoint {
+  registerAction<TConfig, TArtifact = unknown>(
+    definition: ActionDefinition<TConfig, TArtifact>,
+    pluginMetadata: PluginMetadata,
+  ): void;
+}
+
+export const automationActionExtensionPoint =
+  createExtensionPoint<AutomationActionExtensionPoint>(
+    "automation.actionExtensionPoint",
+  );
+
+/**
+ * Extension point for registering artifact types — typed payloads
+ * produced and consumed by actions.
+ */
+export interface AutomationArtifactTypeExtensionPoint {
+  registerArtifactType<T>(
+    definition: ArtifactTypeDefinition<T>,
+    pluginMetadata: PluginMetadata,
+  ): void;
+}
+
+export const automationArtifactTypeExtensionPoint =
+  createExtensionPoint<AutomationArtifactTypeExtensionPoint>(
+    "automation.artifactTypeExtensionPoint",
+  );
+
+// ─── Service refs ─────────────────────────────────────────────────────────
+
+/**
+ * Read-only view of the trigger / action / artifact-type registries.
+ * Other plugins (and the frontend RPC) can inject this to introspect what
+ * the automation platform offers.
+ */
+export interface AutomationRegistries {
+  readonly triggers: TriggerRegistry;
+  readonly actions: ActionRegistry;
+  readonly artifactTypes: ArtifactTypeRegistry;
+}
+
+export const automationRegistriesRef = createServiceRef<AutomationRegistries>(
+  "automation.registries",
+);
+
+/**
+ * Service ref for the artifact store. Cross-plugin code (e.g. an action
+ * in `integration-jira-backend` that wants to look up a prior issue
+ * artifact) injects this to query / persist artifacts.
+ */
+export const automationArtifactStoreRef = createServiceRef<ArtifactStore>(
+  "automation.artifactStore",
+);

package/src/index.ts

@@ -0,0 +1,379 @@
+import {
+  createBackendPlugin,
+  coreServices,
+} from "@checkstack/backend-api";
+import {
+  automationAccess,
+  automationAccessRules,
+  automationContract,
+  automationRoutes,
+  pluginMetadata,
+} from "@checkstack/automation-common";
+import { resolveRoute, extractErrorMessage } from "@checkstack/common";
+import type { PluginMetadata } from "@checkstack/common";
+import { registerSearchProvider } from "@checkstack/command-backend";
+import { createDefaultFilterRegistry } from "@checkstack/template-engine";
+
+import type {
+  ActionDefinition,
+  ArtifactTypeDefinition,
+  TriggerDefinition,
+} from "./action-types";
+import { createTriggerRegistry, type TriggerRegistry } from "./trigger-registry";
+import { createActionRegistry, type ActionRegistry } from "./action-registry";
+import {
+  createArtifactTypeRegistry,
+  type ArtifactTypeRegistry,
+} from "./artifact-type-registry";
+import { createArtifactStore } from "./artifact-store";
+import { createAutomationStore } from "./automation-store";
+import { createAutomationRouter } from "./router";
+import { runWebhookSubscriptionMigration } from "./migration/from-webhook-subscriptions";
+import {
+  startDelayQueueConsumer,
+  type DelayQueueConsumer,
+} from "./dispatch/delay-queue";
+import { createRunStore } from "./dispatch/run-state";
+import { createRunStateStore } from "./dispatch/run-state-store";
+import {
+  startStalledSweeper,
+  type StalledSweeper,
+} from "./dispatch/stalled-sweeper";
+import {
+  setupTriggerSubscriptions,
+  type TriggerSubscriptions,
+} from "./dispatch/trigger-subscriber";
+import type { DispatchDeps } from "./dispatch/types";
+import {
+  automationActionExtensionPoint,
+  automationArtifactStoreRef,
+  automationArtifactTypeExtensionPoint,
+  automationRegistriesRef,
+  automationTriggerExtensionPoint,
+} from "./extension-points";
+import {
+  registerBuiltinTriggerConsumer,
+  registerBuiltinTriggers,
+} from "./builtin-triggers";
+import {
+  createNotifyUserAction,
+  logAction,
+  notifyUserArtifactType,
+} from "./builtin-actions";
+import * as schema from "./schema";
+
+/**
+ * Internal env stash used to thread registries / stores from `register()`
+ * and `init()` into `afterPluginsReady()`. Mirrors the established
+ * pattern in `integration-backend/src/index.ts`.
+ */
+interface EnvStash {
+  triggerRegistry: TriggerRegistry;
+  actionRegistry: ActionRegistry;
+  artifactTypeRegistry: ArtifactTypeRegistry;
+  dispatchDeps: DispatchDeps;
+  automationStore: ReturnType<typeof createAutomationStore>;
+  triggerSubscriptions?: TriggerSubscriptions;
+  stalledSweeper?: StalledSweeper;
+  delayConsumer?: DelayQueueConsumer;
+}
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    const triggerRegistry = createTriggerRegistry();
+    const actionRegistry = createActionRegistry();
+    const artifactTypeRegistry = createArtifactTypeRegistry();
+
+    env.registerAccessRules(automationAccessRules);
+
+    env.registerExtensionPoint(automationTriggerExtensionPoint, {
+      registerTrigger: <TPayload, TConfig = void>(
+        definition: TriggerDefinition<TPayload, TConfig>,
+        metadata: PluginMetadata,
+      ) => {
+        triggerRegistry.register(
+          definition as TriggerDefinition<unknown, unknown>,
+          metadata,
+        );
+      },
+    });
+
+    env.registerExtensionPoint(automationActionExtensionPoint, {
+      registerAction: <TConfig, TArtifact = unknown>(
+        definition: ActionDefinition<TConfig, TArtifact>,
+        metadata: PluginMetadata,
+      ) => {
+        actionRegistry.register(
+          definition as ActionDefinition<unknown, unknown>,
+          metadata,
+        );
+      },
+    });
+
+    env.registerExtensionPoint(automationArtifactTypeExtensionPoint, {
+      registerArtifactType: <T>(
+        definition: ArtifactTypeDefinition<T>,
+        metadata: PluginMetadata,
+      ) => {
+        artifactTypeRegistry.register(
+          definition as ArtifactTypeDefinition<unknown>,
+          metadata,
+        );
+      },
+    });
+
+    env.registerInit({
+      schema,
+      deps: {
+        logger: coreServices.logger,
+        rpc: coreServices.rpc,
+        rpcClient: coreServices.rpcClient,
+        queueManager: coreServices.queueManager,
+        signalService: coreServices.signalService,
+      },
+      init: async ({
+        logger,
+        database,
+        rpc,
+        rpcClient,
+        queueManager,
+        signalService,
+      }) => {
+        logger.debug("⚙️  Initializing Automation Backend...");
+
+        const artifactStore = createArtifactStore(database);
+        const runStore = createRunStore(database);
+        const runStateStore = createRunStateStore(database);
+        const automationStore = createAutomationStore(database);
+
+        env.registerService(automationArtifactStoreRef, artifactStore);
+        env.registerService(automationRegistriesRef, {
+          triggers: triggerRegistry,
+          actions: actionRegistry,
+          artifactTypes: artifactTypeRegistry,
+        });
+
+        // ─── Built-in triggers + actions ──────────────────────────────
+        // automation-backend ships its own triggers/actions through the
+        // same registries it exposes to other plugins; the registration
+        // happens here in init() because the trigger setup needs
+        // `queueManager` and the `notify_user` action needs
+        // `rpcClient`. The shared consumer for built-in trigger ticks
+        // is started here too — by the time `setupTriggerSubscriptions`
+        // calls each trigger's `setup()` in afterPluginsReady, the
+        // consumer is already draining the queue.
+        registerBuiltinTriggers({
+          queueManager,
+          pluginMetadata,
+          registerTrigger: (trigger, metadata) => {
+            triggerRegistry.register(trigger, metadata);
+          },
+        });
+        actionRegistry.register(
+          logAction as ActionDefinition<unknown, unknown>,
+          pluginMetadata,
+        );
+        actionRegistry.register(
+          createNotifyUserAction({ rpcClient }) as ActionDefinition<
+            unknown,
+            unknown
+          >,
+          pluginMetadata,
+        );
+        artifactTypeRegistry.register(
+          notifyUserArtifactType as ArtifactTypeDefinition<unknown>,
+          pluginMetadata,
+        );
+        await registerBuiltinTriggerConsumer({ queueManager, logger });
+
+        const dispatchDeps: DispatchDeps = {
+          logger,
+          filters: createDefaultFilterRegistry(),
+          registries: {
+            triggers: triggerRegistry,
+            actions: actionRegistry,
+            artifactTypes: artifactTypeRegistry,
+          },
+          artifactStore,
+          runStore,
+          runStateStore,
+          queueManager,
+          getService: async () => {
+            throw new Error(
+              "getService not yet wired — automation dispatch invoked too early",
+            );
+          },
+        };
+
+        const stash = env as unknown as EnvStash;
+        stash.triggerRegistry = triggerRegistry;
+        stash.actionRegistry = actionRegistry;
+        stash.artifactTypeRegistry = artifactTypeRegistry;
+        stash.dispatchDeps = dispatchDeps;
+        stash.automationStore = automationStore;
+
+        const router = createAutomationRouter({
+          db: database,
+          automationStore,
+          triggerRegistry,
+          actionRegistry,
+          artifactTypeRegistry,
+          dispatchDeps,
+          signalService,
+          logger,
+        });
+        rpc.registerRouter(router, automationContract);
+
+        registerSearchProvider({
+          pluginMetadata,
+          commands: [
+            {
+              id: "list",
+              title: "Manage Automations",
+              subtitle: "View, edit, enable, or disable automations",
+              iconName: "Workflow",
+              shortcuts: ["meta+shift+a", "ctrl+shift+a"],
+              route: resolveRoute(automationRoutes.routes.list),
+              requiredAccessRules: [automationAccess.read],
+            },
+            {
+              id: "create",
+              title: "Create Automation",
+              subtitle: "Build a new automation from triggers and actions",
+              iconName: "Plus",
+              route: resolveRoute(automationRoutes.routes.create),
+              requiredAccessRules: [automationAccess.manage],
+            },
+            {
+              id: "playground",
+              title: "Template Playground",
+              subtitle: "Test automation templates against a sample payload",
+              iconName: "Beaker",
+              route: resolveRoute(automationRoutes.routes.playground),
+              requiredAccessRules: [automationAccess.read],
+            },
+          ],
+        });
+
+        env.registerCleanup(async () => {
+          const s = env as unknown as EnvStash;
+          await s.triggerSubscriptions?.dispose();
+          s.stalledSweeper?.stop();
+          await s.delayConsumer?.stop();
+        });
+
+        logger.debug("✅ Automation Backend initialized.");
+      },
+
+      afterPluginsReady: async ({ database, logger, onHook, rpcClient }) => {
+        const stash = env as unknown as EnvStash;
+        const triggers = stash.triggerRegistry.getTriggers();
+        const actions = stash.actionRegistry.getActions();
+        const artifactTypes = stash.artifactTypeRegistry.getArtifactTypes();
+
+        logger.debug(
+          `⚙️  Registered ${triggers.length} automation triggers${
+            triggers.length > 0
+              ? ": " + triggers.map((t) => t.qualifiedId).join(", ")
+              : ""
+          }`,
+        );
+        logger.debug(
+          `⚙️  Registered ${actions.length} automation actions${
+            actions.length > 0
+              ? ": " + actions.map((a) => a.qualifiedId).join(", ")
+              : ""
+          }`,
+        );
+        logger.debug(
+          `⚙️  Registered ${artifactTypes.length} artifact types${
+            artifactTypes.length > 0
+              ? ": " + artifactTypes.map((t) => t.qualifiedId).join(", ")
+              : ""
+          }`,
+        );
+
+        // Trigger fan-in: subscribe to every registered hook-backed
+        // trigger in work-queue mode; instantiate setup-backed triggers
+        // per referencing automation.
+        stash.triggerSubscriptions = await setupTriggerSubscriptions({
+          deps: stash.dispatchDeps,
+          onHook,
+          automationStore: stash.automationStore,
+          logger,
+        });
+
+        // Crash-safe delay: register the consumer that fires when a
+        // scheduled queue job pops, resuming the suspended run.
+        stash.delayConsumer = await startDelayQueueConsumer({
+          deps: stash.dispatchDeps,
+          automationStore: stash.automationStore,
+          logger,
+        });
+
+        // Restart safety + horizontal scaling: periodically scan for
+        // runs whose heartbeat is older than the threshold and resume
+        // them under an advisory lock.
+        stash.stalledSweeper = startStalledSweeper({
+          deps: stash.dispatchDeps,
+          automationStore: stash.automationStore,
+          logger,
+        });
+
+        // One-time migration: pull legacy `webhook_subscriptions` rows
+        // via the integration-backend service RPC and translate each
+        // into an automation. Already-migrated rows (matched on
+        // `managed_by`) are skipped, so this is safe to run on every
+        // boot. Failures are recorded for admin review via the
+        // `listMigrationFailures` RPC.
+        try {
+          await runWebhookSubscriptionMigration({
+            db: database,
+            rpcClient,
+            logger,
+          });
+        } catch (error) {
+          logger.error(
+            `Subscription migration failed unexpectedly: ${extractErrorMessage(error, "unknown error")}`,
+          );
+        }
+
+        logger.debug("✅ Automation Backend afterPluginsReady complete.");
+      },
+    });
+  },
+});
+
+// ─── Re-exports for consumer plugins ─────────────────────────────────────
+
+export {
+  automationTriggerExtensionPoint,
+  automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
+  automationRegistriesRef,
+  automationArtifactStoreRef,
+} from "./extension-points";
+
+export type {
+  TriggerDefinition,
+  ActionDefinition,
+  ArtifactTypeDefinition,
+  ActionExecutionContext,
+  ActionRunScope,
+  ActionResult,
+  ArtifactTypeRef,
+  RegisteredTrigger,
+  RegisteredAction,
+  RegisteredArtifactType,
+  TriggerSetupFn,
+  TriggerTeardown,
+} from "./action-types";
+
+export type { ArtifactStore, PersistedArtifact } from "./artifact-store";
+export type { TriggerRegistry } from "./trigger-registry";
+export type { ActionRegistry } from "./action-registry";
+export type { ArtifactTypeRegistry } from "./artifact-type-registry";
+export type { AutomationRegistries } from "./extension-points";
+export type { AutomationStore } from "./automation-store";

package/src/migration/from-webhook-subscriptions.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Behaviour tests for the per-provider translation rules.
+ *
+ * The full `runWebhookSubscriptionMigration` path needs a database and
+ * an RPC client, so it's covered by the existing dispatch-engine
+ * integration fixtures (and ultimately by the smoke test). Here we
+ * lock down `buildDefinitionFor`, which is where the interesting
+ * mapping decisions live.
+ */
+import { describe, expect, it } from "bun:test";
+import {
+  buildDefinitionFor,
+  type LegacySubscription,
+} from "./from-webhook-subscriptions";
+
+function sub(overrides: Partial<LegacySubscription> = {}): LegacySubscription {
+  return {
+    id: "sub-1",
+    name: "Test",
+    providerId: "integration-webhook.webhook",
+    providerConfig: { url: "https://example.com/hook" },
+    eventId: "incident.created",
+    enabled: true,
+    ...overrides,
+  };
+}
+
+describe("buildDefinitionFor", () => {
+  it("returns a failure for unknown providers", () => {
+    const result = buildDefinitionFor(
+      sub({ providerId: "made-up.provider" }),
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toMatch(/unsupported provider/);
+    }
+  });
+
+  it("translates a Jira subscription to the jira.create_issue action", () => {
+    const result = buildDefinitionFor(
+      sub({
+        providerId: "integration-jira.jira",
+        providerConfig: {
+          connectionId: "conn-1",
+          projectKey: "PROJ",
+          issueTypeId: "10001",
+          summaryTemplate: "{{ trigger.payload.title }}",
+          descriptionTemplate: "Severity: {{ trigger.payload.severity }}",
+          priorityId: "3",
+          fieldMappings: [
+            { fieldKey: "customfield_1", template: "{{ trigger.payload.foo }}" },
+          ],
+        },
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.actionId).toBe("integration-jira.create_issue");
+    expect(result.definition.actions).toHaveLength(1);
+    const action = result.definition.actions[0] as { action: string; config: Record<string, unknown> };
+    expect(action.action).toBe("integration-jira.create_issue");
+    expect(action.config.summary).toBe("{{ trigger.payload.title }}");
+    expect(action.config.description).toBe(
+      "Severity: {{ trigger.payload.severity }}",
+    );
+    expect(action.config.fieldMappings).toEqual([
+      { fieldKey: "customfield_1", value: "{{ trigger.payload.foo }}" },
+    ]);
+  });
+
+  it("generates a default body for Teams when the legacy schema had no template", () => {
+    const result = buildDefinitionFor(
+      sub({
+        providerId: "integration-teams.teams",
+        providerConfig: {
+          connectionId: "conn-1",
+          teamId: "team-1",
+          channelId: "ch-1",
+        },
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const action = result.definition.actions[0] as { config: Record<string, unknown> };
+    expect(typeof action.config.body).toBe("string");
+    expect((action.config.body as string).length).toBeGreaterThan(0);
+  });
+
+  it("preserves an explicit Webex messageTemplate", () => {
+    const result = buildDefinitionFor(
+      sub({
+        providerId: "integration-webex.webex",
+        providerConfig: {
+          connectionId: "conn-1",
+          roomId: "room-1",
+          messageTemplate: "Custom: {{ trigger.payload.title }}",
+        },
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const action = result.definition.actions[0] as { config: Record<string, unknown> };
+    expect(action.config.markdown).toBe("Custom: {{ trigger.payload.title }}");
+  });
+
+  it("falls back to a default Webex markdown when messageTemplate is empty", () => {
+    const result = buildDefinitionFor(
+      sub({
+        providerId: "integration-webex.webex",
+        providerConfig: {
+          connectionId: "conn-1",
+          roomId: "room-1",
+        },
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const action = result.definition.actions[0] as { config: Record<string, unknown> };
+    expect(typeof action.config.markdown).toBe("string");
+    expect((action.config.markdown as string).length).toBeGreaterThan(0);
+  });
+
+  it("renames webhook bodyTemplate to body", () => {
+    const result = buildDefinitionFor(
+      sub({
+        providerId: "integration-webhook.webhook",
+        providerConfig: {
+          url: "https://example.com/hook",
+          method: "POST",
+          contentType: "application/json",
+          authType: "none",
+          timeout: 10_000,
+          bodyTemplate: `{"x":"{{ trigger.payload.x }}"}`,
+        },
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const action = result.definition.actions[0] as { config: Record<string, unknown> };
+    expect(action.config.body).toBe(`{"x":"{{ trigger.payload.x }}"}`);
+    expect(action.config.bodyTemplate).toBeUndefined();
+  });
+
+  it("maps the legacy shell provider to integration-script.run_shell and preserves workingDirectory", () => {
+    const result = buildDefinitionFor(
+      sub({
+        providerId: "integration-script.shell",
+        providerConfig: {
+          script: "echo hi",
+          timeout: 10_000,
+          workingDirectory: "/tmp",
+        },
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.actionId).toBe("integration-script.run_shell");
+    const action = result.definition.actions[0] as {
+      config: Record<string, unknown>;
+    };
+    expect(action.config.script).toBe("echo hi");
+    expect(action.config.workingDirectory).toBe("/tmp");
+  });
+
+  it("maps the legacy TS-script provider to integration-script.run_script and drops shell-only fields", () => {
+    const result = buildDefinitionFor(
+      sub({
+        providerId: "integration-script.script",
+        providerConfig: {
+          script: "export default async () => ({ id: 'x' });",
+          timeout: 10_000,
+          // Legacy data may still have a stray workingDirectory — it
+          // doesn't apply to the ESM runner, so the migration drops it
+          // rather than silently feeding it to an action that ignores it.
+          workingDirectory: "/tmp",
+        },
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.actionId).toBe("integration-script.run_script");
+    const action = result.definition.actions[0] as {
+      config: Record<string, unknown>;
+    };
+    expect(action.config.script).toBe(
+      "export default async () => ({ id: 'x' });",
+    );
+    expect(action.config).not.toHaveProperty("workingDirectory");
+  });
+
+  it("emits an OR condition for systemFilter with multiple ids", () => {
+    const result = buildDefinitionFor(
+      sub({
+        systemFilter: ["sys-1", "sys-2"],
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.definition.conditions).toHaveLength(1);
+    const cond = result.definition.conditions[0] as { or: string[] };
+    expect(cond.or).toHaveLength(2);
+    expect(cond.or[0]).toContain("sys-1");
+  });
+
+  it("emits a single template condition for a single-id systemFilter", () => {
+    const result = buildDefinitionFor(
+      sub({ systemFilter: ["sys-only"] }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.definition.conditions).toHaveLength(1);
+    expect(typeof result.definition.conditions[0]).toBe("string");
+    expect(result.definition.conditions[0]).toContain("sys-only");
+  });
+
+  it("emits no conditions when systemFilter is empty", () => {
+    const result = buildDefinitionFor(sub({ systemFilter: [] }));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.definition.conditions).toEqual([]);
+  });
+
+  it("preserves the description and trigger event id", () => {
+    const result = buildDefinitionFor(
+      sub({
+        description: "On-call paging",
+        eventId: "incident.incident.created",
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.definition.description).toBe("On-call paging");
+    expect(result.definition.triggers[0]?.event).toBe(
+      "incident.incident.created",
+    );
+  });
+});