@checkstack/automation-backend 0.2.0

package/src/dispatch/path-nav.ts

@@ -0,0 +1,65 @@
+/**
+ * Path navigation utilities for the action tree.
+ *
+ * Action paths are serialized as strings like
+ * `actions[1].choose[0].sequence[2]` and parsed back into structured
+ * `ActionPath` arrays.
+ */
+import type { ActionPath } from "./types";
+
+/**
+ * Parse a path string emitted by `formatActionPath`.
+ *
+ *   "actions[1].choose[0].sequence[2]"
+ *      → ["actions", 1, "choose", 0, "sequence", 2]
+ */
+export function parseActionPath(serialized: string): ActionPath {
+  const segments: Array<string | number> = [];
+  // Either a `word` (key segment) or `[42]` (index segment); the literal
+  // `.` separators between them are intentionally ignored.
+  const pattern = /([a-z_]+)|\[(\d+)\]/gi;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(serialized)) !== null) {
+    if (match[1] !== undefined) {
+      segments.push(match[1]);
+    } else if (match[2] !== undefined) {
+      segments.push(Number(match[2]));
+    }
+  }
+  return segments;
+}
+
+/**
+ * Detect whether a serialized path contains any container segment that
+ * is forbidden for `wait_for_trigger` / `delay` in v1.
+ *
+ * Waits and delays are supported in the top-level `actions:` list and
+ * inside any depth of nested `choose` branches. They are forbidden
+ * inside `parallel` and `repeat` because suspension semantics for those
+ * containers require branch-level coordination state which is deferred
+ * to a follow-up. Validation throws at edit time and the runtime
+ * rejects at execution time as a defence in depth.
+ */
+export function isSuspensionAllowedAtPath(path: ActionPath): boolean {
+  for (const segment of path) {
+    if (segment === "parallel" || segment === "repeat") return false;
+  }
+  return true;
+}
+
+/**
+ * Pop one container worth of segments off the end of the path.
+ *
+ * Used to walk back out after finishing a nested sequence: the dispatch
+ * engine knows the inner sequence is done, and asks the path util to
+ * give it the container's own path so it can find a sibling at that
+ * level.
+ *
+ *   ["actions", 1, "choose", 0, "sequence", 2]  →  ["actions", 1, "choose", 0]
+ *   ["actions", 1, "choose", 0]                 →  ["actions", 1]
+ */
+export function popContainer(path: ActionPath): ActionPath {
+  // Container segments come in pairs (key, index). We pop two at a time.
+  if (path.length < 2) return path;
+  return path.slice(0, -2);
+}

package/src/dispatch/render.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "bun:test";
+import {
+  createDefaultFilterRegistry,
+  type TemplateContext,
+} from "@checkstack/template-engine";
+import { renderConfig } from "./render";
+
+const filters = createDefaultFilterRegistry();
+const context: TemplateContext = {
+  trigger: { payload: { title: "Outage" } },
+};
+
+describe("renderConfig", () => {
+  it("renders {{ }} in ordinary fields", () => {
+    const out = renderConfig({
+      config: { message: "Incident {{ trigger.payload.title }} fired" },
+      jsonSchema: { properties: { message: { type: "string" } } },
+      context,
+      filters,
+    });
+    expect(out).toEqual({ message: "Incident Outage fired" });
+  });
+
+  it("leaves native-code fields (shell/typescript/javascript) un-rendered", () => {
+    const out = renderConfig({
+      config: {
+        script: 'echo "{{ trigger.payload.title }}"',
+        message: "hi {{ trigger.payload.title }}",
+      },
+      jsonSchema: {
+        properties: {
+          script: { "x-editor-types": ["shell"] },
+          message: { type: "string" },
+        },
+      },
+      context,
+      filters,
+    });
+    // The code field's template markers stay literal; the plain field renders.
+    expect(out).toEqual({
+      script: 'echo "{{ trigger.payload.title }}"',
+      message: "hi Outage",
+    });
+  });
+
+  it("treats typescript and javascript editor types as code too", () => {
+    const out = renderConfig({
+      config: { ts: "const x = {{ trigger.payload.title }};" },
+      jsonSchema: { properties: { ts: { "x-editor-types": ["typescript"] } } },
+      context,
+      filters,
+    });
+    expect(out).toEqual({ ts: "const x = {{ trigger.payload.title }};" });
+  });
+
+  it("falls back to plain rendering when no schema is supplied", () => {
+    const out = renderConfig({
+      config: { a: "{{ trigger.payload.title }}" },
+      jsonSchema: undefined,
+      context,
+      filters,
+    });
+    expect(out).toEqual({ a: "Outage" });
+  });
+
+  it("passes non-object config straight through the renderer", () => {
+    const out = renderConfig({
+      config: "{{ trigger.payload.title }}",
+      jsonSchema: undefined,
+      context,
+      filters,
+    });
+    expect(out).toBe("Outage");
+  });
+});

