@davidorex/pi-workflows 0.2.0 → 0.3.1

package/src/step-foreach.ts

@@ -1,148 +0,0 @@
-/**
- * ForEach step executor — iterates over an array, executing the step body
- * once per element with the element bound to a named variable in scope.
- */
-import type { StepSpec, StepResult, ExecutionState, ExpressionScope } from "./types.ts";
-import { resolveExpression, resolveExpressions } from "./expression.ts";
-import { zeroUsage, addUsage } from "./step-shared.ts";
-import { persistStepOutput } from "./output.ts";
-
-/** Options for forEach execution, matching the StepExecOptions pattern. */
-interface ForEachOptions {
-  ctx: any;
-  pi: any;
-  signal?: AbortSignal;
-  loadAgent: (name: string) => any;
-  runDir: string;
-  spec: any;
-  widgetState: any;
-  templateEnv?: any;
-  dispatchFn?: any;
-}
-
-/**
- * Execute a forEach step: iterates over an array and executes the step body
- * for each element.
- *
- * @param stepName - the name of the forEach step
- * @param stepSpec - the full step spec (including forEach, as, and the body type)
- * @param state - current execution state
- * @param forEachExpr - the forEach expression string (without ${{ }} delimiters)
- * @param asName - the variable name to bind each element (default: "item")
- * @param executeSingleStep - the step executor function to delegate to
- * @param options - step execution options
- * @returns combined StepResult with array output
- */
-export async function executeForEach(
-  stepName: string,
-  stepSpec: StepSpec,
-  state: ExecutionState,
-  forEachExpr: string,
-  asName: string,
-  executeSingleStep: (name: string, spec: StepSpec, state: ExecutionState, opts: ForEachOptions) => Promise<boolean>,
-  options: ForEachOptions,
-): Promise<StepResult> {
-  const startTime = Date.now();
-  const scope: Record<string, unknown> = { input: state.input, steps: state.steps };
-
-  // Resolve the forEach expression to get the array
-  const rawExpr = forEachExpr.replace(/^\$\{\{\s*/, "").replace(/\s*\}\}$/, "");
-  let array: unknown;
-  try {
-    array = resolveExpression(rawExpr, scope);
-  } catch (err) {
-    return {
-      step: stepName,
-      agent: "forEach",
-      status: "failed",
-      usage: zeroUsage(),
-      durationMs: Date.now() - startTime,
-      error: `forEach expression failed: ${err instanceof Error ? err.message : String(err)}`,
-    };
-  }
-
-  if (!Array.isArray(array)) {
-    return {
-      step: stepName,
-      agent: "forEach",
-      status: "failed",
-      usage: zeroUsage(),
-      durationMs: Date.now() - startTime,
-      error: `forEach expression must resolve to an array, got ${typeof array}`,
-    };
-  }
-
-  // Empty array → completed with empty output
-  if (array.length === 0) {
-    return {
-      step: stepName,
-      agent: "forEach",
-      status: "completed",
-      output: [],
-      textOutput: "[]",
-      usage: zeroUsage(),
-      durationMs: Date.now() - startTime,
-    };
-  }
-
-  // Create the step body (strip forEach/as fields)
-  const bodySpec: StepSpec = { ...stepSpec };
-  delete bodySpec.forEach;
-  delete bodySpec.as;
-
-  const outputs: unknown[] = [];
-  const totalUsage = zeroUsage();
-  let failed = false;
-
-  for (let i = 0; i < array.length; i++) {
-    const element = array[i];
-    const iterStepName = `${stepName}[${i}]`;
-
-    // Create a scoped copy of state for this iteration
-    // The as binding and forEach metadata are added to a proxy state
-    // that exposes them in the expression scope
-    const iterState: ExecutionState = {
-      ...state,
-      steps: { ...state.steps },
-      // Store forEach bindings that the executor can pick up
-      [asName]: element,
-      forEach: { index: i, length: array.length },
-    } as ExecutionState & Record<string, unknown>;
-
-    const cont = await executeSingleStep(iterStepName, bodySpec, iterState, options);
-
-    // Copy iteration results back to main state
-    const iterResult = iterState.steps[iterStepName];
-    if (iterResult) {
-      state.steps[iterStepName] = iterResult;
-      outputs.push(iterResult.output);
-      addUsage(totalUsage, iterResult.usage);
-    }
-
-    if (!cont || (iterResult && iterResult.status === "failed")) {
-      failed = true;
-      break;
-    }
-  }
-
-  const result: StepResult = {
-    step: stepName,
-    agent: "forEach",
-    status: failed ? "failed" : "completed",
-    output: outputs,
-    textOutput: JSON.stringify(outputs, null, 2),
-    usage: totalUsage,
-    durationMs: Date.now() - startTime,
-    error: failed ? `forEach iteration failed` : undefined,
-  };
-
-  // Persist the collected output
-  if (options.runDir) {
-    const outputPath = stepSpec.output?.path
-      ? String(resolveExpressions(stepSpec.output.path, scope))
-      : undefined;
-    result.outputPath = persistStepOutput(options.runDir, stepName, outputs, undefined, outputPath);
-  }
-
-  return result;
-}

