@stigmer/runner 3.0.1

package/src/workflow-engine/errors.ts

@@ -0,0 +1,130 @@
+/**
+ * WorkflowError — typed, serializable error following the CNCF
+ * Serverless Workflow error shape (type, status, title, detail, instance).
+ *
+ * Used by:
+ * - `raise` tasks to throw structured errors
+ * - `try` executor to normalize caught errors
+ * - `catch.errors.with` to filter errors by type/status
+ * - `catch.as` to bind error details into state for jq expressions
+ *
+ * Sandbox-safe: zero dependencies, no Node.js or Temporal imports.
+ */
+
+import type { CatchErrors } from "./types.js";
+
+const RUNTIME_ERROR_TYPE =
+  "https://serverlessworkflow.io/spec/1.0.0/errors/runtime";
+
+export class WorkflowError extends Error {
+  readonly type: string;
+  readonly status: number;
+  readonly title: string;
+  readonly detail: string;
+  readonly instance: string;
+
+  constructor(fields: {
+    type: string;
+    status: number;
+    title?: string;
+    detail?: string;
+    instance?: string;
+  }) {
+    const message =
+      fields.title ?? fields.detail ?? `WorkflowError [${fields.type}]`;
+    super(message);
+    this.name = "WorkflowError";
+    this.type = fields.type;
+    this.status = fields.status;
+    this.title = fields.title ?? "";
+    this.detail = fields.detail ?? "";
+    this.instance = fields.instance ?? "";
+  }
+
+  /**
+   * Serializes to a plain object for binding into workflow state
+   * via `catch.as`. The shape matches the CNCF error definition,
+   * making it accessible to jq expressions like `${ .error.type }`.
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      type: this.type,
+      status: this.status,
+      title: this.title,
+      detail: this.detail,
+      instance: this.instance,
+    };
+  }
+
+  /**
+   * Wraps any caught value into a WorkflowError with a consistent
+   * CNCF shape. WorkflowError instances pass through unchanged.
+   */
+  static fromUnknown(err: unknown): WorkflowError {
+    if (err instanceof WorkflowError) {
+      return err;
+    }
+
+    if (err instanceof Error) {
+      return new WorkflowError({
+        type: RUNTIME_ERROR_TYPE,
+        status: 500,
+        title: err.name,
+        detail: err.message,
+      });
+    }
+
+    if (typeof err === "string") {
+      return new WorkflowError({
+        type: RUNTIME_ERROR_TYPE,
+        status: 500,
+        title: "Error",
+        detail: err,
+      });
+    }
+
+    if (err !== null && typeof err === "object") {
+      const obj = err as Record<string, unknown>;
+      return new WorkflowError({
+        type: typeof obj.type === "string" ? obj.type : RUNTIME_ERROR_TYPE,
+        status: typeof obj.status === "number" ? obj.status : 500,
+        title: typeof obj.title === "string" ? obj.title : "",
+        detail: typeof obj.detail === "string" ? obj.detail : "",
+        instance: typeof obj.instance === "string" ? obj.instance : "",
+      });
+    }
+
+    return new WorkflowError({
+      type: RUNTIME_ERROR_TYPE,
+      status: 500,
+      title: "Unknown error",
+      detail: String(err),
+    });
+  }
+
+  /**
+   * Tests whether an error matches a `catch.errors.with` filter.
+   * Returns true if the error satisfies ALL specified filter fields
+   * (AND semantics). An empty or undefined filter matches all errors.
+   *
+   * Matching is exact equality: `type` by string, `status` by number.
+   */
+  static matches(
+    error: WorkflowError,
+    filter: CatchErrors | undefined,
+  ): boolean {
+    if (!filter?.with) return true;
+
+    const conditions = filter.with;
+
+    if ("type" in conditions && conditions.type !== error.type) {
+      return false;
+    }
+
+    if ("status" in conditions && conditions.status !== error.status) {
+      return false;
+    }
+
+    return true;
+  }
+}

package/src/workflow-engine/expression-utils.ts

