@stigmer/runner 3.0.1

package/src/workflow-engine/__tests__/tasks/run.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect, vi } from "vitest";
+import { RunTaskBuilder } from "../../tasks/run.js";
+import { createState } from "../../state.js";
+import type { RunTaskDef, TaskExecutionContext, RunCommandConfig, RunWorkflowExecutionConfig } from "../../types.js";
+
+const notAvailable = () => { throw new Error("not available in test"); };
+
+function makeCtx(overrides?: {
+  runCommand?: (config: RunCommandConfig) => Promise<unknown>;
+  runWorkflow?: (config: RunWorkflowExecutionConfig) => Promise<unknown>;
+}): TaskExecutionContext {
+  return {
+    evaluateExpressions: async () => ({}),
+    doc: { document: { dsl: "1.0.0", name: "test" }, do: [] },
+    sleep: notAvailable,
+    listen: notAvailable,
+    runCommand: overrides?.runCommand ?? notAvailable,
+    runWorkflow: overrides?.runWorkflow ?? notAvailable,
+    awaitHumanInput: notAvailable,
+    callHttp: notAvailable,
+    callGrpc: notAvailable,
+    callFunction: notAvailable,
+    callAgent: notAvailable,
+  };
+}
+
+describe("RunTaskBuilder", () => {
+  describe("validation", () => {
+    it("throws when no mode is defined", () => {
+      const taskDef: RunTaskDef = { kind: "run", run: {} };
+      const builder = new RunTaskBuilder("task", taskDef);
+      expect(() => builder.build()).toThrow("exactly one of 'script', 'shell', or 'workflow'");
+    });
+
+    it("throws when multiple modes are defined", () => {
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: {
+          script: { language: "js", code: "1" },
+          shell: { command: "echo" },
+        },
+      };
+      const builder = new RunTaskBuilder("task", taskDef);
+      expect(() => builder.build()).toThrow("only one of");
+    });
+
+    it("throws for unsupported script language", () => {
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: { script: { language: "ruby", code: "puts 1" } },
+      };
+      const builder = new RunTaskBuilder("task", taskDef);
+      expect(() => builder.build()).toThrow("unsupported script language 'ruby'");
+    });
+
+    it("throws when script.code is missing", () => {
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: { script: { language: "js" } },
+      };
+      const builder = new RunTaskBuilder("task", taskDef);
+      expect(() => builder.build()).toThrow("script.code is required");
+    });
+
+    it("throws when shell.command is missing", () => {
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: { shell: { command: "" } },
+      };
+      const builder = new RunTaskBuilder("task", taskDef);
+      expect(() => builder.build()).toThrow("shell.command is required");
+    });
+
+    it("throws when workflow.name is missing", () => {
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: { workflow: { name: "", namespace: "default", version: "1.0.0" } },
+      };
+      const builder = new RunTaskBuilder("task", taskDef);
+      expect(() => builder.build()).toThrow("workflow.name is required");
+    });
+  });
+
+  describe("script execution", () => {
+    it("calls ctx.runCommand with script config", async () => {
+      const runCommand = vi.fn(async () => "hello world");
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: { script: { language: "js", code: "console.log('hello world')" } },
+      };
+
+      const builder = new RunTaskBuilder("script1", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      const result = await executor(null, state, makeCtx({ runCommand }));
+
+      expect(runCommand).toHaveBeenCalledWith(expect.objectContaining({
+        mode: "script",
+        language: "js",
+        code: "console.log('hello world')",
+      }));
+      expect(result).toBe("hello world");
+    });
+
+    it("stores script result in state under task name", async () => {
+      const runCommand = vi.fn(async () => "output-data");
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: { script: { language: "python", code: "print('output-data')" } },
+      };
+
+      const builder = new RunTaskBuilder("pyScript", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      await executor(null, state, makeCtx({ runCommand }));
+
+      expect(state.data.pyScript).toBe("output-data");
+    });
+
+    it("passes environment from script config", async () => {
+      const runCommand = vi.fn(async () => "");
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: {
+          script: {
+            language: "js",
+            code: "process.env.MY_VAR",
+            environment: { MY_VAR: "value" },
+          },
+        },
+      };
+
+      const builder = new RunTaskBuilder("envScript", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      await executor(null, state, makeCtx({ runCommand }));
+
+      expect(runCommand).toHaveBeenCalledWith(expect.objectContaining({
+        environment: { MY_VAR: "value" },
+      }));
+    });
+  });
+
+  describe("shell execution", () => {
+    it("calls ctx.runCommand with shell config", async () => {
+      const runCommand = vi.fn(async () => "shell-output");
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: { shell: { command: "echo hello" } },
+      };
+
+      const builder = new RunTaskBuilder("shell1", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      const result = await executor(null, state, makeCtx({ runCommand }));
+
+      expect(runCommand).toHaveBeenCalledWith(expect.objectContaining({
+        mode: "shell",
+        command: "echo hello",
+      }));
+      expect(result).toBe("shell-output");
+    });
+
+    it("stores shell result in state", async () => {
+      const runCommand = vi.fn(async () => "ls-result");
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: { shell: { command: "ls" } },
+      };
+
+      const builder = new RunTaskBuilder("lsTask", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      await executor(null, state, makeCtx({ runCommand }));
+
+      expect(state.data.lsTask).toBe("ls-result");
+    });
+  });
+
+  describe("workflow execution", () => {
+    it("calls ctx.runWorkflow with await: true", async () => {
+      const runWorkflow = vi.fn(async () => ({ child: "done" }));
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: {
+          workflow: { name: "child-workflow", namespace: "default", version: "1.0.0" },
+        },
+      };
+
+      const builder = new RunTaskBuilder("childRun", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      const result = await executor(null, state, makeCtx({ runWorkflow }));
+
+      expect(runWorkflow).toHaveBeenCalledWith({
+        name: "child-workflow",
+        input: undefined,
+        await: true,
+      });
+      expect(result).toEqual({ child: "done" });
+    });
+
+    it("stores child workflow result in state", async () => {
+      const runWorkflow = vi.fn(async () => ({ key: "value" }));
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: {
+          workflow: { name: "sub-flow", namespace: "ns", version: "2.0.0" },
+        },
+      };
+
+      const builder = new RunTaskBuilder("subflow", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      await executor(null, state, makeCtx({ runWorkflow }));
+
+      expect(state.data.subflow).toEqual({ key: "value" });
+    });
+
+    it("passes workflow.input to child", async () => {
+      const runWorkflow = vi.fn(async () => null);
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: {
+          workflow: {
+            name: "child",
+            namespace: "default",
+            version: "1.0.0",
+            input: { userId: "u123" },
+          },
+        },
+      };
+
+      const builder = new RunTaskBuilder("task", taskDef);
+      const executor = builder.build();
+      await executor(null, createState(), makeCtx({ runWorkflow }));
+
+      expect(runWorkflow).toHaveBeenCalledWith(expect.objectContaining({
+        input: { userId: "u123" },
+      }));
+    });
+  });
+
+  describe("state.env propagation", () => {
+    it("passes state.env as runtimeEnv to runCommand", async () => {
+      const runCommand = vi.fn(async () => "");
+      const taskDef: RunTaskDef = {
+        kind: "run",
+        run: { shell: { command: "test" } },
+      };
+
+      const builder = new RunTaskBuilder("envTask", taskDef);
+      const executor = builder.build();
+      const state = createState();
+      state.env = { SECRET_KEY: "abc123" };
+      await executor(null, state, makeCtx({ runCommand }));
+
+      expect(runCommand).toHaveBeenCalledWith(expect.objectContaining({
+        runtimeEnv: { SECRET_KEY: "abc123" },
+      }));
+    });
+  });
+
+  it("shouldRun always returns true", async () => {
+    const taskDef: RunTaskDef = {
+      kind: "run",
+      run: { shell: { command: "echo" } },
+    };
+    const builder = new RunTaskBuilder("t", taskDef);
+    expect(await builder.shouldRun()).toBe(true);
+  });
+});

