@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/migration/flapping-to-window.ts

@@ -0,0 +1,205 @@
+/**
+ * One-time migration: rewrite legacy `healthcheck.flapping_detected` triggers
+ * onto the generic windowed-count gate.
+ *
+ * The pre-derived `flapping_detected` trigger (+ its `{ transitions,
+ * windowMinutes }` config) was removed. Flapping is now expressed as a window
+ * over the raw `healthcheck.system_health_changed` change event:
+ *
+ *   event:  healthcheck.flapping_detected
+ *   config: { transitions, windowMinutes }
+ *      ↓
+ *   event:  healthcheck.system_health_changed
+ *   filter: trigger.payload.newStatus != "healthy"
+ *   window: { count: transitions ?? 3, minutes: windowMinutes ?? 60, refire: "once" }
+ *
+ * Targets USER-created automations only — the seeded `auto-incident:*` rows
+ * were already deleted (migration 0008). Idempotent: an automation whose
+ * triggers no longer reference the legacy event is left untouched.
+ *
+ * Safe-option note on a PRE-EXISTING filter: a legacy flapping trigger could
+ * (rarely) already carry an operator `filter`. The unhealthy-transition filter
+ * is the load-bearing semantic of the new flapping shape, so we REPLACE any
+ * pre-existing filter with the canonical one rather than silently AND-combining
+ * (which could change behaviour in surprising ways). This is logged per row so
+ * an operator can re-add a bespoke clause if they had one.
+ */
+import { eq } from "drizzle-orm";
+import type { Logger, SafeDatabase } from "@checkstack/backend-api";
+
+import * as schema from "../schema";
+
+type Db = SafeDatabase<typeof schema>;
+
+/** Legacy + new event ids (string-compared against stored `trigger.event`). */
+export const LEGACY_FLAPPING_EVENT = "healthcheck.flapping_detected";
+export const HEALTH_CHANGED_EVENT = "healthcheck.system_health_changed";
+
+/** Canonical filter for the windowed flapping shape (unhealthy transitions). */
+export const FLAPPING_FILTER = 'trigger.payload.newStatus != "healthy"';
+
+/** Defaults applied when a legacy trigger carried no / partial config. */
+export const DEFAULT_FLAPPING_COUNT = 3;
+export const DEFAULT_FLAPPING_MINUTES = 60;
+
+interface RewriteOutcome {
+  /** The (possibly) rewritten definition. */
+  definition: Record<string, unknown>;
+  /** Number of flapping triggers rewritten in this definition. */
+  rewritten: number;
+  /** True if any rewritten trigger had a pre-existing filter we replaced. */
+  replacedFilter: boolean;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function readPositiveInt(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1
+    ? value
+    : fallback;
+}
+
+/**
+ * Rewrite every legacy `flapping_detected` trigger in a stored automation
+ * definition. Pure — no I/O — so the mapping (config → window, defaults,
+ * filter replacement) is unit-testable in isolation. Returns the new
+ * definition plus counters; `rewritten === 0` means "leave the row untouched".
+ */
+export function rewriteFlappingTriggers(
+  definition: Record<string, unknown>,
+): RewriteOutcome {
+  const triggers = definition["triggers"];
+  if (!Array.isArray(triggers)) {
+    return { definition, rewritten: 0, replacedFilter: false };
+  }
+
+  let rewritten = 0;
+  let replacedFilter = false;
+
+  const nextTriggers = triggers.map((raw) => {
+    const trigger = asRecord(raw);
+    if (!trigger || trigger["event"] !== LEGACY_FLAPPING_EVENT) return raw;
+
+    const config = asRecord(trigger["config"]);
+    const count = readPositiveInt(config?.["transitions"], DEFAULT_FLAPPING_COUNT);
+    const minutes = readPositiveInt(
+      config?.["windowMinutes"],
+      DEFAULT_FLAPPING_MINUTES,
+    );
+
+    if (typeof trigger["filter"] === "string") replacedFilter = true;
+    rewritten += 1;
+
+    // Drop `config`; set the new event + canonical filter + window. Preserve
+    // any other fields the operator set (id, for, etc.).
+    const { config: _dropped, ...rest } = trigger;
+    void _dropped;
+    return {
+      ...rest,
+      event: HEALTH_CHANGED_EVENT,
+      filter: FLAPPING_FILTER,
+      window: { count, minutes, refire: "once" },
+    };
+  });
+
+  if (rewritten === 0) {
+    return { definition, rewritten: 0, replacedFilter: false };
+  }
+  return {
+    definition: { ...definition, triggers: nextTriggers },
+    rewritten,
+    replacedFilter,
+  };
+}
+
+export interface FlappingMigrationResult {
+  /** Automations scanned. */
+  scanned: number;
+  /** Automations whose definition was rewritten + persisted. */
+  migrated: number;
+  /** Total flapping triggers rewritten across all rows. */
+  triggersRewritten: number;
+}
+
+/**
+ * Scan every automation and rewrite legacy flapping triggers. Idempotent:
+ * rows with no flapping trigger are skipped; rows already migrated have no
+ * `flapping_detected` event and are skipped too. Safe to run on every boot.
+ *
+ * After the rewrite, logs a WARNING if any enabled automation still references
+ * the legacy event (should never happen post-rewrite — a leftover indicates a
+ * definition the migration couldn't parse).
+ */
+export async function runFlappingAutomationMigration(args: {
+  db: Db;
+  logger: Logger;
+}): Promise<FlappingMigrationResult> {
+  const { db, logger } = args;
+
+  const rows = await db
+    .select({
+      id: schema.automations.id,
+      name: schema.automations.name,
+      status: schema.automations.status,
+      definition: schema.automations.definition,
+    })
+    .from(schema.automations);
+
+  let migrated = 0;
+  let triggersRewritten = 0;
+  // Enabled rows that STILL reference the dead event after the rewrite pass —
+  // i.e. the rewrite couldn't convert them (unparseable definition). These
+  // would never fire again, so they get a per-boot warning.
+  const leftover: string[] = [];
+
+  for (const row of rows) {
+    const outcome = rewriteFlappingTriggers(row.definition);
+    if (outcome.rewritten === 0) {
+      // Untouched: flag it only if it (still) points at the dead event while
+      // enabled — the rewrite found nothing to convert there.
+      const triggers = row.definition["triggers"];
+      if (
+        row.status === "enabled" &&
+        Array.isArray(triggers) &&
+        triggers.some((t) => asRecord(t)?.["event"] === LEGACY_FLAPPING_EVENT)
+      ) {
+        leftover.push(row.id);
+      }
+      continue;
+    }
+
+    await db
+      .update(schema.automations)
+      .set({ definition: outcome.definition, updatedAt: new Date() })
+      .where(eq(schema.automations.id, row.id));
+
+    migrated += 1;
+    triggersRewritten += outcome.rewritten;
+    logger.info(
+      `flapping migration: rewrote ${outcome.rewritten} flapping trigger(s) on automation ${row.id} (${row.name}) → windowed system_health_changed${
+        outcome.replacedFilter
+          ? "; a pre-existing trigger filter was replaced with the canonical unhealthy-transition filter"
+          : ""
+      }`,
+    );
+  }
+
+  if (leftover.length > 0) {
+    logger.warn(
+      `flapping migration: ${leftover.length} enabled automation(s) still reference the removed "${LEGACY_FLAPPING_EVENT}" event after migration and will not fire: ${leftover.join(
+        ", ",
+      )}`,
+    );
+  }
+
+  if (migrated > 0) {
+    logger.debug(
+      `flapping migration: migrated ${migrated} automation(s) (${triggersRewritten} trigger(s))`,
+    );
+  }
+  return { scanned: rows.length, migrated, triggersRewritten };
+}

package/src/router.test.ts

@@ -69,6 +69,7 @@ const sampleTrigger: TriggerDefinition<{ incidentId: string }> = {
   payloadSchema: samplePayloadSchema,
   hook: sampleHook,
   contextKey: (p) => p.incidentId,
+  contextKeyLabel: "incident",
 };
 
 const sampleAction: ActionDefinition<{ message: string }, { id: string }> = {
@@ -97,6 +98,7 @@ const sampleDefinition: AutomationDefinition = {
   conditions: [],
   actions: [],
   mode: "single",
+  concurrency_scope: "automation",
   max_runs: 10,
 };
 
@@ -117,6 +119,7 @@ function createInMemoryAutomationStore(): {
         id,
         name: input.name,
         description: input.description,
+        group: input.group,
         status: input.status,
         definition: input.definition,
         createdAt: now(),
@@ -132,6 +135,8 @@ function createInMemoryAutomationStore(): {
         ...existing,
         name: input.name ?? existing.name,
         description: input.description ?? existing.description,
+        // null clears, undefined leaves unchanged, string sets.
+        group: input.group === undefined ? existing.group : (input.group ?? undefined),
         status: input.status ?? existing.status,
         definition: input.definition ?? existing.definition,
         updatedAt: now(),
@@ -160,13 +165,20 @@ function createInMemoryAutomationStore(): {
       const limit = filter?.limit ?? 50;
       const offset = filter?.offset ?? 0;
       const all = [...rows.values()].filter(
-        (a) => !filter?.status || a.status === filter.status,
+        (a) =>
+          (!filter?.status || a.status === filter.status) &&
+          (!filter?.group || a.group === filter.group),
       );
       return {
         items: all.slice(offset, offset + limit),
         total: all.length,
       };
     },
+    async listGroups() {
+      const groups = new Set<string>();
+      for (const a of rows.values()) if (a.group) groups.add(a.group);
+      return [...groups].sort();
+    },
     async findEnabledByTriggerEvent() {
       return [];
     },
@@ -239,6 +251,7 @@ interface RouterHarness {
   signalService: MockSignalService;
   automationRows: Map<string, Automation>;
   db: ReturnType<typeof createMockDbForRouter>;
+  dispatchDeps: ReturnType<typeof makeDispatchDeps>["deps"];
 }
 
 function createMockDbForRouter() {
@@ -295,6 +308,7 @@ function makeRouter(): RouterHarness {
     signalService,
     automationRows,
     db,
+    dispatchDeps,
   };
 }
 
@@ -348,6 +362,56 @@ describe("Automation Router", () => {
       expect(res.total).toBe(1);
       expect(res.items[0]?.name).toBe("A");
     });
+
+    it("threads the group filter through to the store", async () => {
+      await h.automationStore.create({
+        name: "A",
+        group: "Alerting",
+        status: "enabled",
+        definition: sampleDefinition,
+      });
+      await h.automationStore.create({
+        name: "B",
+        group: "Networking",
+        status: "enabled",
+        definition: sampleDefinition,
+      });
+      const res = await call(
+        h.router.listAutomations,
+        { limit: 50, offset: 0, group: "Alerting" },
+        { context: h.context },
+      );
+      expect(res.total).toBe(1);
+      expect(res.items[0]?.name).toBe("A");
+    });
+  });
+
+  describe("listAutomationGroups", () => {
+    it("returns the distinct non-null group values", async () => {
+      await h.automationStore.create({
+        name: "A",
+        group: "Networking",
+        status: "enabled",
+        definition: sampleDefinition,
+      });
+      await h.automationStore.create({
+        name: "B",
+        group: "Alerting",
+        status: "enabled",
+        definition: sampleDefinition,
+      });
+      await h.automationStore.create({
+        name: "C",
+        status: "enabled",
+        definition: sampleDefinition,
+      });
+      const res = await call(
+        h.router.listAutomationGroups,
+        {},
+        { context: h.context },
+      );
+      expect(res.groups).toEqual(["Alerting", "Networking"]);
+    });
   });
 
   describe("getAutomation", () => {
@@ -521,6 +585,9 @@ describe("Automation Router", () => {
       expect(res.items).toHaveLength(1);
       expect(res.items[0]?.qualifiedId).toBe("test.incident.created");
       expect(res.items[0]?.payloadSchema).toBeDefined();
+      // contextKeyLabel flows through to the wire format for the editor's
+      // window "Partition by" default hint.
+      expect(res.items[0]?.contextKeyLabel).toBe("incident");
     });
   });
 
@@ -721,4 +788,118 @@ describe("Automation Router", () => {
       expect(typeof res.error?.column).toBe("number");
     });
   });