@@ -0,0 +1,129 @@
+/**
+ * Pure expression-parsing utilities safe for the Temporal workflow sandbox.
+ *
+ * These functions perform only synchronous string manipulation with zero
+ * external dependencies — no Node.js built-ins, no Wasm, no I/O. They
+ * can be imported from workflow-side code (inside the deterministic V8
+ * isolate) without violating sandbox constraints.
+ *
+ * Activity-only evaluation logic (jq-wasm, crypto) remains in
+ * `expression.ts` which must NOT be imported from workflow code.
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// Expression Detection
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Checks if a string is a strict runtime expression: `${ ... }`.
+ * Matches Go's `model.IsStrictExpr` — requires the entire string to
+ * be wrapped, with a space after `${`.
+ */
+export function isStrictExpr(str: string): boolean {
+  return str.startsWith("${ ") && str.endsWith(" }");
+}
+
+/**
+ * Strips the `${ ` prefix and ` }` suffix from a strict expression.
+ * Matches Go's `model.SanitizeExpr`.
+ */
+export function sanitizeExpr(str: string): string {
+  return str.slice(3, -2);
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Embedded Expression Extraction (brace-depth tracking)
+// ─────────────────────────────────────────────────────────────────────
+
+export interface EmbeddedExpression {
+  /** Byte offset of the opening `$` in the source string. */
+  start: number;
+  /** Byte offset one past the closing `}`. */
+  end: number;
+  /** The raw jq expression between `${ ` and ` }`. */
+  expr: string;
+}
+
+const EMBEDDED_MARKER = "${ ";
+
+/**
+ * Scans a string for embedded `${ ... }` expressions using
+ * brace-depth tracking. Returns an empty array when:
+ * - The string contains no `${ ` markers
+ * - The entire string IS a strict expression (handled separately)
+ *
+ * Brace-depth tracking correctly handles nested braces in jq object
+ * construction (e.g. `${ { key: .value } }`), unlike a naive regex
+ * which would stop at the first `}`.
+ *
+ * Known limitation: braces inside jq string literals (e.g. `${ "}" }`)
+ * are counted structurally — the parser does not track quoted context.
+ * This is acceptable because jq string literals containing literal
+ * braces are not a realistic pattern in workflow config values.
+ *
+ * Runtime placeholders (`${.secrets.KEY}`, `${.env_vars.KEY}`) are
+ * never matched because they lack the space after `${`.
+ */
+export function extractEmbeddedExpressions(str: string): EmbeddedExpression[] {
+  if (isStrictExpr(str)) return [];
+
+  const results: EmbeddedExpression[] = [];
+  let searchFrom = 0;
+
+  while (searchFrom < str.length) {
+    const markerIdx = str.indexOf(EMBEDDED_MARKER, searchFrom);
+    if (markerIdx === -1) break;
+
+    const exprStart = markerIdx + EMBEDDED_MARKER.length;
+    let depth = 1;
+    let pos = exprStart;
+
+    while (pos < str.length && depth > 0) {
+      if (str[pos] === "{") depth++;
+      else if (str[pos] === "}") depth--;
+      if (depth > 0) pos++;
+    }
+
+    if (depth !== 0) {
+      searchFrom = exprStart;
+      continue;
+    }
+
+    const rawExpr = str.slice(exprStart, pos);
+    const expr = rawExpr.endsWith(" ") ? rawExpr.slice(0, -1) : rawExpr;
+
+    results.push({
+      start: markerIdx,
+      end: pos + 1,
+      expr,
+    });
+
+    searchFrom = pos + 1;
+  }
+
+  return results;
+}
+
+/**
+ * Checks whether a string contains embedded `${ ... }` expressions
+ * that are NOT strict (the entire value is one expression) and NOT
+ * runtime placeholders (`${.secrets.*}`).
+ */
+export function hasEmbeddedExpressions(str: string): boolean {
+  if (isStrictExpr(str)) return false;
+  return str.includes(EMBEDDED_MARKER);
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Interpolation Helpers
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Converts an evaluated expression result to a string for embedding
+ * into a larger template string.
+ */
+export function stringifyInterpolatedValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}

package/src/workflow-engine/expression.ts

@@ -0,0 +1,430 @@
+/**
+ * Expression evaluation engine for CNCF Serverless Workflow runtime
+ * expressions. Runs OUTSIDE the Temporal workflow sandbox (in a local
+ * activity) using jq-wasm for evaluation.
+ *
+ * Supports:
+ * - Strict expression detection: `${ .some.path }`
+ * - Embedded expression interpolation: `"Hello ${ .name }!"`
+ * - Expression sanitization: strips `${` and `}` wrapper
+ * - Single expression evaluation via jq-wasm
+ * - Recursive tree traversal for evaluating expressions in nested objects
+ * - Conditional (if-statement) evaluation
+ * - uuid() preprocessing (jq-wasm has no custom function support)
+ * - Single-quote normalization (YAML ergonomic: `'approve'` → `"approve"`)
+ *
+ * NOTE: This module requires Node.js built-ins (crypto) and jq-wasm.
+ * It must ONLY be imported from activity code running outside the
+ * Temporal sandbox. Workflow-side code should import sandbox-safe
+ * utilities from `./expression-utils.js` instead.
+ */
+
+import * as jq from "jq-wasm";
+import { randomUUID } from "node:crypto";
+
+import {
+  extractEmbeddedExpressions,
+  hasEmbeddedExpressions,
+  isStrictExpr,
+  sanitizeExpr,
+  stringifyInterpolatedValue,
+} from "./expression-utils.js";
+
+export type { EmbeddedExpression } from "./expression-utils.js";
+export {
+  extractEmbeddedExpressions,
+  hasEmbeddedExpressions,
+  isStrictExpr,
+  sanitizeExpr,
+  stringifyInterpolatedValue,
+} from "./expression-utils.js";
+
+/**
+ * Interpolates all embedded `${ ... }` expressions within a string.
+ * Each expression is evaluated via jq and substituted in place.
+ *
+ * - `null` / `undefined` results become `""` (consistent with
+ *   `resolveRuntimePlaceholders` in resolve.ts).
+ * - Non-string results (objects, arrays, numbers) are JSON-stringified.
+ * - String results are inserted directly.
+ */
+export async function interpolateString(
+  str: string,
+  input: unknown,
+  stateVars: Record<string, unknown>,
+): Promise<string> {
+  const expressions = extractEmbeddedExpressions(str);
+  if (expressions.length === 0) return str;
+
+  let result = "";
+  let lastEnd = 0;
+
+  for (const embedded of expressions) {
+    result += str.slice(lastEnd, embedded.start);
+    const value = await evaluateExpression(embedded.expr, input, stateVars);
+    result += stringifyInterpolatedValue(value);
+    lastEnd = embedded.end;
+  }
+
+  result += str.slice(lastEnd);
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Single-Quote Normalization
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Converts single-quoted string literals in a jq expression to
+ * double-quoted literals with proper JSON/jq escaping.
+ *
+ * jq only supports double-quoted strings (JSON-style). Single quotes
+ * have zero valid meaning in jq syntax. However, YAML workflow authors
+ * naturally write `'approve'` inside double-quoted YAML values because
+ * escaping double quotes in YAML is awkward:
+ *
+ *   when: "${ $context.outcome == 'approve' }"   ← natural
+ *   when: "${ $context.outcome == \"approve\" }"  ← ugly
+ *
+ * This function bridges that gap using a jq-aware lexer with four
+ * states (CODE, IN_DOUBLE_QUOTE, IN_SINGLE_QUOTE, COMMENT) to ensure:
+ *
+ * - Single quotes inside double-quoted jq strings are NOT converted
+ *   (e.g., `"it's"` is valid jq and remains unchanged)
+ * - Characters inside single-quoted content are treated as literal
+ *   (shell-style: `\` is a literal backslash, not an escape prefix)
+ * - Double quotes inside single-quoted content are escaped (`\"`)
+ * - Unclosed single quotes pass through unchanged (let jq report the
+ *   actual syntax error rather than masking it)
+ * - jq `#` comments are left alone
+ *
+ * Must run BEFORE preprocessUuid so that `'uuid'` becomes `"uuid"`
+ * (a quoted string literal) and is not matched by the uuid
+ * word-boundary pattern.
+ */
+export function normalizeSingleQuotedStrings(expr: string): string {
+  if (!expr.includes("'")) return expr;
+
+  const out: string[] = [];
+  let i = 0;
+  const len = expr.length;
+
+  while (i < len) {
+    const ch = expr[i]!;
+
+    if (ch === "#") {
+      // COMMENT: copy everything until end of line
+      while (i < len && expr[i] !== "\n") {
+        out.push(expr[i]!);
+        i++;
+      }
+      continue;
+    }
+
+    if (ch === '"') {
+      // IN_DOUBLE_QUOTE: copy verbatim until unescaped closing "
+      out.push(ch);
+      i++;
+      while (i < len) {
+        const dqch = expr[i]!;
+        if (dqch === "\\") {
+          out.push(dqch);
+          i++;
+          if (i < len) {
+            out.push(expr[i]!);
+            i++;
+          }
+          continue;
+        }
+        out.push(dqch);
+        i++;
+        if (dqch === '"') break;
+      }
+      continue;
+    }
+
+    if (ch === "'") {
+      // IN_SINGLE_QUOTE: collect content until closing '
+      i++;
+      let content = "";
+      let closed = false;
+      while (i < len) {
+        if (expr[i] === "'") {
+          closed = true;
+          i++;
+          break;
+        }
+        content += expr[i];
+        i++;
+      }
+      if (!closed) {
+        // Unclosed single quote — pass through unchanged for jq to report
+        out.push("'");
+        out.push(content);
+      } else {
+        out.push(escapeForJqDoubleQuoted(content));
+      }
+      continue;
+    }
+
+    // CODE: pass through
+    out.push(ch);
+    i++;
+  }
+
+  return out.join("");
+}
+
+/**
+ * Encodes a raw string as a jq/JSON double-quoted literal. All
+ * characters are treated as literal (shell-style single-quote
+ * semantics): backslashes, double quotes, and control characters
+ * are escaped for jq compatibility.
+ */
+function escapeForJqDoubleQuoted(content: string): string {
+  let out = '"';
+  for (const ch of content) {
+    switch (ch) {
+      case '"': out += '\\"'; break;
+      case "\\": out += "\\\\"; break;
+      case "\n": out += "\\n"; break;
+      case "\r": out += "\\r"; break;
+      case "\t": out += "\\t"; break;
+      case "\b": out += "\\b"; break;
+      case "\f": out += "\\f"; break;
+      default: {
+        const code = ch.charCodeAt(0);
+        if (code < 0x20) {
+          out += "\\u" + code.toString(16).padStart(4, "0");
+        } else {
+          out += ch;
+        }
+        break;
+      }
+    }
+  }
+  return out + '"';
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// UUID Preprocessing
+// ─────────────────────────────────────────────────────────────────────
+
+const UUID_PATTERN = /\buuid\b/g;
+
+/**
+ * Replaces all occurrences of `uuid` in a jq expression with a
+ * generated UUID string literal. jq-wasm doesn't support custom
+ * function registration (Go uses `gojq.WithFunction("uuid", ...)`),
+ * so we pre-process before evaluation.
+ */
+export function preprocessUuid(expr: string): { expr: string; hadUuid: boolean } {
+  let hadUuid = false;
+  const processed = expr.replace(UUID_PATTERN, () => {
+    hadUuid = true;
+    return `"${randomUUID()}"`;
+  });
+  return { expr: processed, hadUuid };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Single Expression Evaluation
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Evaluates a single jq expression against an input value, with
+ * state variables available as jq `$variable` bindings.
+ *
+ * The state variables map provides `$context`, `$data`, `$env`,
+ * `$input`, `$output` — matching the workflow state model.
+ *
+ * @param expr - Raw jq expression (already sanitized, no `${ }` wrapper)
+ * @param input - The jq input value (`.` in jq)
+ * @param stateVars - Map of `$variable` → value for jq variable bindings
+ */
+export async function evaluateExpression(
+  expr: string,
+  input: unknown,
+  stateVars: Record<string, unknown>,
+): Promise<unknown> {
+  const normalized = normalizeSingleQuotedStrings(expr);
+  const { expr: processedExpr } = preprocessUuid(normalized);
+
+  const wrappedExpr = buildVariableBindingExpr(processedExpr, stateVars);
+  const jqInput = buildJqInput(input, stateVars);
+
+  const result = await jq.json(jqInput, wrappedExpr);
+  return result;
+}
+
+/**
+ * Wraps a jq expression with variable bindings by constructing a
+ * combined input object and piping through `.as $var` assignments.
+ *
+ * For state vars `{ $context: {...}, $data: {...} }`, produces:
+ * ```
+ * .__vars__.$context as $context | .__vars__.$data as $data | ... | .__body__ | <expr>
+ * ```
+ *
+ * The actual jq input becomes `{ __body__: <original input>, __vars__: <stateVars> }`.
+ */
+function buildVariableBindingExpr(
+  expr: string,
+  stateVars: Record<string, unknown>,
+): string {
+  const varNames = Object.keys(stateVars);
+  if (varNames.length === 0) return expr;
+
+  const bindings = varNames
+    .map((name) => `.__vars__.["${name}"] as ${name}`)
+    .join(" | ");
+
+  return `${bindings} | .__body__ | ${expr}`;
+}
+
+/**
+ * Wraps the input value with state variables for jq evaluation.
+ * The jq expression produced by `buildVariableBindingExpr` expects
+ * this shape.
+ */
+export function buildJqInput(
+  input: unknown,
+  stateVars: Record<string, unknown>,
+): object {
+  if (Object.keys(stateVars).length === 0) return (input ?? {}) as object;
+
+  return {
+    __body__: input ?? {},
+    __vars__: stateVars,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Batch Expression Evaluation
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Evaluates multiple expressions in a single call. Each expression
+ * is evaluated independently against the same input and state.
+ *
+ * Used by the local activity to batch-evaluate all expressions
+ * needed by a task in one round-trip.
+ */
+export async function evaluateExpressionBatch(
+  expressions: Record<string, string>,
+  input: unknown,
+  stateVars: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const results: Record<string, unknown> = {};
+  const entries = Object.entries(expressions);
+
+  for (const [key, expr] of entries) {
+    results[key] = await evaluateExpression(expr, input, stateVars);
+  }
+
+  return results;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// String Evaluation (detect + evaluate if expression)
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Evaluates a string value using a three-step chain:
+ *
+ * 1. **Strict**: If the entire string is `${ expr }`, evaluate via
+ *    jq and return the result (may be any type — object, number, etc.).
+ * 2. **Embedded**: If the string contains `${ expr }` fragments within
+ *    larger text, interpolate each fragment and return a string.
+ * 3. **Passthrough**: Return the string unchanged.
+ *
+ * The CNCF Serverless Workflow 1.0.0 spec demonstrates embedded
+ * expressions in multi-line strings (e.g., HTTP body templates).
+ */
+export async function evaluateString(
+  str: string,
+  input: unknown,
+  stateVars: Record<string, unknown>,
+): Promise<unknown> {
+  if (isStrictExpr(str)) {
+    return evaluateExpression(sanitizeExpr(str), input, stateVars);
+  }
+  if (hasEmbeddedExpressions(str)) {
+    return interpolateString(str, input, stateVars);
+  }
+  return str;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Recursive Tree Traversal
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Recursively walks a value tree, evaluating any string expression
+ * (`${ ... }`) found at any depth. Maps and arrays are traversed
+ * recursively; strings are checked for expressions; all other types
+ * pass through unchanged.
+ *
+ * Originally ported from Go's `utils.TraverseAndEvaluateObj` (now deleted).
+ *
+ * IMPORTANT: Mutates the input object in place (maps and arrays).
+ * Clone before calling if you need the original preserved.
+ */
+export async function traverseAndEvaluate(
+  node: unknown,
+  input: unknown,
+  stateVars: Record<string, unknown>,
+): Promise<unknown> {
+  if (node === null || node === undefined) return node;
+
+  if (typeof node === "string") {
+    return evaluateString(node, input, stateVars);
+  }
+
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      node[i] = await traverseAndEvaluate(node[i], input, stateVars);
+    }
+    return node;
+  }
+
+  if (typeof node === "object") {
+    const obj = node as Record<string, unknown>;
+    for (const key of Object.keys(obj)) {
+      obj[key] = await traverseAndEvaluate(obj[key], input, stateVars);
+    }
+    return obj;
+  }
+
+  return node;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Conditional (If-Statement) Evaluation
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Evaluates a task's `if` condition. Returns true if:
+ * - No condition is specified (task always runs)
+ * - The expression evaluates to `true` (boolean)
+ * - The expression evaluates to "TRUE" (case-insensitive string)
+ * - The expression evaluates to "1"
+ *
+ * Originally ported from Go's `utils.CheckIfStatement` (now deleted).
+ */
+export async function checkIfStatement(
+  ifExpr: string | undefined,
+  input: unknown,
+  stateVars: Record<string, unknown>,
+): Promise<boolean> {
+  if (ifExpr === undefined || ifExpr === null) return true;
+
+  const result = await evaluateString(ifExpr, input, stateVars);
+
+  if (typeof result === "boolean") return result;
+  if (typeof result === "string") {
+    return result.toUpperCase() === "TRUE" || result === "1";
+  }
+
+  return false;
+}