@checkstack/automation-backend 0.2.0

package/src/schema.ts

@@ -0,0 +1,310 @@
+import {
+  pgTable,
+  text,
+  timestamp,
+  jsonb,
+  integer,
+  index,
+} from "drizzle-orm/pg-core";
+
+/**
+ * Automations — top-level entity. The `definition` column holds the full
+ * `AutomationDefinitionSchema`-validated JSON (triggers, conditions,
+ * actions, mode).
+ */
+export const automations = pgTable(
+  "automations",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    name: text("name").notNull(),
+    description: text("description"),
+    /** "enabled" | "disabled" */
+    status: text("status").notNull().default("enabled"),
+    /** Validated AutomationDefinition (zod-checked on write). */
+    definition: jsonb("definition")
+      .notNull()
+      .$type<Record<string, unknown>>(),
+    /**
+     * Origin marker. Set to "migrated-subscription:<id>" for rows produced
+     * by the webhook-subscription auto-migration, or "gitops:<provider>"
+     * for declaratively managed automations.
+     */
+    managedBy: text("managed_by"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    statusIdx: index("automations_status_idx").on(t.status),
+    managedByIdx: index("automations_managed_by_idx").on(t.managedBy),
+  }),
+);
+
+/**
+ * Automation runs — one row per dispatch. Captures the originating
+ * trigger, the payload it carried, and the durable context key for the
+ * run scope (typically `incidentId`).
+ */
+export const automationRuns = pgTable(
+  "automation_runs",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    automationId: text("automation_id")
+      .notNull()
+      .references(() => automations.id, { onDelete: "cascade" }),
+    /** Discriminator chosen at definition time. */
+    triggerId: text("trigger_id").notNull(),
+    /** Fully qualified event id (e.g. "incident.incident.created"). */
+    triggerEventId: text("trigger_event_id").notNull(),
+    triggerPayload: jsonb("trigger_payload")
+      .notNull()
+      .$type<Record<string, unknown>>(),
+    /** Durable key linking the run to a domain entity. Nullable. */
+    contextKey: text("context_key"),
+    /** "pending" | "running" | "waiting" | "success" | "failed" | "cancelled" | "skipped" */
+    status: text("status").notNull().default("pending"),
+    errorMessage: text("error_message"),
+    startedAt: timestamp("started_at").defaultNow().notNull(),
+    finishedAt: timestamp("finished_at"),
+  },
+  (t) => ({
+    automationIdx: index("automation_runs_automation_idx").on(
+      t.automationId,
+      t.startedAt,
+    ),
+    statusIdx: index("automation_runs_status_idx").on(t.status),
+    contextKeyIdx: index("automation_runs_context_key_idx").on(
+      t.automationId,
+      t.contextKey,
+    ),
+  }),
+);
+
+/**
+ * Run steps — one row per attempted action node. `actionPath` is the
+ * hierarchical path inside the action tree (e.g.
+ * "actions[0].choose[1].then[2]") so we can correlate logs back to the
+ * editor card.
+ */
+export const automationRunSteps = pgTable(
+  "automation_run_steps",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    runId: text("run_id")
+      .notNull()
+      .references(() => automationRuns.id, { onDelete: "cascade" }),
+    actionPath: text("action_path").notNull(),
+    /** Operator-assigned action id, if any. */
+    actionId: text("action_id"),
+    /** Discriminator kind: "action" | "choose" | "parallel" | … */
+    actionKind: text("action_kind").notNull(),
+    /** Fully qualified action id for provider-action steps. */
+    providerActionId: text("provider_action_id"),
+    /** "pending" | "running" | "success" | "failed" | "skipped" | "waiting" */
+    status: text("status").notNull().default("pending"),
+    attempts: integer("attempts").notNull().default(0),
+    errorMessage: text("error_message"),
+    resultPayload: jsonb("result_payload").$type<Record<string, unknown>>(),
+    startedAt: timestamp("started_at").defaultNow().notNull(),
+    finishedAt: timestamp("finished_at"),
+  },
+  (t) => ({
+    runIdx: index("automation_run_steps_run_idx").on(t.runId),
+  }),
+);
+
+/**
+ * Artifacts — typed payloads actions persist for downstream lookup.
+ *
+ * Lookup keys:
+ *   - `(automationId, contextKey, artifactType)` — "give me the most recent
+ *     jira.issue artifact for incident X in automation Y"
+ *   - `(automationId, actionId)` — "give me what action Z produced"
+ */
+export const automationArtifacts = pgTable(
+  "automation_artifacts",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    automationId: text("automation_id")
+      .notNull()
+      .references(() => automations.id, { onDelete: "cascade" }),
+    runId: text("run_id")
+      .notNull()
+      .references(() => automationRuns.id, { onDelete: "cascade" }),
+    stepId: text("step_id")
+      .notNull()
+      .references(() => automationRunSteps.id, { onDelete: "cascade" }),
+    /** Operator-assigned action id, if any. */
+    actionId: text("action_id"),
+    /** Fully qualified artifact type (e.g. "jira.issue"). */
+    artifactType: text("artifact_type").notNull(),
+    /** Free-form artifact data — validated against the type's schema on write. */
+    data: jsonb("data").notNull().$type<Record<string, unknown>>(),
+    /** Durable lookup key (typically `incidentId`). */
+    contextKey: text("context_key"),
+    /** Set when a downstream close action marks the artifact resolved. */
+    closedAt: timestamp("closed_at"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    /**
+     * Powers "find the most recent jira.issue for incident X" — the
+     * default lookup when an action declares `consumes`.
+     */
+    contextLookupIdx: index(
+      "automation_artifacts_context_lookup_idx",
+    ).on(t.automationId, t.contextKey, t.artifactType, t.createdAt),
+    /** Powers per-action lookup (`artifacts.<actionId>` references). */
+    actionLookupIdx: index("automation_artifacts_action_lookup_idx").on(
+      t.automationId,
+      t.actionId,
+      t.createdAt,
+    ),
+    /** Used by close actions to filter "still open" artifacts. */
+    openIdx: index("automation_artifacts_open_idx").on(
+      t.automationId,
+      t.closedAt,
+    ),
+  }),
+);
+
+/**
+ * Wait locks — durable bookkeeping for any kind of suspended run.
+ *
+ *   - `kind = "trigger"`: classic `wait_for_trigger`. Resumed by the
+ *     trigger fan-in when a matching event arrives.
+ *   - `kind = "delay"`: durable replacement for `setTimeout`. The dispatch
+ *     engine persists the lock and enqueues a `automation-delay` queue
+ *     job with `startDelay`; the queue consumer resumes the run on
+ *     firing. The stalled-run sweeper also catches expired delay locks
+ *     in case the queue job is lost.
+ *
+ * Either kind survives process restarts and horizontal scaling: the
+ * lock is the source of truth, the queue / hook is the wake-up signal.
+ */
+export const automationWaitLocks = pgTable(
+  "automation_wait_locks",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    runId: text("run_id")
+      .notNull()
+      .references(() => automationRuns.id, { onDelete: "cascade" }),
+    /** Action path of the suspended node — used to resume from the next sibling. */
+    actionPath: text("action_path").notNull(),
+    /** Discriminator: "trigger" (wait_for_trigger) or "delay" (queue-backed sleep). */
+    kind: text("kind").notNull().default("trigger"),
+    /** Fully qualified event id being awaited (only meaningful when kind = "trigger"). */
+    eventId: text("event_id").notNull(),
+    /** Optional context-key filter (e.g. same incidentId). */
+    contextKey: text("context_key"),
+    /** Optional template that must evaluate truthy on the arriving payload. */
+    filterTemplate: text("filter_template"),
+    /**
+     * Absolute deadline. For `kind = "trigger"`: nullable; if set, the
+     * sweeper fails the run when exceeded. For `kind = "delay"`:
+     * required; the firing time after which the run should resume even
+     * if the queue job is lost.
+     */
+    timeoutAt: timestamp("timeout_at"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    /** Powers "any wait locks for this incoming event + context?" */
+    eventLookupIdx: index("automation_wait_locks_event_lookup_idx").on(
+      t.eventId,
+      t.contextKey,
+    ),
+    /** Powers periodic timeout sweep. */
+    timeoutIdx: index("automation_wait_locks_timeout_idx").on(t.timeoutAt),
+    /** Powers the run-detail UI's "what are we waiting on?" view. */
+    runIdx: index("automation_wait_locks_run_idx").on(t.runId),
+  }),
+);
+
+/**
+ * Per-run durable execution state.
+ *
+ * Updated after every successfully-completed step (and again on
+ * suspension) so a future process can resume a run from exactly where
+ * the prior process left off.
+ *
+ *   - `scopeSnapshot` — JSON-encoded variable scope (`trigger`, `variables`,
+ *     `artifacts`, plus helpers) sufficient to seed a fresh
+ *     `DispatchContext` on resume.
+ *   - `lastActionPath` — path of the most recently completed action; the
+ *     walker resumes from the next sibling after this.
+ *   - `lastHeartbeatAt` — bumped on every step write. The stalled-run
+ *     sweeper uses this to identify runs that look dead.
+ *
+ * One row per active or waiting run. Cleared on terminal status.
+ */
+export const automationRunState = pgTable(
+  "automation_run_state",
+  {
+    runId: text("run_id")
+      .primaryKey()
+      .references(() => automationRuns.id, { onDelete: "cascade" }),
+    scopeSnapshot: jsonb("scope_snapshot")
+      .notNull()
+      .$type<Record<string, unknown>>(),
+    lastActionPath: text("last_action_path"),
+    lastHeartbeatAt: timestamp("last_heartbeat_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    /**
+     * Powers the stalled-run sweeper: scan runs whose heartbeat is older
+     * than the threshold.
+     */
+    heartbeatIdx: index("automation_run_state_heartbeat_idx").on(
+      t.lastHeartbeatAt,
+    ),
+  }),
+);
+
+/**
+ * Subscription-migration failures.
+ *
+ * Surfaces every webhook_subscription row the one-time migration
+ * couldn't convert into an automation. Operators see them via the
+ * `listMigrationFailures` RPC + acknowledge them once the source
+ * subscription is recreated as an automation. Acknowledged rows are
+ * dropped so the queue is self-cleaning.
+ *
+ * The table is empty under normal operation — its presence costs
+ * nothing on greenfield installs.
+ */
+export const automationMigrationFailures = pgTable(
+  "automation_migration_failures",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    /** Source `webhook_subscriptions.id`. */
+    subscriptionId: text("subscription_id").notNull().unique(),
+    /** Subscription `name`, captured for the admin UI. */
+    subscriptionName: text("subscription_name").notNull(),
+    /** Source `providerId` (e.g. `integration-teams.teams`). */
+    providerId: text("provider_id").notNull(),
+    /** Source `eventId` the subscription was bound to. */
+    eventId: text("event_id").notNull(),
+    /** Short reason (a code or one-line summary). */
+    reason: text("reason").notNull(),
+    /** Detailed error message captured at migration time. */
+    detail: text("detail"),
+    /** Original `providerConfig` JSON for postmortem / manual rebuild. */
+    providerConfig: jsonb("provider_config")
+      .notNull()
+      .$type<Record<string, unknown>>(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+);

package/src/trigger-registry.ts

@@ -0,0 +1,99 @@
+import type { PluginMetadata } from "@checkstack/common";
+import { toJsonSchema } from "@checkstack/backend-api";
+import type {
+  RegisteredTrigger,
+  TriggerDefinition,
+} from "./action-types";
+
+/**
+ * Registry for automation triggers. Plugins register triggers here through
+ * `automationTriggerExtensionPoint`; the dispatch engine reads from this
+ * registry in `afterPluginsReady` to wire up hook subscriptions and custom
+ * setups.
+ */
+export interface TriggerRegistry {
+  register<TPayload, TConfig = void>(
+    definition: TriggerDefinition<TPayload, TConfig>,
+    pluginMetadata: PluginMetadata,
+  ): void;
+
+  /** Get every registered trigger. */
+  getTriggers(): RegisteredTrigger[];
+  /** Look up a trigger by its fully qualified id. */
+  getTrigger(qualifiedId: string): RegisteredTrigger | undefined;
+  /** Group triggers by their category for UI listings. */
+  getTriggersByCategory(): Map<string, RegisteredTrigger[]>;
+  hasTrigger(qualifiedId: string): boolean;
+}
+
+export function createTriggerRegistry(): TriggerRegistry {
+  const triggers = new Map<string, RegisteredTrigger>();
+
+  return {
+    register<TPayload, TConfig = void>(
+      definition: TriggerDefinition<TPayload, TConfig>,
+      pluginMetadata: PluginMetadata,
+    ): void {
+      const qualifiedId = `${pluginMetadata.pluginId}.${definition.id}`;
+      if (triggers.has(qualifiedId)) {
+        throw new Error(
+          `Trigger ${qualifiedId} already registered — likely a duplicate registration in ${pluginMetadata.pluginId}.`,
+        );
+      }
+
+      // Defence in depth: a trigger must be reachable somehow.
+      if (!definition.hook && !definition.setup) {
+        throw new Error(
+          `Trigger ${qualifiedId} has neither a hook nor a setup callback; it cannot fire.`,
+        );
+      }
+
+      const payloadJsonSchema = toJsonSchema(definition.payloadSchema);
+      const configJsonSchema = definition.configSchema
+        ? toJsonSchema(definition.configSchema)
+        : undefined;
+
+      const registered: RegisteredTrigger<TPayload, TConfig> = {
+        id: definition.id,
+        displayName: definition.displayName,
+        description: definition.description,
+        category: definition.category ?? "Uncategorized",
+        icon: definition.icon,
+        payloadSchema: definition.payloadSchema,
+        configSchema: definition.configSchema,
+        contextKey: definition.contextKey,
+        hook: definition.hook,
+        setup: definition.setup,
+        qualifiedId,
+        ownerPluginId: pluginMetadata.pluginId,
+        payloadJsonSchema,
+        configJsonSchema,
+      };
+
+      triggers.set(qualifiedId, registered as RegisteredTrigger);
+    },
+
+    getTriggers(): RegisteredTrigger[] {
+      return [...triggers.values()];
+    },
+
+    getTrigger(qualifiedId: string): RegisteredTrigger | undefined {
+      return triggers.get(qualifiedId);
+    },
+
+    getTriggersByCategory(): Map<string, RegisteredTrigger[]> {
+      const byCategory = new Map<string, RegisteredTrigger[]>();
+      for (const trigger of triggers.values()) {
+        const category = trigger.category ?? "Uncategorized";
+        const existing = byCategory.get(category) ?? [];
+        existing.push(trigger);
+        byCategory.set(category, existing);
+      }
+      return byCategory;
+    },
+
+    hasTrigger(qualifiedId: string): boolean {
+      return triggers.has(qualifiedId);
+    },
+  };
+}