package/src/workflow-engine/__tests__/tasks/set.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from "vitest";
+import { SetTaskBuilder } from "../../tasks/set.js";
+import { WorkflowStateImpl, createState } from "../../state.js";
+import { evaluateExpressionBatch } from "../../expression.js";
+import type { SetTaskDef, TaskExecutionContext, WorkflowModel } from "../../types.js";
+
+const notAvailable = () => { throw new Error("not available in test"); };
+
+function makeCtx(): TaskExecutionContext {
+  return {
+    evaluateExpressions: evaluateExpressionBatch,
+    doc: { document: { dsl: "1.0.0", name: "test" }, do: [] },
+    sleep: notAvailable,
+    listen: notAvailable,
+    runCommand: notAvailable,
+    runWorkflow: notAvailable,
+    awaitHumanInput: notAvailable,
+    callHttp: notAvailable,
+    callGrpc: notAvailable,
+    callFunction: notAvailable,
+    callAgent: notAvailable,
+  };
+}
+
+describe("SetTaskBuilder", () => {
+  it("sets static values into state.data", async () => {
+    const taskDef: SetTaskDef = {
+      kind: "set",
+      set: { workflow_started: true, message: "hello" },
+    };
+    const builder = new SetTaskBuilder("initialize", taskDef);
+    const executor = builder.build();
+    const state = createState();
+
+    await executor(null, state, makeCtx());
+
+    expect(state.data.workflow_started).toBe(true);
+    expect(state.data.message).toBe("hello");
+  });
+
+  it("evaluates jq expressions in set object", async () => {
+    const taskDef: SetTaskDef = {
+      kind: "set",
+      set: { computed: "${ $data.a + $data.b }", message: "Data injected" },
+    };
+    const builder = new SetTaskBuilder("injectData", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.addData({ a: 10, b: 32 });
+
+    await executor(null, state, makeCtx());
+
+    expect(state.data.computed).toBe(42);
+    expect(state.data.message).toBe("Data injected");
+  });
+
+  it("returns the evaluated set object as output", async () => {
+    const taskDef: SetTaskDef = {
+      kind: "set",
+      set: { status: "success", count: 42 },
+    };
+    const builder = new SetTaskBuilder("step", taskDef);
+    const executor = builder.build();
+    const state = createState();
+
+    const output = await executor(null, state, makeCtx());
+
+    expect(output).toEqual({ status: "success", count: 42 });
+  });
+
+  it("does not mutate the original task definition", async () => {
+    const taskDef: SetTaskDef = {
+      kind: "set",
+      set: { value: "${ .x }" },
+    };
+    const builder = new SetTaskBuilder("step", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.addData({ x: 99 });
+
+    await executor(null, state, makeCtx());
+
+    expect(taskDef.set.value).toBe("${ .x }");
+  });
+
+  it("handles mixed static and expression values", async () => {
+    const taskDef: SetTaskDef = {
+      kind: "set",
+      set: {
+        staticKey: "constant",
+        dynamicKey: "${ $data.name }",
+        nested: { inner: "${ $data.value }" },
+      },
+    };
+    const builder = new SetTaskBuilder("step", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.addData({ name: "hello", value: 42 });
+
+    await executor(null, state, makeCtx());
+
+    expect(state.data.staticKey).toBe("constant");
+    expect(state.data.dynamicKey).toBe("hello");
+    expect(state.data.nested).toEqual({ inner: 42 });
+  });
+
+  it("matches golden YAML 01 — three sequential set tasks", async () => {
+    const state = createState();
+    const ctx = makeCtx();
+
+    const task1: SetTaskDef = { kind: "set", set: { workflow_started: true } };
+    await new SetTaskBuilder("initialize", task1).build()(null, state, ctx);
+    expect(state.data.workflow_started).toBe(true);
+
+    const task2: SetTaskDef = {
+      kind: "set",
+      set: { message: "Hello, Zigflow!", status: "success", executed: true },
+    };
+    await new SetTaskBuilder("hello", task2).build()(null, state, ctx);
+    expect(state.data.message).toBe("Hello, Zigflow!");
+    expect(state.data.status).toBe("success");
+
+    const task3: SetTaskDef = { kind: "set", set: { workflow_completed: true } };
+    await new SetTaskBuilder("finalize", task3).build()(null, state, ctx);
+    expect(state.data.workflow_completed).toBe(true);
+  });
+});

package/src/workflow-engine/__tests__/tasks/switch.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect } from "vitest";
+import { SwitchTaskBuilder, extractFlowDirective } from "../../tasks/switch.js";
+import { createState } from "../../state.js";
+import { evaluateExpressionBatch } from "../../expression.js";
+import type { SwitchTaskDef, TaskExecutionContext } from "../../types.js";
+
+const notAvailable = () => { throw new Error("not available in test"); };
+
+function makeCtx(): TaskExecutionContext {
+  return {
+    evaluateExpressions: evaluateExpressionBatch,
+    doc: { document: { dsl: "1.0.0", name: "test" }, do: [] },
+    sleep: notAvailable,
+    listen: notAvailable,
+    runCommand: notAvailable,
+    runWorkflow: notAvailable,
+    awaitHumanInput: notAvailable,
+    callHttp: notAvailable,
+    callGrpc: notAvailable,
+    callFunction: notAvailable,
+    callAgent: notAvailable,
+  };
+}
+
+describe("SwitchTaskBuilder", () => {
+  it("matches the first true condition", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "highValue", when: "${ $context.userId > 5 }", then: "highValueUser" },
+        { name: "regular", when: "${ $context.userId <= 5 }", then: "regularUser" },
+        { name: "default", then: "unknownUser" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("classifyUser", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.context = { userId: 10 };
+
+    const output = await executor(null, state, makeCtx());
+    const directive = extractFlowDirective(output);
+
+    expect(directive).toBe("highValueUser");
+  });
+
+  it("falls through to second condition when first is false", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "highValue", when: "${ $context.userId > 5 }", then: "highValueUser" },
+        { name: "regular", when: "${ $context.userId <= 5 }", then: "regularUser" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("classifyUser", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.context = { userId: 3 };
+
+    const output = await executor(null, state, makeCtx());
+    const directive = extractFlowDirective(output);
+
+    expect(directive).toBe("regularUser");
+  });
+
+  it("matches the default case when no when conditions match", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "never", when: "${ 1 == 0 }", then: "neverReached" },
+        { name: "default", then: "fallback" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("decide", taskDef);
+    const executor = builder.build();
+    const state = createState();
+
+    const output = await executor(null, state, makeCtx());
+    const directive = extractFlowDirective(output);
+
+    expect(directive).toBe("fallback");
+  });
+
+  it("supports end directive", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "always", when: "${ 1 == 1 }", then: "end" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("decide", taskDef);
+    const executor = builder.build();
+    const state = createState();
+
+    const output = await executor(null, state, makeCtx());
+    const directive = extractFlowDirective(output);
+
+    expect(directive).toBe("end");
+  });
+
+  it("returns null when no conditions match and no default", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "never", when: "${ 1 == 0 }", then: "neverReached" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("decide", taskDef);
+    const executor = builder.build();
+    const state = createState();
+
+    const output = await executor(null, state, makeCtx());
+
+    expect(output).toBeNull();
+  });
+
+  it("throws on duplicate default cases", () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "default1", then: "a" },
+        { name: "default2", then: "b" },
+      ],
+    };
+    expect(() => new SwitchTaskBuilder("bad", taskDef)).toThrow(
+      "has 2 default cases",
+    );
+  });
+
+  it("uses $data variables for conditions", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "valid", when: "${ $data.valid == true }", then: "proceed" },
+        { name: "default", then: "reject" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("check", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.addData({ valid: true });
+
+    const output = await executor(null, state, makeCtx());
+    const directive = extractFlowDirective(output);
+
+    expect(directive).toBe("proceed");
+  });
+
+  it("matches golden YAML 02 — classify user by userId", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "highValueCase", when: "${ $context.userId > 5 }", then: "highValueUser" },
+        { name: "regularUserCase", when: "${ $context.userId <= 5 }", then: "regularUser" },
+        { name: "defaultCase", then: "unknownUser" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("classifyUser", taskDef);
+    const executor = builder.build();
+
+    const state1 = createState();
+    state1.context = { userId: 7 };
+    const output1 = await executor(null, state1, makeCtx());
+    expect(extractFlowDirective(output1)).toBe("highValueUser");
+
+    const state2 = createState();
+    state2.context = { userId: 3 };
+    const output2 = await executor(null, state2, makeCtx());
+    expect(extractFlowDirective(output2)).toBe("regularUser");
+  });
+
+  it("matches single-quoted string condition — the approval gate pattern", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "approved", when: "${ $context.review.outcome == 'approve' }", then: "handleApproved" },
+        { name: "rejected", then: "handleRejected" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("approvalGate", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.context = { review: { outcome: "approve", reviewer: "alice" } };
+
+    const output = await executor(null, state, makeCtx());
+    expect(extractFlowDirective(output)).toBe("handleApproved");
+  });
+
+  it("matches double-quoted string condition (baseline parity)", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "approved", when: '${ $context.review.outcome == "approve" }', then: "handleApproved" },
+        { name: "rejected", then: "handleRejected" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("approvalGate", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.context = { review: { outcome: "approve" } };
+
+    const output = await executor(null, state, makeCtx());
+    expect(extractFlowDirective(output)).toBe("handleApproved");
+  });
+
+  it("falls through to default when single-quoted condition does not match", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "approved", when: "${ $context.review.outcome == 'approve' }", then: "handleApproved" },
+        { name: "rejected", then: "handleRejected" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("approvalGate", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.context = { review: { outcome: "reject" } };
+
+    const output = await executor(null, state, makeCtx());
+    expect(extractFlowDirective(output)).toBe("handleRejected");
+  });
+
+  it("routes 3-way string switch correctly", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "approve", when: "${ $context.gate.outcome == 'approve' }", then: "approved" },
+        { name: "escalate", when: "${ $context.gate.outcome == 'escalate' }", then: "escalated" },
+        { name: "reject", when: "${ $context.gate.outcome == 'reject' }", then: "rejected" },
+        { name: "default", then: "unknown" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("threeWay", taskDef);
+    const executor = builder.build();
+
+    for (const [outcome, expected] of [
+      ["approve", "approved"],
+      ["escalate", "escalated"],
+      ["reject", "rejected"],
+      ["other", "unknown"],
+    ]) {
+      const state = createState();
+      state.context = { gate: { outcome } };
+      const output = await executor(null, state, makeCtx());
+      expect(extractFlowDirective(output)).toBe(expected);
+    }
+  });
+
+  it("accesses deeply nested context in single-quoted condition", async () => {
+    const taskDef: SwitchTaskDef = {
+      kind: "switch",
+      switch: [
+        { name: "critical", when: "${ $context.classify.result.severity == 'critical' }", then: "escalate" },
+        { name: "default", then: "log" },
+      ],
+    };
+    const builder = new SwitchTaskBuilder("severity", taskDef);
+    const executor = builder.build();
+    const state = createState();
+    state.context = { classify: { result: { severity: "critical" } } };
+
+    const output = await executor(null, state, makeCtx());
+    expect(extractFlowDirective(output)).toBe("escalate");
+  });
+});
+
+describe("extractFlowDirective", () => {
+  it("extracts directive from switch output", () => {
+    expect(extractFlowDirective({ __flow_directive__: "end" })).toBe("end");
+    expect(extractFlowDirective({ __flow_directive__: "myTask" })).toBe("myTask");
+  });
+
+  it("returns undefined for non-switch output", () => {
+    expect(extractFlowDirective(null)).toBeUndefined();
+    expect(extractFlowDirective(42)).toBeUndefined();
+    expect(extractFlowDirective({ data: 1 })).toBeUndefined();
+  });
+});