+
+  describe("testScript", () => {
+    it("runs a shell script against the flattened sample context", async () => {
+      const res = await call(
+        h.router.testScript,
+        {
+          kind: "shell",
+          script: 'echo "$CHECKSTACK_TRIGGER_PAYLOAD_ID"',
+          context: { trigger: { event: "incident.created", payload: { id: "INC-7" } } },
+          timeoutMs: 10_000,
+        },
+        { context: h.context },
+      );
+      expect(res.exitCode).toBe(0);
+      expect(res.stdout).toBe("INC-7");
+      expect(res.error).toBeUndefined();
+      expect(res.timedOut).toBe(false);
+    });
+
+    it("surfaces a non-zero shell exit code as an error", async () => {
+      const res = await call(
+        h.router.testScript,
+        { kind: "shell", script: "exit 3", timeoutMs: 10_000 },
+        { context: h.context },
+      );
+      expect(res.exitCode).toBe(3);
+      expect(res.error).toContain("exited with code 3");
+    });
+
+    it("runs a typescript script and returns its default export", async () => {
+      const res = await call(
+        h.router.testScript,
+        {
+          kind: "typescript",
+          script: "export default { ok: context.trigger.payload.id };",
+          context: { trigger: { event: "e", payload: { id: "INC-9" } } },
+          timeoutMs: 10_000,
+        },
+        { context: h.context },
+      );
+      expect(res.result).toEqual({ ok: "INC-9" });
+      expect(res.error).toBeUndefined();
+    });
+  });
+
+  describe("getRunScopeForReplay", () => {
+    it("reconstructs trigger + artifacts and reports snapshot availability", async () => {
+      // First select() → the run row; second select() → artifact rows.
+      const runRow = {
+        id: "run-1",
+        triggerEventId: "incident.incident.created",
+        triggerPayload: { id: "INC-7" },
+      };
+      const artifactRows = [
+        { artifactType: "jira.issue", actionId: "j", data: { key: "P-1" } },
+      ];
+      h.db.select = mock(() => fluentSelect([runRow]))
+        .mockImplementationOnce(() => fluentSelect([runRow]))
+        .mockImplementationOnce(() => fluentSelect(artifactRows));
+      h.dispatchDeps.runStateStore.load = mock(async () => ({
+        scopeSnapshot: { vars: { count: 2 } },
+        lastActionPath: null,
+        lastHeartbeatAt: new Date(),
+      }));
+
+      const res = await call(
+        h.router.getRunScopeForReplay,
+        { runId: "run-1" },
+        { context: h.context },
+      );
+
+      expect(res.context.trigger).toEqual({
+        event: "incident.incident.created",
+        payload: { id: "INC-7" },
+      });
+      expect(res.context.artifacts).toEqual({
+        "jira.issue": { key: "P-1" },
+        j: { key: "P-1" },
+      });
+      expect(res.context.var).toEqual({ count: 2 });
+      expect(res.scopeSnapshotAvailable).toBe(true);
+    });
+
+    it("reports scopeSnapshotAvailable=false when the run state is cleared", async () => {
+      const runRow = {
+        id: "run-2",
+        triggerEventId: "e",
+        triggerPayload: {},
+      };
+      h.db.select = mock(() => fluentSelect([runRow]))
+        .mockImplementationOnce(() => fluentSelect([runRow]))
+        .mockImplementationOnce(() => fluentSelect([]));
+      h.dispatchDeps.runStateStore.load = mock(async () => undefined);
+
+      const res = await call(
+        h.router.getRunScopeForReplay,
+        { runId: "run-2" },
+        { context: h.context },
+      );
+      expect(res.scopeSnapshotAvailable).toBe(false);
+      expect(res.context.var).toEqual({});
+    });
+
+    it("404s on an unknown run id", async () => {
+      h.db.select = mock(() => fluentSelect([]));
+      await expect(
+        call(
+          h.router.getRunScopeForReplay,
+          { runId: "missing" },
+          { context: h.context },
+        ),
+      ).rejects.toThrow(/not found/i);
+    });
+  });
 });