package/src/dispatch/render.ts

@@ -0,0 +1,136 @@
+/**
+ * Recursive template rendering for action `config` objects.
+ *
+ * Action configs are arbitrary JSON: strings, numbers, booleans, arrays,
+ * objects. Strings may carry `{{ }}` interpolation that should be
+ * rendered against the current scope. This helper walks the object tree
+ * and renders every string value in place, leaving non-strings alone.
+ *
+ * Errors from individual templates surface up — the dispatch engine
+ * catches and converts them into a failed step.
+ */
+import {
+  evaluate as evaluateExpression,
+  parseCondition,
+  parseTemplate,
+  render as renderTemplate,
+  type FilterRegistry,
+  type TemplateContext,
+} from "@checkstack/template-engine";
+
+/**
+ * Editor-type tags that denote a native-code field. Such fields are
+ * passed through verbatim by {@link renderConfig} — their `{{ }}`, if
+ * any, is NOT expanded, because script actions read run data from the
+ * typed `context` (TS) or injected env vars (shell), not from templates.
+ */
+const CODE_EDITOR_TYPES = new Set(["shell", "typescript", "javascript"]);
+
+/**
+ * Narrow an unknown JSON value to a string-keyed record after a runtime
+ * type check. The single cast is the canonical safe-narrowing pattern —
+ * JSON schemas arrive as `Record<string, unknown>`, so reading nested
+ * shape requires asserting the post-check type.
+ */
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function hasCodeEditorType(propSchema: unknown): boolean {
+  const types = asRecord(propSchema)["x-editor-types"];
+  return (
+    Array.isArray(types) &&
+    types.some((t) => typeof t === "string" && CODE_EDITOR_TYPES.has(t))
+  );
+}
+
+/**
+ * Render an action's top-level `config`, skipping native-code fields.
+ *
+ * Identical to {@link renderValue} for every field EXCEPT those whose
+ * JSON schema declares an `x-editor-types` of `shell` / `typescript` /
+ * `javascript`: those are returned verbatim so any `{{ }}` stays literal.
+ * This removes the deprecated "templates inside a code field" path so it
+ * can't be used by accident — code fields get run data via `context` /
+ * env vars instead. Falls back to {@link renderValue} when the config
+ * isn't a plain object or no schema is available.
+ */
+export function renderConfig(args: {
+  config: unknown;
+  jsonSchema: Record<string, unknown> | undefined;
+  context: TemplateContext;
+  filters: FilterRegistry;
+}): unknown {
+  const { config, jsonSchema, context, filters } = args;
+  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+    return renderValue(config, context, filters);
+  }
+  const properties = asRecord(jsonSchema?.["properties"]);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(asRecord(config))) {
+    out[key] = hasCodeEditorType(properties[key])
+      ? value
+      : renderValue(value, context, filters);
+  }
+  return out;
+}
+
+/**
+ * Render any value, recursing into objects and arrays. Strings are
+ * passed through the template engine; everything else is returned as-is.
+ */
+export function renderValue(
+  value: unknown,
+  context: TemplateContext,
+  filters: FilterRegistry,
+): unknown {
+  if (typeof value === "string") {
+    return renderString(value, context, filters);
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => renderValue(v, context, filters));
+  }
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = renderValue(v, context, filters);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Render a single string template. If the string contains no `{{`
+ * markers, this is effectively a passthrough (the template engine
+ * tokenises trivial cases very cheaply).
+ *
+ * For pure expressions like `"{{ count + 1 }}"` the renderer returns a
+ * stringified value — callers that need the typed primitive should use
+ * `renderExpression` instead.
+ */
+export function renderString(
+  template: string,
+  context: TemplateContext,
+  filters: FilterRegistry,
+): string {
+  if (!template.includes("{{")) return template;
+  return renderTemplate(parseTemplate(template), context, { filters });
+}
+
+/**
+ * Evaluate an expression and return the raw (un-stringified) value.
+ *
+ * Use this when the dispatched action's schema expects a typed primitive
+ * (e.g. `delay: { seconds: "{{ trigger.payload.retryAfter }}" }` — the
+ * action expects a number, not a string).
+ */
+export function renderExpression(
+  source: string,
+  context: TemplateContext,
+  filters: FilterRegistry,
+): unknown {
+  return evaluateExpression(parseCondition(source), context, { filters });
+}

package/src/dispatch/run-state-store.ts

