@stigmer/runner 3.0.1

package/dist/workflow-engine/errors.js

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+const RUNTIME_ERROR_TYPE = "https://serverlessworkflow.io/spec/1.0.0/errors/runtime";
+export class WorkflowError extends Error {
+    type;
+    status;
+    title;
+    detail;
+    instance;
+    constructor(fields) {
+        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() {
+        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) {
+        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;
+            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, filter) {
+        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;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/workflow-engine/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/workflow-engine/errors.ts"],"names":[],"mappings":"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"}

package/dist/workflow-engine/expression-utils.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function isStrictExpr(str: string): boolean;
+/**
+ * Strips the `${ ` prefix and ` }` suffix from a strict expression.
+ * Matches Go's `model.SanitizeExpr`.
+ */
+export declare function sanitizeExpr(str: string): string;
+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;
+}
+/**
+ * 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 declare function extractEmbeddedExpressions(str: string): EmbeddedExpression[];
+/**
+ * Checks whether a string contains embedded `${ ... }` expressions
+ * that are NOT strict (the entire value is one expression) and NOT
+ * runtime placeholders (`${.secrets.*}`).
+ */
+export declare function hasEmbeddedExpressions(str: string): boolean;
+/**
+ * Converts an evaluated expression result to a string for embedding
+ * into a larger template string.
+ */
+export declare function stringifyInterpolatedValue(value: unknown): string;

package/dist/workflow-engine/expression-utils.js

@@ -0,0 +1,108 @@
+/**
+ * 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) {
+    return str.startsWith("${ ") && str.endsWith(" }");
+}
+/**
+ * Strips the `${ ` prefix and ` }` suffix from a strict expression.
+ * Matches Go's `model.SanitizeExpr`.
+ */
+export function sanitizeExpr(str) {
+    return str.slice(3, -2);
+}
+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) {
+    if (isStrictExpr(str))
+        return [];
+    const results = [];
+    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) {
+    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) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=expression-utils.js.map

package/dist/workflow-engine/expression-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression-utils.js","sourceRoot":"","sources":["../../src/workflow-engine/expression-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wEAAwE;AACxE,uBAAuB;AACvB,wEAAwE;AAExE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC1B,CAAC;AAeD,MAAM,eAAe,GAAG,KAAK,CAAC;AAE9B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,IAAI,YAAY,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,MAAM,OAAO,GAAyB,EAAE,CAAC;IACzC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,OAAO,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAC3D,IAAI,SAAS,KAAK,CAAC,CAAC;YAAE,MAAM;QAE5B,MAAM,SAAS,GAAG,SAAS,GAAG,eAAe,CAAC,MAAM,CAAC;QACrD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,GAAG,GAAG,SAAS,CAAC;QAEpB,OAAO,GAAG,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACrC,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG;gBAAE,KAAK,EAAE,CAAC;iBACzB,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG;gBAAE,KAAK,EAAE,CAAC;YACnC,IAAI,KAAK,GAAG,CAAC;gBAAE,GAAG,EAAE,CAAC;QACvB,CAAC;QAED,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,UAAU,GAAG,SAAS,CAAC;YACvB,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAEpE,OAAO,CAAC,IAAI,CAAC;YACX,KAAK,EAAE,SAAS;YAChB,GAAG,EAAE,GAAG,GAAG,CAAC;YACZ,IAAI;SACL,CAAC,CAAC;QAEH,UAAU,GAAG,GAAG,GAAG,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,IAAI,YAAY,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;AACvC,CAAC;AAED,wEAAwE;AACxE,wBAAwB;AACxB,wEAAwE;AAExE;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC"}

package/dist/workflow-engine/expression.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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.
+ */
+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 declare function interpolateString(str: string, input: unknown, stateVars: Record<string, unknown>): Promise<string>;
+/**
+ * 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 declare function normalizeSingleQuotedStrings(expr: string): string;
+/**
+ * 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 declare function preprocessUuid(expr: string): {
+    expr: string;
+    hadUuid: boolean;
+};
+/**
+ * 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 declare function evaluateExpression(expr: string, input: unknown, stateVars: Record<string, unknown>): Promise<unknown>;
+/**
+ * Wraps the input value with state variables for jq evaluation.
+ * The jq expression produced by `buildVariableBindingExpr` expects
+ * this shape.
+ */
+export declare function buildJqInput(input: unknown, stateVars: Record<string, unknown>): object;
+/**
+ * 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 declare function evaluateExpressionBatch(expressions: Record<string, string>, input: unknown, stateVars: Record<string, unknown>): Promise<Record<string, unknown>>;
+/**
+ * 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 declare function evaluateString(str: string, input: unknown, stateVars: Record<string, unknown>): Promise<unknown>;
+/**
+ * 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 declare function traverseAndEvaluate(node: unknown, input: unknown, stateVars: Record<string, unknown>): Promise<unknown>;
+/**
+ * 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 declare function checkIfStatement(ifExpr: string | undefined, input: unknown, stateVars: Record<string, unknown>): Promise<boolean>;