@synap-core/workspace-templates 0.9.1 → 0.9.3

package/src/validate-flow.ts

@@ -0,0 +1,555 @@
+/**
+ * Node-contract validation for automation flow definitions.
+ *
+ * The persist doors and the install/apply doors validate flow SHAPE only
+ * (`{ nodes: [], edges: [] }`). A semantically-broken flow — a `channel_message`
+ * output with a typo'd `channelType`, a `capability` node with no `verbId`, an
+ * edge to a nonexistent node, a cycle, an unknown `node.type` — passes the shape
+ * check and only fails at RUNTIME (automation-executor.ts throws mid-run). For a
+ * template automation this is worse: it validates green at author time and then
+ * SILENTLY never fires on a live pod.
+ *
+ * `validateFlowDefinition` closes that gap: a PURE, synchronous, DB-free function
+ * that rejects malformed flows with actionable per-node errors. It is called by
+ * `validateTemplate` (this package) so `synap market validate` / the build gate /
+ * the CP publish door all run the same contract check, and by the pod's persist
+ * doors.
+ *
+ * ── SSOT-IN-WAITING — temporary duplicate ────────────────────────────────────
+ * This is a PURE copy of synap-backend's
+ * `packages/api/src/services/automations/validate-flow.ts` (the current runtime
+ * SSOT, which carries the `@synap/database` COMPILE-TIME drift guard). This copy
+ * exists so `validateTemplate` — which runs in THIS published, backend-independent
+ * package (CLI `synap market validate` / build gate / CP publish) — can catch
+ * broken automation flows at AUTHOR time. It is intentionally free of any
+ * `@synap/database` import (this package depends only on zod + js-yaml), so the
+ * compile-time drift guard cannot live here; it stays in backend.
+ *
+ * The two copies are kept byte-identical (logic) by `validate-flow.drift.test.ts`
+ * in this package, which reads BOTH files and fails if they diverge.
+ *
+ * CUTOVER (collapse to ONE SSOT): publish `@synap-core/workspace-templates`, bump
+ * synap-backend (`^0.7.1`) and CP (`^0.9.2`) deps to that version, then replace
+ * backend's validate-flow.ts body with a re-export FROM HERE (keeping backend's
+ * `AssertExact` guard binding these arrays to the `@synap/database` unions).
+ * Until then: keep the constant arrays below identical to `@synap/database`
+ * `schema/automations.ts`.
+ */
+
+// ── Contract constants (mirror @synap/database schema/automations.ts) ─────────
+
+/** The 21 node types — `AutomationNodeBase.type` union (schema/automations.ts). */
+export const FLOW_NODE_TYPES = [
+  "trigger",
+  "command",
+  "condition",
+  "delay",
+  "output",
+  "loop",
+  "transform",
+  "fetch",
+  "query",
+  "entity_read",
+  "related_entities",
+  "guard",
+  "compute",
+  "select",
+  "claim",
+  "messages_query",
+  "switch",
+  "skill",
+  "capability",
+  "sub_automation",
+  "playbook_run",
+] as const;
+
+/** The 11 output types — `OutputNodeDef.data.outputType` (schema/automations.ts). */
+export const FLOW_OUTPUT_TYPES = [
+  "notification",
+  "entity_create",
+  "entity_update",
+  "facet_attach",
+  "facet_update",
+  "facet_detach",
+  "relation_create",
+  "webhook",
+  "channel_message",
+  "session_update",
+  "set_state",
+] as const;
+
+/**
+ * The known `config.channelType` values for a `channel_message` output. Mirrors
+ * the executor's channel_message resolution (automation-executor.ts). The output
+ * channel is CONTEXT-DERIVED — a channel_message is valid with `channelId`, OR
+ * `channelEntityRef` (an entity-id expression → that entity's internal channel),
+ * OR a `channelType` from this set, OR NOTHING (the executor defaults a targetless
+ * channel_message to the automation's own run channel). A `channelType` that is
+ * PRESENT but not one of these is still a typo → still an error.
+ */
+export const CHANNEL_MESSAGE_CHANNEL_TYPES = [
+  "personal_thread",
+  "proactive",
+  "subjectEntity",
+] as const;
+
+const NODE_TYPE_SET = new Set<string>(FLOW_NODE_TYPES);
+const OUTPUT_TYPE_SET = new Set<string>(FLOW_OUTPUT_TYPES);
+const CHANNEL_TYPE_SET = new Set<string>(CHANNEL_MESSAGE_CHANNEL_TYPES);
+
+// ── Result / error types ──────────────────────────────────────────────────────
+
+export interface FlowValidationError {
+  /** Node the error is about (absent for graph-level / edge-level errors). */
+  nodeId?: string;
+  /** Edge the error is about (for dangling-reference / bad-handle errors). */
+  edgeId?: string;
+  /** Stable machine code — see the `code` literals below. */
+  code: string;
+  /** Human-actionable message naming what is wrong and how to fix it. */
+  message: string;
+}
+
+export interface FlowValidationResult {
+  valid: boolean;
+  errors: FlowValidationError[];
+}
+
+/**
+ * Optional catalog resolvers. When provided, existence checks run; when omitted,
+ * those checks are SKIPPED (structural + contract checks always run). Kept
+ * synchronous so the whole function stays pure — the caller pre-loads whatever
+ * it needs and passes predicates.
+ */
+export interface FlowValidationResolvers {
+  /** Does this capability verb (skill name) exist in the workspace catalog? */
+  verbExists?: (verbId: string) => boolean;
+  /** Does the referenced skill exist (by id OR by name)? */
+  skillExists?: (ref: { skillId?: string; skillName?: string }) => boolean;
+  /** Does the referenced playbook exist? */
+  playbookExists?: (ref: {
+    playbookId?: string;
+    playbookName?: string;
+  }) => boolean;
+}
+
+// ── Loose input shapes (the flow arrives as untyped JSON at the door) ──────────
+
+interface LooseNode {
+  id?: unknown;
+  type?: unknown;
+  data?: unknown;
+}
+interface LooseEdge {
+  id?: unknown;
+  source?: unknown;
+  target?: unknown;
+  sourceHandle?: unknown;
+}
+interface LooseFlow {
+  nodes?: unknown;
+  edges?: unknown;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function nonEmptyString(v: unknown): v is string {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+// ── The validator ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate an automation flow definition against the node contract.
+ * Pure and synchronous. `resolvers` gate the catalog-existence checks only.
+ */
+export function validateFlowDefinition(
+  flow: unknown,
+  resolvers?: FlowValidationResolvers
+): FlowValidationResult {
+  const errors: FlowValidationError[] = [];
+
+  // ── Shape ───────────────────────────────────────────────────────────────────
+  if (!isRecord(flow)) {
+    return {
+      valid: false,
+      errors: [
+        {
+          code: "flow_not_object",
+          message:
+            "flowDefinition must be an object with `nodes` and `edges` arrays.",
+        },
+      ],
+    };
+  }
+  const f = flow as LooseFlow;
+  if (!Array.isArray(f.nodes)) {
+    errors.push({
+      code: "nodes_not_array",
+      message: "flowDefinition.nodes must be an array.",
+    });
+  }
+  if (!Array.isArray(f.edges)) {
+    errors.push({
+      code: "edges_not_array",
+      message: "flowDefinition.edges must be an array.",
+    });
+  }
+  // Can't do node/edge checks without the arrays.
+  if (errors.length > 0) return { valid: false, errors };
+
+  const nodes = (f.nodes as unknown[]).map((n) =>
+    isRecord(n) ? n : {}
+  ) as LooseNode[];
+  const edges = (f.edges as unknown[]).map((e) =>
+    isRecord(e) ? e : {}
+  ) as LooseEdge[];
+
+  // ── Node ids: present, string, unique ─────────────────────────────────────────
+  const nodeIds = new Set<string>();
+  const seenIds = new Set<string>();
+  nodes.forEach((node, idx) => {
+    if (!nonEmptyString(node.id)) {
+      errors.push({
+        code: "node_missing_id",
+        message: `Node at index ${idx} is missing a non-empty string \`id\`.`,
+      });
+      return;
+    }
+    if (seenIds.has(node.id)) {
+      errors.push({
+        nodeId: node.id,
+        code: "duplicate_node_id",
+        message: `Duplicate node id "${node.id}" — every node id must be unique.`,
+      });
+      return;
+    }
+    seenIds.add(node.id);
+    nodeIds.add(node.id);
+  });
+
+  // ── Per-node type + contract ──────────────────────────────────────────────────
+  const nodesById = new Map<string, LooseNode>();
+  for (const node of nodes) {
+    if (nonEmptyString(node.id)) nodesById.set(node.id, node);
+
+    const nodeId = nonEmptyString(node.id) ? node.id : undefined;
+
+    // node.type ∈ the union
+    if (!nonEmptyString(node.type) || !NODE_TYPE_SET.has(node.type)) {
+      errors.push({
+        nodeId,
+        code: "unknown_node_type",
+        message: `Node ${nodeId ? `"${nodeId}"` : `at index ?`} has ${
+          nonEmptyString(node.type) ? `unknown type "${node.type}"` : "no type"
+        }. Must be one of: ${FLOW_NODE_TYPES.join(", ")}.`,
+      });
+      continue; // contract checks below are type-specific
+    }
+
+    const type = node.type;
+    const data = isRecord(node.data) ? node.data : {};
+
+    switch (type) {
+      case "capability": {
+        if (!nonEmptyString(data.verbId)) {
+          errors.push({
+            nodeId,
+            code: "capability_missing_verbId",
+            message: `Capability node "${nodeId}" has no \`verbId\`. Pick a verb on the selected tool.`,
+          });
+        } else if (
+          resolvers?.verbExists &&
+          !resolvers.verbExists(data.verbId)
+        ) {
+          errors.push({
+            nodeId,
+            code: "capability_unknown_verbId",
+            message: `Capability node "${nodeId}" references verb "${data.verbId}", which is not in the capability catalog.`,
+          });
+        }
+        break;
+      }
+
+      case "skill": {
+        // Accept `skillId` OR `skillName` — the template-friendly form (mirrors
+        // playbook_run's id-OR-name): a capability seeds a skill + an automation
+        // that references it by its stable name, since the runtime id isn't known
+        // at author time. The create door resolves skillName → skillId pre-insert.
+        const skillId = nonEmptyString(data.skillId) ? data.skillId : undefined;
+        const skillName = nonEmptyString(data.skillName)
+          ? data.skillName
+          : undefined;
+        if (!skillId && !skillName) {
+          errors.push({
+            nodeId,
+            code: "skill_missing_ref",
+            message: `Skill node "${nodeId}" has neither \`skillId\` nor \`skillName\`. One is required.`,
+          });
+        } else if (
+          resolvers?.skillExists &&
+          !resolvers.skillExists({ skillId, skillName })
+        ) {
+          errors.push({
+            nodeId,
+            code: "skill_unknown_ref",
+            message: `Skill node "${nodeId}" references a skill (${
+              skillId ? `id "${skillId}"` : `name "${skillName}"`
+            }) that does not exist.`,
+          });
+        }
+        break;
+      }
+
+      case "playbook_run": {
+        const playbookId = nonEmptyString(data.playbookId)
+          ? data.playbookId
+          : undefined;
+        const playbookName = nonEmptyString(data.playbookName)
+          ? data.playbookName
+          : undefined;
+        if (!playbookId && !playbookName) {
+          errors.push({
+            nodeId,
+            code: "playbook_run_missing_ref",
+            message: `Playbook-run node "${nodeId}" has neither \`playbookId\` nor \`playbookName\`. One is required.`,
+          });
+        } else if (
+          resolvers?.playbookExists &&
+          !resolvers.playbookExists({ playbookId, playbookName })
+        ) {
+          errors.push({
+            nodeId,
+            code: "playbook_run_unknown_ref",
+            message: `Playbook-run node "${nodeId}" references a playbook (${
+              playbookId ? `id "${playbookId}"` : `name "${playbookName}"`
+            }) that does not exist.`,
+          });
+        }
+        break;
+      }
+
+      case "output": {
+        const outputType = data.outputType;
+        if (!nonEmptyString(outputType) || !OUTPUT_TYPE_SET.has(outputType)) {
+          errors.push({
+            nodeId,
+            code: "output_bad_outputType",
+            message: `Output node "${nodeId}" has ${
+              nonEmptyString(outputType)
+                ? `unknown outputType "${outputType}"`
+                : "no outputType"
+            }. Must be one of: ${FLOW_OUTPUT_TYPES.join(", ")}.`,
+          });
+          break;
+        }
+        // channel_message target is CONTEXT-DERIVED: valid with channelId,
+        // channelEntityRef, a known channelType, OR nothing (executor defaults a
+        // targetless channel_message to the automation's own run channel). Only a
+        // channelType that is PRESENT but unknown is an error (a typo'd type).
+        if (outputType === "channel_message") {
+          const config = isRecord(data.config) ? data.config : {};
+          const channelType = config.channelType;
+          if (channelType !== undefined && channelType !== null) {
+            if (
+              !nonEmptyString(channelType) ||
+              !CHANNEL_TYPE_SET.has(channelType)
+            ) {
+              errors.push({
+                nodeId,
+                code: "channel_message_unknown_channelType",
+                message: `Channel-message output "${nodeId}" has unknown channelType ${
+                  nonEmptyString(channelType)
+                    ? `"${channelType}"`
+                    : JSON.stringify(channelType)
+                }. Use one of: ${CHANNEL_MESSAGE_CHANNEL_TYPES.join(
+                  ", "
+                )}, or set \`config.channelEntityRef\`/\`config.channelId\`, or omit the target to post to the automation's own run channel.`,
+              });
+            }
+          }
+        }
+        break;
+      }
+
+      case "loop": {
+        if (!nonEmptyString(data.iteratorExpression)) {
+          errors.push({
+            nodeId,
+            code: "loop_missing_iterator",
+            message: `Loop node "${nodeId}" has no \`iteratorExpression\` (the items to iterate, e.g. "steps.query.output.entities").`,
+          });
+        }
+        break;
+      }
+
+      case "condition": {
+        if (!nonEmptyString(data.expression)) {
+          errors.push({
+            nodeId,
+            code: "condition_missing_expression",
+            message: `Condition node "${nodeId}" has no \`expression\` (the predicate to evaluate).`,
+          });
+        }
+        break;
+      }
+
+      case "switch": {
+        if (!nonEmptyString(data.expression)) {
+          errors.push({
+            nodeId,
+            code: "switch_missing_expression",
+            message: `Switch node "${nodeId}" has no \`expression\` (the value to match against cases).`,
+          });
+        }
+        if (!Array.isArray(data.cases) || data.cases.length === 0) {
+          errors.push({
+            nodeId,
+            code: "switch_missing_cases",
+            message: `Switch node "${nodeId}" has no \`cases\`. Add at least one case with a \`value\`.`,
+          });
+        }
+        break;
+      }
+    }
+  }
+
+  // ── Edges: source/target reference existing nodes ─────────────────────────────
+  edges.forEach((edge, idx) => {
+    const edgeId = nonEmptyString(edge.id) ? edge.id : undefined;
+    const label = edgeId ? `"${edgeId}"` : `at index ${idx}`;
+    if (!nonEmptyString(edge.source) || !nodeIds.has(edge.source)) {
+      errors.push({
+        edgeId,
+        code: "edge_bad_source",
+        message: `Edge ${label} has ${
+          nonEmptyString(edge.source)
+            ? `source "${edge.source}" which is not a node in this flow`
+            : "no source node"
+        }.`,
+      });
+    }
+    if (!nonEmptyString(edge.target) || !nodeIds.has(edge.target)) {
+      errors.push({
+        edgeId,
+        code: "edge_bad_target",
+        message: `Edge ${label} has ${
+          nonEmptyString(edge.target)
+            ? `target "${edge.target}" which is not a node in this flow`
+            : "no target node"
+        }.`,
+      });
+    }
+  });
+
+  // ── Edge handles: condition → yes/no, switch → a declared case value ──────────
+  for (const edge of edges) {
+    if (!nonEmptyString(edge.source) || !nodesById.has(edge.source)) continue;
+    if (edge.sourceHandle === undefined || edge.sourceHandle === null) continue;
+    if (!nonEmptyString(edge.sourceHandle)) continue;
+    const src = nodesById.get(edge.source)!;
+    const edgeId = nonEmptyString(edge.id) ? edge.id : undefined;
+    if (src.type === "condition") {
+      if (edge.sourceHandle !== "yes" && edge.sourceHandle !== "no") {
+        errors.push({
+          edgeId,
+          nodeId: edge.source,
+          code: "condition_bad_handle",
+          message: `Edge from condition "${edge.source}" has sourceHandle "${edge.sourceHandle}" — must be "yes" or "no".`,
+        });
+      }
+    } else if (src.type === "switch") {
+      const data = isRecord(src.data) ? src.data : {};
+      const caseValues = Array.isArray(data.cases)
+        ? data.cases
+            .map((c) => (isRecord(c) ? c.value : undefined))
+            .filter((v): v is string => typeof v === "string")
+        : [];
+      if (!caseValues.includes(edge.sourceHandle)) {
+        errors.push({
+          edgeId,
+          nodeId: edge.source,
+          code: "switch_bad_handle",
+          message: `Edge from switch "${edge.source}" has sourceHandle "${edge.sourceHandle}", which matches no declared case value (${
+            caseValues.length ? caseValues.join(", ") : "none declared"
+          }).`,
+        });
+      }
+    }
+  }
+
+  // ── Acyclic (Kahn's algorithm — mirrors topoSort in automation-executor.ts) ───
+  // Only run when edges reference real nodes; dangling edges are already reported
+  // and would corrupt the in-degree bookkeeping.
+  const cyclic = detectCycle(nodeIds, edges);
+  if (cyclic.length > 0) {
+    errors.push({
+      code: "flow_has_cycle",
+      message: `Flow has a cycle — these nodes cannot be ordered and would never run: ${cyclic.join(
+        ", "
+      )}. Remove the back-edge(s) so the graph is acyclic.`,
+    });
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Return the set of node ids that participate in a cycle (empty if acyclic).
+ * Kahn's algorithm — the same ordering the executor's `topoSort` relies on; a
+ * cycle is exactly the nodes whose in-degree never reaches zero. Edges whose
+ * endpoints aren't real nodes are ignored (those are reported separately).
+ */
+function detectCycle(nodeIds: Set<string>, edges: LooseEdge[]): string[] {
+  const inDegree = new Map<string, number>();
+  const adjacency = new Map<string, string[]>();
+  for (const id of nodeIds) {
+    inDegree.set(id, 0);
+    adjacency.set(id, []);
+  }
+  for (const edge of edges) {
+    const source = nonEmptyString(edge.source) ? edge.source : undefined;
+    const target = nonEmptyString(edge.target) ? edge.target : undefined;
+    if (!source || !target) continue;
+    if (!nodeIds.has(source) || !nodeIds.has(target)) continue;
+    adjacency.get(source)!.push(target);
+    inDegree.set(target, (inDegree.get(target) ?? 0) + 1);
+  }
+  const queue: string[] = [];
+  for (const [id, degree] of inDegree) if (degree === 0) queue.push(id);
+  let visited = 0;
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    visited++;
+    for (const target of adjacency.get(id) ?? []) {
+      const next = (inDegree.get(target) ?? 1) - 1;
+      inDegree.set(target, next);
+      if (next === 0) queue.push(target);
+    }
+  }
+  if (visited === nodeIds.size) return [];
+  // The remaining nodes (in-degree > 0 after Kahn drain) are the cycle members.
+  const cyclic: string[] = [];
+  for (const [id, degree] of inDegree) if (degree > 0) cyclic.push(id);
+  return cyclic;
+}
+
+/**
+ * Convenience helper for the persist doors: run the validator and, if invalid,
+ * return a single joined actionable message (else null). Keeps the door code a
+ * one-liner and the message format consistent across create/update.
+ */
+export function flowValidationErrorMessage(
+  flow: unknown,
+  resolvers?: FlowValidationResolvers
+): string | null {
+  const result = validateFlowDefinition(flow, resolvers);
+  if (result.valid) return null;
+  return (
+    "Invalid automation flow: " +
+    result.errors
+      .map((e) => (e.nodeId ? `[${e.nodeId}] ${e.message}` : e.message))
+      .join(" ")
+  );
+}

package/src/validate.test.ts

@@ -79,3 +79,124 @@ describe("validateTemplate — clean template", () => {
     expect(result, JSON.stringify(result.errors)).toEqual({ ok: true, errors: [] });
   });
 });
+
+// Regression: before wiring `validateFlowDefinition` into validateTemplate, a
+// template automation with a broken FLOW (bogus node type / dangling edge / cycle
+// / typo'd channelType) passed the template gate green and then silently never
+// fired on a live pod — the flow contract only ran server-side at install.
+describe("validateTemplate — automation flow node contract", () => {
+  const withAutomation = (flow: unknown): WorkspaceYaml =>
+    ({
+      meta: {
+        slug: "flowy",
+        name: "Flowy",
+        description: "d",
+        icon: "x",
+        color: "#000000",
+      },
+      workspace: { name: "Flowy", description: "d" },
+      profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
+      automations: [
+        { name: "on-create", triggerType: "event", triggerConfig: {}, flow },
+      ],
+    }) as unknown as WorkspaceYaml;
+
+  it("FAILS on an unknown node type (was green before)", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [
+          { id: "t1", type: "trigger", data: {} },
+          { id: "x1", type: "not_a_real_node", data: {} },
+        ],
+        edges: [{ id: "e1", source: "t1", target: "x1" }],
+      }),
+      {}
+    );
+    expect(result.ok).toBe(false);
+    const err = result.errors.find(
+      (e) => e.rule === "automation-flow-unknown_node_type"
+    );
+    expect(err, JSON.stringify(result.errors)).toBeDefined();
+    expect(err!.message).toContain("not_a_real_node");
+  });
+
+  it("FAILS on a dangling edge (target references no node)", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [{ id: "t1", type: "trigger", data: {} }],
+        edges: [{ id: "e1", source: "t1", target: "ghost" }],
+      }),
+      {}
+    );
+    expect(result.ok).toBe(false);
+    const err = result.errors.find(
+      (e) => e.rule === "automation-flow-edge_bad_target"
+    );
+    expect(err, JSON.stringify(result.errors)).toBeDefined();
+  });
+
+  it("FAILS on a capability node with no verbId", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [
+          { id: "t1", type: "trigger", data: {} },
+          { id: "c1", type: "capability", data: {} },
+        ],
+        edges: [{ id: "e1", source: "t1", target: "c1" }],
+      }),
+      {}
+    );
+    expect(result.ok).toBe(false);
+    expect(
+      result.errors.find(
+        (e) => e.rule === "automation-flow-capability_missing_verbId"
+      ),
+      JSON.stringify(result.errors)
+    ).toBeDefined();
+  });
+
+  it("FAILS on a cycle", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [
+          { id: "a", type: "transform", data: { expression: "{{x}}" } },
+          { id: "b", type: "transform", data: { expression: "{{y}}" } },
+        ],
+        edges: [
+          { id: "e1", source: "a", target: "b" },
+          { id: "e2", source: "b", target: "a" },
+        ],
+      }),
+      {}
+    );
+    expect(result.ok).toBe(false);
+    expect(
+      result.errors.find((e) => e.rule === "automation-flow-flow_has_cycle"),
+      JSON.stringify(result.errors)
+    ).toBeDefined();
+  });
+
+  it("PASSES a well-formed flow (trigger → notification output)", () => {
+    const result = validateTemplate(
+      withAutomation({
+        nodes: [
+          { id: "t1", type: "trigger", data: { triggerType: "event" } },
+          {
+            id: "o1",
+            type: "output",
+            data: {
+              outputType: "notification",
+              config: { title: "Hi", body: "{{trigger.payload.data.title}}" },
+            },
+          },
+        ],
+        edges: [{ id: "e1", source: "t1", target: "o1" }],
+      }),
+      {}
+    );
+    expect(result, JSON.stringify(result.errors)).toEqual({
+      ok: true,
+      errors: [],
+    });
+  });
+});