package/src/step-gate.test.ts

@@ -1,185 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert";
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import { executeGate } from "./step-gate.ts";
-import { zeroUsage } from "./step-shared.ts";
-
-describe("executeGate", () => {
-  // Happy path — command passes (exit 0)
-  it("returns completed with passed:true on exit 0", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "echo pass" }, "gate1", { cwd: tmpDir });
-    assert.strictEqual(result.status, "completed");
-    assert.strictEqual((result.output as any).passed, true);
-    assert.strictEqual((result.output as any).exitCode, 0);
-  }, { timeout: 10000 });
-
-  it("captures stdout in output.output and textOutput", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "echo hello" }, "gate1", { cwd: tmpDir });
-    assert.strictEqual((result.output as any).output, "hello");
-    assert.strictEqual(result.textOutput, "hello");
-  }, { timeout: 10000 });
-
-  it("sets agent to 'gate'", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "true" }, "gate1", { cwd: tmpDir });
-    assert.strictEqual(result.agent, "gate");
-  }, { timeout: 10000 });
-
-  it("has zero usage", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "true" }, "gate1", { cwd: tmpDir });
-    assert.deepStrictEqual(result.usage, zeroUsage());
-  }, { timeout: 10000 });
-
-  it("records positive durationMs", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "echo test" }, "gate1", { cwd: tmpDir });
-    assert.ok(result.durationMs >= 0);
-  }, { timeout: 10000 });
-
-  // Command fails (non-zero exit)
-  it("returns completed with passed:false on non-zero exit", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "exit 1" }, "gate1", { cwd: tmpDir });
-    assert.strictEqual(result.status, "completed");
-    assert.strictEqual((result.output as any).passed, false);
-    assert.strictEqual((result.output as any).exitCode, 1);
-  }, { timeout: 10000 });
-
-  it("captures stderr on failure", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "echo err >&2; exit 1" }, "gate1", { cwd: tmpDir });
-    assert.ok((result.output as any).output.includes("err"));
-  }, { timeout: 10000 });
-
-  it("captures stdout when stderr is empty on failure", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "echo stdout-msg; exit 1" }, "gate1", { cwd: tmpDir });
-    assert.ok((result.output as any).output.includes("stdout-msg"));
-  }, { timeout: 10000 });
-
-  // Stdout trimming
-  it("trims whitespace from stdout", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "echo '  trimmed  '" }, "gate1", { cwd: tmpDir });
-    assert.strictEqual((result.output as any).output, "trimmed");
-    assert.strictEqual(result.textOutput, "trimmed");
-  }, { timeout: 10000 });
-
-  // Output persistence
-  it("persists output when runDir is provided", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-    fs.mkdirSync(path.join(tmpDir, "outputs"), { recursive: true });
-
-    const result = await executeGate({ check: "echo persist" }, "gate1", { cwd: tmpDir, runDir: tmpDir });
-    assert.ok(result.outputPath);
-    assert.ok(fs.existsSync(result.outputPath!));
-  }, { timeout: 10000 });
-
-  it("persists to custom outputPath when provided", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const customPath = path.join(tmpDir, "custom-gate.json");
-    const result = await executeGate({ check: "echo custom" }, "gate1", {
-      cwd: tmpDir,
-      runDir: tmpDir,
-      outputPath: customPath,
-    });
-    assert.strictEqual(result.outputPath, customPath);
-    assert.ok(fs.existsSync(customPath));
-  }, { timeout: 10000 });
-
-  it("does not persist when runDir is omitted", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "echo nopersist" }, "gate1", { cwd: tmpDir });
-    assert.strictEqual(result.outputPath, undefined);
-  }, { timeout: 10000 });
-
-  // Cancellation
-  it("terminates on abort signal", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const controller = new AbortController();
-    controller.abort();
-    const result = await executeGate({ check: "sleep 30" }, "gate1", {
-      cwd: tmpDir,
-      signal: controller.signal,
-    });
-    // Should resolve (not hang) — the process was killed
-    assert.ok(result);
-  }, { timeout: 10000 });
-
-  it("terminates on late abort signal", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const controller = new AbortController();
-    setTimeout(() => controller.abort(), 200);
-    const result = await executeGate({ check: "sleep 30" }, "gate1", {
-      cwd: tmpDir,
-      signal: controller.signal,
-    });
-    assert.ok(result);
-    // The gate should have failed since the process was killed
-    assert.strictEqual((result.output as any).passed, false);
-  }, { timeout: 10000 });
-
-  // Timeout
-  it("terminates on timeout", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "sleep 30" }, "gate1", {
-      cwd: tmpDir,
-      timeoutMs: 500,
-    });
-    assert.ok(result);
-    assert.strictEqual((result.output as any).passed, false);
-  }, { timeout: 10000 });
-
-  // Edge cases
-  it("handles command that produces no output", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "true" }, "gate1", { cwd: tmpDir });
-    assert.strictEqual((result.output as any).output, "");
-    assert.strictEqual(result.textOutput, "");
-  }, { timeout: 10000 });
-
-  it("handles command with multi-line stdout", async (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-gate-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const result = await executeGate({ check: "echo line1; echo line2" }, "gate1", { cwd: tmpDir });
-    assert.ok((result.output as any).output.includes("line1"));
-    assert.ok((result.output as any).output.includes("line2"));
-  }, { timeout: 10000 });
-});