package/src/router.ts

@@ -43,6 +43,12 @@ import type { AutomationStore } from "./automation-store";
 import { dispatchTrigger } from "./dispatch/engine";
 import type { DispatchDeps } from "./dispatch/types";
 import { collectDefinitionIssues } from "./validate-definition";
+import {
+  resolveResolutionRootFromStore,
+  resolveScriptPackagesDir,
+} from "@checkstack/script-packages-backend";
+import { runScriptTest } from "./script-test";
+import { buildReplayContext } from "./script-test-replay";
 import * as schema from "./schema";
 
 interface RouterDeps {
@@ -140,8 +146,13 @@ export function createAutomationRouter(deps: RouterDeps) {
     // ─── Automations CRUD ────────────────────────────────────────────────
 
     listAutomations: os.listAutomations.handler(async ({ input }) => {
-      const { limit, offset, status } = input;
-      const result = await automationStore.list({ limit, offset, status });
+      const { limit, offset, status, group } = input;
+      const result = await automationStore.list({
+        limit,
+        offset,
+        status,
+        group,
+      });
       return {
         items: result.items,
         total: result.total,
@@ -150,6 +161,11 @@ export function createAutomationRouter(deps: RouterDeps) {
       };
     }),
 
+    listAutomationGroups: os.listAutomationGroups.handler(async () => {
+      const groups = await automationStore.listGroups();
+      return { groups };
+    }),
+
     getAutomation: os.getAutomation.handler(async ({ input }) => {
       const automation = await automationStore.getById(input.id);
       if (!automation) {
@@ -446,6 +462,7 @@ export function createAutomationRouter(deps: RouterDeps) {
           ownerPluginId: t.ownerPluginId,
           payloadSchema: t.payloadJsonSchema,
           configSchema: t.configJsonSchema,
+          contextKeyLabel: t.contextKeyLabel,
         }));
       return { items };
     }),
@@ -514,6 +531,60 @@ export function createAutomationRouter(deps: RouterDeps) {
       },
     ),
 
+    // ─── Inline script testing ───────────────────────────────────────────
+
+    testScript: os.testScript.handler(async ({ input }) => {
+      // Resolve the managed npm-package root from the local store so a test
+      // resolves the same allowlisted packages the real `run_script` action
+      // would (plan §4.1). Filesystem-only: ready when a tree is
+      // materialized, else unset. Execution safety is the runner's
+      // (auto-install disabled).
+      const status = await resolveResolutionRootFromStore(
+        resolveScriptPackagesDir(),
+      );
+      const resolutionRoot =
+        status.mode === "ready" ? status.root : undefined;
+      return runScriptTest({ input, deps: { resolutionRoot } });
+    }),
+
+    getRunScopeForReplay: os.getRunScopeForReplay.handler(async ({ input }) => {
+      const runRow = await db
+        .select()
+        .from(schema.automationRuns)
+        .where(eq(schema.automationRuns.id, input.runId))
+        .limit(1);
+      const run = runRow[0];
+      if (!run) {
+        throw new ORPCError("NOT_FOUND", {
+          message: `Run ${input.runId} not found`,
+        });
+      }
+
+      const [artifactRows, runState] = await Promise.all([
+        db
+          .select()
+          .from(schema.automationArtifacts)
+          .where(eq(schema.automationArtifacts.runId, input.runId))
+          .orderBy(asc(schema.automationArtifacts.createdAt)),
+        dispatchDeps.runStateStore.load(input.runId),
+      ]);
+
+      const context = buildReplayContext({
+        run: {
+          triggerEventId: run.triggerEventId,
+          triggerPayload: run.triggerPayload,
+        },
+        artifacts: artifactRows.map((row) => ({
+          artifactType: row.artifactType,
+          actionId: row.actionId,
+          data: row.data,
+        })),
+        scopeSnapshot: runState?.scopeSnapshot,
+      });
+
+      return { context, scopeSnapshotAvailable: runState !== undefined };
+    }),
+
     // ─── Template playground ─────────────────────────────────────────────
 
     renderTemplate: os.renderTemplate.handler(async ({ input }) => {