@checkstack/automation-backend 0.2.0

package/src/builtin-triggers.test.ts

@@ -0,0 +1,264 @@
+/**
+ * Behaviour tests for the built-in `time.cron`, `time.interval`, and
+ * `template` triggers.
+ *
+ * Each test exercises one factory, fakes out the queue, runs setup()
+ * to register a fire-callback in the module-scoped tick map, and then
+ * either (a) inspects the queue arguments, or (b) plays a tick through
+ * the recorded callback to verify the fire behaviour (including the
+ * template trigger's false → true edge detection).
+ */
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+import type { Logger } from "@checkstack/backend-api";
+import type { QueueManager } from "@checkstack/queue-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+import {
+  _resetBuiltinTriggerTickHandlersForTests,
+  BUILTIN_TRIGGER_QUEUE,
+  createTemplateTrigger,
+  createTimeCronTrigger,
+  createTimeIntervalTrigger,
+  registerBuiltinTriggerConsumer,
+  type BuiltinTriggerTickPayload,
+} from "./builtin-triggers";
+
+interface FakeJob {
+  id: string;
+  data: BuiltinTriggerTickPayload;
+  timestamp: Date;
+}
+
+function tick(jobId: string): FakeJob {
+  return {
+    id: jobId,
+    data: { jobId },
+    timestamp: new Date(),
+  };
+}
+
+const logger = createMockLogger() as Logger;
+
+interface QueueFixture {
+  queueManager: QueueManager;
+  scheduleMock: ReturnType<typeof mock>;
+  cancelMock: ReturnType<typeof mock>;
+  consumeMock: ReturnType<typeof mock>;
+  /** Last consumer registered via `queue.consume`. */
+  consumer?: (job: FakeJob) => Promise<void>;
+}
+
+function makeQueueFixture(): QueueFixture {
+  const fixture: QueueFixture = {
+    queueManager: undefined as never,
+    scheduleMock: mock(async (_payload: unknown, options: { jobId: string }) =>
+      options.jobId,
+    ),
+    cancelMock: mock(async (_jobId: string) => undefined),
+    consumeMock: mock(async () => undefined),
+  };
+  fixture.consumeMock = mock(
+    async (consumer: (job: FakeJob) => Promise<void>) => {
+      fixture.consumer = consumer;
+    },
+  );
+  const queue = {
+    scheduleRecurring: fixture.scheduleMock,
+    cancelRecurring: fixture.cancelMock,
+    consume: fixture.consumeMock,
+  };
+  fixture.queueManager = {
+    getQueue: () => queue,
+  } as unknown as QueueManager;
+  return fixture;
+}
+
+beforeEach(() => {
+  _resetBuiltinTriggerTickHandlersForTests();
+});
+
+describe("automation.cron", () => {
+  it("schedules a recurring cron job and fires on each tick", async () => {
+    const fx = makeQueueFixture();
+    await registerBuiltinTriggerConsumer({
+      queueManager: fx.queueManager,
+      logger,
+    });
+    const fired: Array<{ firedAt: string }> = [];
+    const fire = mock(async (payload: unknown) => {
+      fired.push(payload as { firedAt: string });
+    });
+
+    const trigger = createTimeCronTrigger({ queueManager: fx.queueManager });
+    const teardown = await trigger.setup!({
+      config: { cronPattern: "*/5 * * * *" },
+      identity: { automationId: "auto-1", triggerId: "t-1" },
+      fire,
+      logger,
+    });
+
+    expect(fx.scheduleMock).toHaveBeenCalledTimes(1);
+    const [scheduleData, scheduleOptions] = fx.scheduleMock.mock.calls[0] as [
+      BuiltinTriggerTickPayload,
+      { jobId: string; cronPattern?: string },
+    ];
+    expect(scheduleData.jobId).toBe("builtin:cron:auto-1:t-1");
+    expect(scheduleOptions.cronPattern).toBe("*/5 * * * *");
+
+    // The consumer was registered first; play a tick through it and
+    // confirm the fire-callback ran.
+    expect(fx.consumer).toBeDefined();
+    await fx.consumer!(tick("builtin:cron:auto-1:t-1"));
+    expect(fire).toHaveBeenCalledTimes(1);
+    expect(fired[0]?.firedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+
+    // Teardown cancels the recurring job + drops the handler.
+    await teardown();
+    expect(fx.cancelMock).toHaveBeenCalledWith("builtin:cron:auto-1:t-1");
+    await fx.consumer!(tick("builtin:cron:auto-1:t-1"));
+    // No additional fire after teardown — handler was removed.
+    expect(fire).toHaveBeenCalledTimes(1);
+  });
+
+  it("scopes the jobId by (automationId, triggerId)", async () => {
+    const fx = makeQueueFixture();
+    const trigger = createTimeCronTrigger({ queueManager: fx.queueManager });
+    const teardownA = await trigger.setup!({
+      config: { cronPattern: "0 * * * *" },
+      identity: { automationId: "auto-A", triggerId: "x" },
+      fire: mock(async () => {}),
+      logger,
+    });
+    const teardownB = await trigger.setup!({
+      config: { cronPattern: "0 * * * *" },
+      identity: { automationId: "auto-B", triggerId: "x" },
+      fire: mock(async () => {}),
+      logger,
+    });
+    const jobIds = fx.scheduleMock.mock.calls.map(
+      (c) => (c[1] as { jobId: string }).jobId,
+    );
+    expect(jobIds).toContain("builtin:cron:auto-A:x");
+    expect(jobIds).toContain("builtin:cron:auto-B:x");
+    await teardownA();
+    await teardownB();
+  });
+});
+
+describe("automation.interval", () => {
+  it("schedules a recurring interval job with a startDelay equal to the interval", async () => {
+    const fx = makeQueueFixture();
+    await registerBuiltinTriggerConsumer({
+      queueManager: fx.queueManager,
+      logger,
+    });
+    const fire = mock(async (_payload: unknown) => {});
+
+    const trigger = createTimeIntervalTrigger({
+      queueManager: fx.queueManager,
+    });
+    const teardown = await trigger.setup!({
+      config: { intervalSeconds: 30 },
+      identity: { automationId: "auto-1", triggerId: "t-1" },
+      fire,
+      logger,
+    });
+
+    const [, scheduleOptions] = fx.scheduleMock.mock.calls[0] as [
+      BuiltinTriggerTickPayload,
+      { jobId: string; intervalSeconds?: number; startDelay?: number },
+    ];
+    expect(scheduleOptions.intervalSeconds).toBe(30);
+    expect(scheduleOptions.startDelay).toBe(30);
+
+    await fx.consumer!(tick("builtin:interval:auto-1:t-1"));
+    expect(fire).toHaveBeenCalledTimes(1);
+
+    await teardown();
+  });
+});
+
+describe("automation.template", () => {
+  it("fires only on the false → true edge", async () => {
+    const fx = makeQueueFixture();
+    await registerBuiltinTriggerConsumer({
+      queueManager: fx.queueManager,
+      logger,
+    });
+    const fire = mock(async (_payload: unknown) => {});
+
+    // Use a template that toggles based on a flag in the closure.
+    // Since the trigger only has access to `{ now }`, we simulate the
+    // edge by switching the template via two separate setup calls.
+    const trigger = createTemplateTrigger({ queueManager: fx.queueManager });
+    const teardown = await trigger.setup!({
+      // Truthy from the start. We expect:
+      //  tick 1 → previousTruthy was false → fire.
+      //  tick 2 → previousTruthy is now true → no fire.
+      config: { value_template: "true", intervalSeconds: 5 },
+      identity: { automationId: "auto-1", triggerId: "t-1" },
+      fire,
+      logger,
+    });
+
+    await fx.consumer!(tick("builtin:template:auto-1:t-1"));
+    await fx.consumer!(tick("builtin:template:auto-1:t-1"));
+    expect(fire).toHaveBeenCalledTimes(1);
+
+    await teardown();
+  });
+
+  it("does not fire when the template is always falsy", async () => {
+    const fx = makeQueueFixture();
+    await registerBuiltinTriggerConsumer({
+      queueManager: fx.queueManager,
+      logger,
+    });
+    const fire = mock(async (_payload: unknown) => {});
+
+    const trigger = createTemplateTrigger({ queueManager: fx.queueManager });
+    const teardown = await trigger.setup!({
+      config: { value_template: "false", intervalSeconds: 5 },
+      identity: { automationId: "auto-1", triggerId: "t-1" },
+      fire,
+      logger,
+    });
+
+    await fx.consumer!(tick("builtin:template:auto-1:t-1"));
+    await fx.consumer!(tick("builtin:template:auto-1:t-1"));
+    expect(fire).not.toHaveBeenCalled();
+
+    await teardown();
+  });
+
+  it("rejects an invalid template at setup time", async () => {
+    const fx = makeQueueFixture();
+    const trigger = createTemplateTrigger({ queueManager: fx.queueManager });
+    await expect(
+      trigger.setup!({
+        config: { value_template: "((((", intervalSeconds: 5 },
+        identity: { automationId: "auto-1", triggerId: "t-1" },
+        fire: mock(async () => {}),
+        logger,
+      }),
+    ).rejects.toThrow(/invalid value_template/);
+    expect(fx.scheduleMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("builtin trigger consumer", () => {
+  it("logs but does not throw when a tick arrives without a registered handler", async () => {
+    const fx = makeQueueFixture();
+    await registerBuiltinTriggerConsumer({
+      queueManager: fx.queueManager,
+      logger,
+    });
+    await expect(
+      fx.consumer!(tick("builtin:cron:unregistered:nope")),
+    ).resolves.toBeUndefined();
+  });
+
+  it("uses the shared queue name", () => {
+    expect(BUILTIN_TRIGGER_QUEUE).toBe("automation-builtin-triggers");
+  });
+});

package/src/builtin-triggers.ts

@@ -0,0 +1,365 @@
+/**
+ * Built-in triggers shipped by automation-backend itself.
+ *
+ * Three triggers, all setup-backed (no plugin hook to subscribe to):
+ *
+ *   - `time.cron` — recurring queue job on a cron pattern.
+ *   - `time.interval` — recurring queue job on a fixed interval.
+ *   - `template` — interval-based polling; evaluates a template on each
+ *     tick and fires on the false → true edge (so an automation
+ *     subscribing on "value template is truthy" doesn't re-fire while
+ *     the value stays truthy).
+ *
+ * All three share the same two-stage runtime structure:
+ *
+ *   1. A single shared queue (`automation-builtin-triggers`) accepts
+ *      every recurring tick. A consumer registered at plugin init reads
+ *      the payload's `jobId` and dispatches to whichever fire-callback
+ *      was registered for that jobId.
+ *   2. `setup()` is invoked once per (automation, trigger-config) pair
+ *      by the standard trigger-subscriber machinery. It registers a
+ *      fire-callback in a module-scoped map and calls
+ *      `queue.scheduleRecurring(...)`; the matching teardown cancels
+ *      the recurring job and drops the map entry.
+ *
+ * Restart semantics work the same way regardless of the queue
+ * backend: `setupTriggerSubscriptions` re-runs every enabled
+ * automation's `setup()` during `afterPluginsReady` on every boot,
+ * and `setup()` calls `scheduleRecurring(...)` with a deterministic
+ * jobId. On a persistent queue (BullMQ/Redis), the second call is an
+ * in-place update of the surviving recurring job. On the in-memory
+ * queue — whose recurring-schedule map gets wiped at shutdown — it
+ * re-creates the schedule from scratch. Either way the schedule is
+ * back in place by the time the consumer would dispatch.
+ */
+import { z } from "zod";
+import type { Logger } from "@checkstack/backend-api";
+import type { QueueManager } from "@checkstack/queue-api";
+import type { PluginMetadata } from "@checkstack/common";
+import {
+  evaluateBoolean,
+  parseCondition,
+} from "@checkstack/template-engine";
+
+import type { TriggerDefinition } from "./action-types";
+
+// ─── Shared queue plumbing ─────────────────────────────────────────────
+
+export const BUILTIN_TRIGGER_QUEUE = "automation-builtin-triggers";
+const BUILTIN_TRIGGER_CONSUMER_GROUP = "automation-builtin-triggers-worker";
+
+export interface BuiltinTriggerTickPayload {
+  /**
+   * Stable identifier matching the recurring `jobId` so the consumer
+   * can route the tick to the right fire-callback.
+   */
+  jobId: string;
+}
+
+/**
+ * Module-scoped registry of `jobId` → tick handler. Populated by
+ * `setup()` on automation start, drained by the teardown returned
+ * from `setup()` on disable/delete.
+ *
+ * Scoped here (not under a `Map` in init's closure) so the queue
+ * consumer registered in init can look up the live entries.
+ */
+const tickHandlers = new Map<string, (logger: Logger) => Promise<void>>();
+
+export async function registerBuiltinTriggerConsumer(args: {
+  queueManager: QueueManager;
+  logger: Logger;
+}): Promise<void> {
+  const { queueManager, logger } = args;
+  const queue = queueManager.getQueue<BuiltinTriggerTickPayload>(
+    BUILTIN_TRIGGER_QUEUE,
+  );
+  await queue.consume(
+    async (job) => {
+      const handler = tickHandlers.get(job.data.jobId);
+      if (!handler) {
+        // Schedule may have outlived the trigger's setup — could
+        // happen across a restart while jobs flush. Logging is
+        // enough; the consumer keeps going.
+        logger.debug(
+          `Built-in trigger tick for ${job.data.jobId} has no registered handler — skipping`,
+        );
+        return;
+      }
+      await handler(logger);
+    },
+    {
+      consumerGroup: BUILTIN_TRIGGER_CONSUMER_GROUP,
+      // Time / template ticks are idempotent in spirit but a missed
+      // fire is preferable to a duplicate fire (operators wire
+      // mutation actions on these). Don't retry.
+      maxRetries: 0,
+    },
+  );
+}
+
+function buildJobId(args: {
+  kind: "cron" | "interval" | "template";
+  automationId: string;
+  triggerId: string;
+}): string {
+  return `builtin:${args.kind}:${args.automationId}:${args.triggerId}`;
+}
+
+// ─── time.cron ─────────────────────────────────────────────────────────
+
+const cronConfigSchema = z.object({
+  cronPattern: z
+    .string()
+    .min(1)
+    .describe("Cron expression — fires on each match (e.g. `*/5 * * * *`)"),
+});
+
+const timeTickPayloadSchema = z.object({
+  firedAt: z.string().describe("ISO timestamp of when the tick fired"),
+});
+
+export type TimeCronConfig = z.infer<typeof cronConfigSchema>;
+export type TimeTickPayload = z.infer<typeof timeTickPayloadSchema>;
+
+export interface BuiltinTriggerDeps {
+  queueManager: QueueManager;
+}
+
+export function createTimeCronTrigger(
+  deps: BuiltinTriggerDeps,
+): TriggerDefinition<TimeTickPayload, TimeCronConfig> {
+  return {
+    id: "cron",
+    displayName: "Cron Schedule",
+    description:
+      "Fires on a recurring cron pattern. Use for daily reports, periodic reconciliation, etc.",
+    category: "Time",
+    icon: "Clock",
+    payloadSchema: timeTickPayloadSchema,
+    configSchema: cronConfigSchema,
+    setup: async ({ config, identity, fire, logger }) => {
+      const jobId = buildJobId({
+        kind: "cron",
+        automationId: identity.automationId,
+        triggerId: identity.triggerId,
+      });
+      tickHandlers.set(jobId, async () => {
+        await fire({ firedAt: new Date().toISOString() });
+      });
+      const queue = deps.queueManager.getQueue<BuiltinTriggerTickPayload>(
+        BUILTIN_TRIGGER_QUEUE,
+      );
+      await queue.scheduleRecurring(
+        { jobId },
+        { jobId, cronPattern: config.cronPattern },
+      );
+      logger.debug(
+        `Scheduled time.cron trigger for automation ${identity.automationId}: ${config.cronPattern}`,
+      );
+      return async () => {
+        tickHandlers.delete(jobId);
+        await queue.cancelRecurring(jobId);
+      };
+    },
+  };
+}
+
+// ─── time.interval ─────────────────────────────────────────────────────
+
+const intervalConfigSchema = z.object({
+  intervalSeconds: z
+    .number()
+    .int()
+    .min(1)
+    .max(31_536_000)
+    .describe("Interval between fires, in seconds (1s – 1y)"),
+});
+
+export type TimeIntervalConfig = z.infer<typeof intervalConfigSchema>;
+
+export function createTimeIntervalTrigger(
+  deps: BuiltinTriggerDeps,
+): TriggerDefinition<TimeTickPayload, TimeIntervalConfig> {
+  return {
+    id: "interval",
+    displayName: "Interval",
+    description: "Fires on a fixed time interval (seconds).",
+    category: "Time",
+    icon: "Timer",
+    payloadSchema: timeTickPayloadSchema,
+    configSchema: intervalConfigSchema,
+    setup: async ({ config, identity, fire, logger }) => {
+      const jobId = buildJobId({
+        kind: "interval",
+        automationId: identity.automationId,
+        triggerId: identity.triggerId,
+      });
+      tickHandlers.set(jobId, async () => {
+        await fire({ firedAt: new Date().toISOString() });
+      });
+      const queue = deps.queueManager.getQueue<BuiltinTriggerTickPayload>(
+        BUILTIN_TRIGGER_QUEUE,
+      );
+      await queue.scheduleRecurring(
+        { jobId },
+        {
+          jobId,
+          intervalSeconds: config.intervalSeconds,
+          // Delay the first fire by the interval so an operator doesn't
+          // see a tick the instant they save the automation.
+          startDelay: config.intervalSeconds,
+        },
+      );
+      logger.debug(
+        `Scheduled time.interval trigger for automation ${identity.automationId}: every ${config.intervalSeconds}s`,
+      );
+      return async () => {
+        tickHandlers.delete(jobId);
+        await queue.cancelRecurring(jobId);
+      };
+    },
+  };
+}
+
+// ─── template ──────────────────────────────────────────────────────────
+
+const templateConfigSchema = z.object({
+  /**
+   * Boolean expression evaluated every tick — uses the template
+   * engine's condition grammar.
+   *
+   * The trigger context exposes `{ now }` (ISO string). Anything more
+   * elaborate should be reached via the standard automation `variables`
+   * block / action pipeline, not from the trigger itself — the
+   * tick frequency makes anything I/O-heavy in here costly.
+   */
+  value_template: z
+    .string()
+    .min(1)
+    .describe(
+      "Boolean template — fires on the false → true edge. Has access to `{ now }`.",
+    ),
+  intervalSeconds: z
+    .number()
+    .int()
+    .min(1)
+    .max(86_400)
+    .describe("How often to re-evaluate the template (1s – 24h)."),
+});
+
+const templateFiredPayloadSchema = z.object({
+  firedAt: z.string(),
+});
+
+export type TemplateConfig = z.infer<typeof templateConfigSchema>;
+export type TemplateFiredPayload = z.infer<typeof templateFiredPayloadSchema>;
+
+export function createTemplateTrigger(
+  deps: BuiltinTriggerDeps,
+): TriggerDefinition<TemplateFiredPayload, TemplateConfig> {
+  return {
+    id: "template",
+    displayName: "Template Condition",
+    description:
+      "Polls a boolean template on a fixed interval. Fires on the false → true edge so the automation runs once per truthy window, not on every tick.",
+    category: "Time",
+    icon: "FileCode",
+    payloadSchema: templateFiredPayloadSchema,
+    configSchema: templateConfigSchema,
+    setup: async ({ config, identity, fire, logger }) => {
+      const jobId = buildJobId({
+        kind: "template",
+        automationId: identity.automationId,
+        triggerId: identity.triggerId,
+      });
+      // Each tick lives in this closure — `previousTruthy` survives
+      // across ticks for the lifetime of the setup() return. Tearing
+      // down resets it via the map-removal.
+      let previousTruthy = false;
+      let parsed;
+      try {
+        parsed = parseCondition(config.value_template);
+      } catch (error) {
+        // A malformed expression should fail fast at setup so the
+        // operator sees the error in the editor rather than as
+        // silently-never-firing.
+        throw new Error(
+          `template trigger: invalid value_template — ${(error as Error).message}`,
+        );
+      }
+      tickHandlers.set(jobId, async (tickLogger) => {
+        const truthy = (() => {
+          try {
+            return evaluateBoolean(parsed!, { now: new Date().toISOString() });
+          } catch (error) {
+            tickLogger.warn(
+              `template trigger ${jobId} threw on evaluation — treating as false: ${(error as Error).message}`,
+            );
+            return false;
+          }
+        })();
+        if (truthy && !previousTruthy) {
+          await fire({ firedAt: new Date().toISOString() });
+        }
+        previousTruthy = truthy;
+      });
+      const queue = deps.queueManager.getQueue<BuiltinTriggerTickPayload>(
+        BUILTIN_TRIGGER_QUEUE,
+      );
+      await queue.scheduleRecurring(
+        { jobId },
+        {
+          jobId,
+          intervalSeconds: config.intervalSeconds,
+          startDelay: config.intervalSeconds,
+        },
+      );
+      logger.debug(
+        `Scheduled template trigger for automation ${identity.automationId}: every ${config.intervalSeconds}s`,
+      );
+      return async () => {
+        tickHandlers.delete(jobId);
+        await queue.cancelRecurring(jobId);
+      };
+    },
+  };
+}
+
+// ─── Public registry helper ────────────────────────────────────────────
+
+/**
+ * Construct all three built-in triggers and register them through the
+ * provided callback (which the automation-backend init phase passes
+ * straight into the trigger registry).
+ */
+export function registerBuiltinTriggers(args: {
+  queueManager: QueueManager;
+  pluginMetadata: PluginMetadata;
+  registerTrigger: (
+    trigger: TriggerDefinition<unknown, unknown>,
+    metadata: PluginMetadata,
+  ) => void;
+}): void {
+  const deps: BuiltinTriggerDeps = { queueManager: args.queueManager };
+  args.registerTrigger(
+    createTimeCronTrigger(deps) as unknown as TriggerDefinition<unknown, unknown>,
+    args.pluginMetadata,
+  );
+  args.registerTrigger(
+    createTimeIntervalTrigger(deps) as unknown as TriggerDefinition<unknown, unknown>,
+    args.pluginMetadata,
+  );
+  args.registerTrigger(
+    createTemplateTrigger(deps) as unknown as TriggerDefinition<unknown, unknown>,
+    args.pluginMetadata,
+  );
+}
+
+/**
+ * Test-only helper — exported so the test file can verify the
+ * module-scoped map is empty between test cases.
+ */
+export function _resetBuiltinTriggerTickHandlersForTests(): void {
+  tickHandlers.clear();
+}

package/src/dispatch/action-kind.ts

@@ -0,0 +1,44 @@
+import type { Action } from "@checkstack/automation-common";
+
+/**
+ * The action primitive discriminator kinds. Mirrors the keys in the
+ * Home-Assistant-style schema (`action`, `choose`, `parallel`, …).
+ *
+ * `sequence` is included so a list of actions can be wrapped as a single
+ * Action — primarily to support multi-action branches inside `parallel`.
+ */
+export type ActionKind =
+  | "action"
+  | "choose"
+  | "parallel"
+  | "delay"
+  | "repeat"
+  | "variables"
+  | "condition"
+  | "stop"
+  | "wait_for_trigger"
+  | "sequence";
+
+/**
+ * Decide which primitive an action is by inspecting which discriminator
+ * key it carries. The zod schema guarantees exactly one key is present
+ * across the union — this function relies on that contract.
+ */
+export function detectActionKind(action: Action): ActionKind {
+  const a = action as Record<string, unknown>;
+  if ("action" in a) return "action";
+  if ("choose" in a) return "choose";
+  if ("parallel" in a) return "parallel";
+  if ("delay" in a) return "delay";
+  if ("repeat" in a) return "repeat";
+  if ("variables" in a) return "variables";
+  if ("condition" in a) return "condition";
+  if ("stop" in a) return "stop";
+  if ("wait_for_trigger" in a) return "wait_for_trigger";
+  if ("sequence" in a) return "sequence";
+  throw new Error(
+    `Unknown action shape — none of the discriminator keys are present: ${JSON.stringify(
+      Object.keys(a),
+    )}`,
+  );
+}