package/src/step-gate.ts

@@ -1,116 +0,0 @@
-/**
- * Gate step executor — runs a shell command and passes/fails based on exit code.
- */
-import type { GateSpec, StepResult } from "./types.ts";
-import { zeroUsage, SIGKILL_GRACE_MS } from "./step-shared.ts";
-import { persistStepOutput } from "./output.ts";
-
-/**
- * Execute a gate step: runs a shell command, passes/fails based on exit code.
- *
- * The gate's check command is expected to already have ${{ }} expressions resolved
- * before being passed here.
- */
-export async function executeGate(
-  gate: GateSpec,
-  stepName: string,
-  options: { cwd: string; signal?: AbortSignal; timeoutMs?: number; runDir?: string; outputPath?: string },
-): Promise<StepResult> {
-  const startTime = Date.now();
-  try {
-    const { spawn } = await import("node:child_process");
-    const output = await new Promise<string>((resolve, reject) => {
-      const proc = spawn("sh", ["-c", gate.check], {
-        cwd: options.cwd,
-        stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-      });
-
-      let stdout = "";
-      let stderr = "";
-      let settled = false;
-      proc.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
-      proc.stderr.on("data", (d: Buffer) => { stderr += d.toString(); });
-
-      // Kill the entire process group (sh + children like sleep)
-      const killProc = () => {
-        if (!proc.pid) return;
-        try { process.kill(-proc.pid, "SIGTERM"); } catch { /* already dead */ }
-        setTimeout(() => {
-          if (!proc.pid) return;
-          try { process.kill(-proc.pid, "SIGKILL"); } catch { /* already dead */ }
-        }, SIGKILL_GRACE_MS);
-      };
-
-      // Handle abort signal (from parallel cancellation or timeout)
-      const onAbort = () => { killProc(); };
-      if (options.signal) {
-        if (options.signal.aborted) { killProc(); }
-        else { options.signal.addEventListener("abort", onAbort, { once: true }); }
-      }
-
-      // Handle step-level timeout
-      let timeoutId: ReturnType<typeof setTimeout> | undefined;
-      if (options.timeoutMs) {
-        timeoutId = setTimeout(() => { killProc(); }, options.timeoutMs);
-      }
-
-      proc.on("close", (code) => {
-        if (settled) return;
-        settled = true;
-        if (timeoutId) clearTimeout(timeoutId);
-        if (options.signal) options.signal.removeEventListener("abort", onAbort);
-        if (code === 0) {
-          resolve(stdout);
-        } else {
-          const err: any = new Error(`Process exited with code ${code}`);
-          err.status = code;
-          err.stdout = stdout;
-          err.stderr = stderr;
-          reject(err);
-        }
-      });
-
-      proc.on("error", (err) => {
-        if (settled) return;
-        settled = true;
-        if (timeoutId) clearTimeout(timeoutId);
-        if (options.signal) options.signal.removeEventListener("abort", onAbort);
-        reject(err);
-      });
-    });
-    const gateOutput = { passed: true, exitCode: 0, output: output.trim() };
-    const result: StepResult = {
-      step: stepName,
-      agent: "gate",
-      status: "completed",
-      textOutput: output.trim(),
-      output: gateOutput,
-      usage: zeroUsage(),
-      durationMs: Date.now() - startTime,
-    };
-    if (options.runDir) {
-      result.outputPath = persistStepOutput(options.runDir, stepName, gateOutput, undefined, options.outputPath);
-    }
-    return result;
-  } catch (err: unknown) {
-    const execErr = err as { status?: number; stdout?: string; stderr?: string };
-    const exitCode = execErr.status ?? 1;
-    const stderr = execErr.stderr?.trim() ?? "";
-    const stdout = execErr.stdout?.trim() ?? "";
-    const gateOutput = { passed: false, exitCode, output: stderr || stdout };
-    const result: StepResult = {
-      step: stepName,
-      agent: "gate",
-      status: "completed",
-      textOutput: stderr || stdout,
-      output: gateOutput,
-      usage: zeroUsage(),
-      durationMs: Date.now() - startTime,
-    };
-    if (options.runDir) {
-      result.outputPath = persistStepOutput(options.runDir, stepName, gateOutput, undefined, options.outputPath);
-    }
-    return result;
-  }
-}