@@ -0,0 +1,143 @@
+/**
+ * Drizzle-backed durable scope + heartbeat persistence and Postgres
+ * advisory-lock helpers for the dispatch engine.
+ *
+ * Scope snapshots are written after every successful step so a future
+ * process can resume the run exactly where the prior process left off.
+ * Heartbeats let the stalled-run sweeper distinguish healthy in-flight
+ * runs from runs whose host crashed mid-execution.
+ *
+ * Advisory locks ensure at most one instance is executing a given run
+ * at a time. The lock auto-releases when the holding connection dies —
+ * exactly what we want during crash recovery.
+ */
+import { lt, eq, sql } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+
+import { automationRunState } from "../schema";
+
+export interface RunStateSnapshot {
+  scopeSnapshot: Record<string, unknown>;
+  lastActionPath: string | null;
+  lastHeartbeatAt: Date;
+}
+
+export interface RunStateStore {
+  /**
+   * Write or update the per-run durable state. `lastActionPath` is the
+   * path of the most recently completed action — resume walks the tree
+   * looking for this path and treats the action at it as already done.
+   */
+  upsert(input: {
+    runId: string;
+    scopeSnapshot: Record<string, unknown>;
+    lastActionPath: string | null;
+  }): Promise<void>;
+
+  load(runId: string): Promise<RunStateSnapshot | undefined>;
+
+  /** Drop the state row — done at terminal run status. */
+  clear(runId: string): Promise<void>;
+
+  /** Bump only the heartbeat. Used by long-running container handlers. */
+  heartbeat(runId: string): Promise<void>;
+
+  /**
+   * Run ids whose heartbeat is older than `threshold`. Returned in
+   * heartbeat-ascending order so the sweeper processes the most
+   * stale first.
+   */
+  findStalledRunIds(threshold: Date): Promise<string[]>;
+
+  /**
+   * Try to acquire a Postgres session-level advisory lock for the run.
+   * Returns true on acquisition. The lock auto-releases when the holding
+   * DB session closes (e.g. on process crash), so dead instances don't
+   * leak locks.
+   */
+  tryAdvisoryLock(runId: string): Promise<boolean>;
+
+  /** Release a previously-acquired advisory lock. */
+  releaseAdvisoryLock(runId: string): Promise<void>;
+}
+
+type Schema = { automationRunState: typeof automationRunState };
+
+export function createRunStateStore(
+  db: SafeDatabase<Schema>,
+): RunStateStore {
+  return {
+    async upsert(input) {
+      await db
+        .insert(automationRunState)
+        .values({
+          runId: input.runId,
+          scopeSnapshot: input.scopeSnapshot,
+          lastActionPath: input.lastActionPath,
+        })
+        .onConflictDoUpdate({
+          target: automationRunState.runId,
+          set: {
+            scopeSnapshot: input.scopeSnapshot,
+            lastActionPath: input.lastActionPath,
+            lastHeartbeatAt: new Date(),
+            updatedAt: new Date(),
+          },
+        });
+    },
+
+    async load(runId) {
+      const rows = await db
+        .select()
+        .from(automationRunState)
+        .where(eq(automationRunState.runId, runId))
+        .limit(1);
+      const row = rows[0];
+      if (!row) return;
+      return {
+        scopeSnapshot: row.scopeSnapshot,
+        lastActionPath: row.lastActionPath,
+        lastHeartbeatAt: row.lastHeartbeatAt,
+      };
+    },
+
+    async clear(runId) {
+      await db
+        .delete(automationRunState)
+        .where(eq(automationRunState.runId, runId));
+    },
+
+    async heartbeat(runId) {
+      await db
+        .update(automationRunState)
+        .set({ lastHeartbeatAt: new Date() })
+        .where(eq(automationRunState.runId, runId));
+    },
+
+    async findStalledRunIds(threshold) {
+      const rows = await db
+        .select({ runId: automationRunState.runId })
+        .from(automationRunState)
+        .where(lt(automationRunState.lastHeartbeatAt, threshold))
+        .orderBy(automationRunState.lastHeartbeatAt);
+      return rows.map((r) => r.runId);
+    },
+
+    async tryAdvisoryLock(runId) {
+      // hashtextextended returns int8 in Postgres, which pg_try_advisory_lock
+      // accepts directly. Using a deterministic hash means the same runId
+      // always maps to the same lock key across processes.
+      const result = await db.execute<{ ok: boolean }>(sql`
+        SELECT pg_try_advisory_lock(hashtextextended(${runId}, 0)) AS ok
+      `);
+      const rows = result as unknown as { rows: Array<{ ok: boolean }> };
+      return Boolean(rows.rows?.[0]?.ok);
+    },
+
+    async releaseAdvisoryLock(runId) {
+      await db.execute(sql`
+        SELECT pg_advisory_unlock(hashtextextended(${runId}, 0))
+      `);
+    },
+  };
+}