@q1k-oss/btree-workflows 0.0.1

package/src/actions/parse-file.ts

@@ -0,0 +1,139 @@
+/**
+ * ParseFile Node
+ *
+ * Parses CSV/Excel files into structured data via a Temporal activity.
+ * This node requires the `parseFile` activity to be configured in the context -
+ * it does not support standalone/inline execution because file I/O requires
+ * capabilities outside the workflow sandbox.
+ *
+ * Features:
+ * - CSV and Excel (xlsx, xls) file format support
+ * - Column mapping/renaming
+ * - Parse options (skip rows, trim, date parsing)
+ * - Result stored in blackboard
+ */
+
+import { ActionNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  type ParseFileRequest,
+  NodeStatus,
+} from "../types.js";
+import { resolveValue, type VariableContext } from "../utilities/variable-resolver.js";
+
+/**
+ * Configuration for ParseFile node
+ */
+export interface ParseFileConfig extends NodeConfiguration {
+  /** Path to file (supports ${input.file}, ${bb.filePath}) */
+  file: string;
+  /** File format */
+  format?: "csv" | "xlsx" | "xls" | "auto";
+  /** Sheet name for Excel (default: first sheet) */
+  sheetName?: string;
+  /** Column mapping { "Original Name": "normalizedName" } */
+  columnMapping?: Record<string, string>;
+  /** Output key on blackboard */
+  outputKey: string;
+  /** Parse options */
+  options?: ParseFileRequest["options"];
+}
+
+/**
+ * ParseFile Node
+ *
+ * Parses CSV/Excel files into structured data and stores the result in blackboard.
+ * Requires the `parseFile` activity to be configured.
+ *
+ * @example YAML
+ * ```yaml
+ * type: ParseFile
+ * id: parse-orders
+ * props:
+ *   file: "${input.orderFile}"
+ *   format: csv
+ *   columnMapping:
+ *     "Order ID": "orderId"
+ *     "Customer Name": "customerName"
+ *     "Amount": "amount"
+ *   outputKey: "orders"
+ *   options:
+ *     skipRows: 1
+ *     trim: true
+ * ```
+ */
+export class ParseFile extends ActionNode {
+  private file: string;
+  private format: ParseFileConfig["format"];
+  private sheetName?: string;
+  private columnMapping?: Record<string, string>;
+  private outputKey: string;
+  private options?: ParseFileRequest["options"];
+
+  constructor(config: ParseFileConfig) {
+    super(config);
+
+    if (!config.file) {
+      throw new ConfigurationError("ParseFile requires file");
+    }
+
+    if (!config.outputKey) {
+      throw new ConfigurationError("ParseFile requires outputKey");
+    }
+
+    this.file = config.file;
+    this.format = config.format || "auto";
+    this.sheetName = config.sheetName;
+    this.columnMapping = config.columnMapping;
+    this.outputKey = config.outputKey;
+    this.options = config.options;
+  }
+
+  protected async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    // Validate activity is available
+    if (!context.activities?.parseFile) {
+      this._lastError =
+        "ParseFile requires activities.parseFile to be configured. " +
+        "This activity handles file I/O outside the workflow sandbox.";
+      this.log(`Error: ${this._lastError}`);
+      return NodeStatus.FAILURE;
+    }
+
+    try {
+      const varCtx: VariableContext = {
+        blackboard: context.blackboard,
+        input: context.input,
+        testData: context.testData,
+      };
+
+      const resolvedFile = resolveValue(this.file, varCtx) as string;
+
+      const request: ParseFileRequest = {
+        file: resolvedFile,
+        format: this.format,
+        sheetName: this.sheetName,
+        columnMapping: this.columnMapping,
+        options: this.options,
+      };
+
+      this.log(`Parsing file: ${resolvedFile} (format: ${this.format || "auto"})`);
+      const result = await context.activities.parseFile(request);
+
+      // Store parsed data in blackboard
+      context.blackboard.set(this.outputKey, result.data);
+
+      this.log(
+        `Parsed ${result.rowCount} rows from ${resolvedFile}, ` +
+        `columns: [${result.columns.join(", ")}]`
+      );
+
+      return NodeStatus.SUCCESS;
+    } catch (error) {
+      this._lastError = error instanceof Error ? error.message : String(error);
+      this.log(`Parse file failed: ${this._lastError}`);
+      return NodeStatus.FAILURE;
+    }
+  }
+}

package/src/actions/python-script.test.ts

@@ -0,0 +1,439 @@
+/**
+ * PythonScript Node Tests
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { Registry } from "../registry.js";
+import { type TemporalContext, type BtreeActivities, NodeStatus } from "../types.js";
+import { PythonScript, type PythonScriptConfig } from "./python-script.js";
+
+describe("PythonScript Node", () => {
+  let blackboard: ScopedBlackboard;
+  let registry: Registry;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard();
+    registry = new Registry();
+    vi.clearAllMocks();
+  });
+
+  describe("Construction and validation", () => {
+    it("should create node with valid config", () => {
+      const node = new PythonScript({
+        id: "test",
+        code: "bb['result'] = 42",
+      });
+
+      expect(node).toBeDefined();
+      expect(node.id).toBe("test");
+    });
+
+    it("should require code", () => {
+      expect(() => {
+        new PythonScript({
+          id: "test",
+        } as PythonScriptConfig);
+      }).toThrow(/requires code/i);
+    });
+
+    it("should accept optional packages and timeout", () => {
+      const node = new PythonScript({
+        id: "test",
+        code: "import pandas",
+        packages: ["pandas"],
+        timeout: 30000,
+      });
+
+      expect(node).toBeDefined();
+    });
+  });
+
+  describe("Activity requirement", () => {
+    it("should fail without executePythonScript activity", async () => {
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: undefined,
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "bb['result'] = 1 + 1",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("requires activities.executePythonScript");
+    });
+
+    it("should fail when activities object exists but executePythonScript is missing", async () => {
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          // executePythonScript is not provided
+        } as BtreeActivities,
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "bb['result'] = 1 + 1",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("requires activities.executePythonScript");
+    });
+  });
+
+  describe("Execution with activity", () => {
+    it("should execute Python code via activity", async () => {
+      const mockPythonActivity = vi.fn().mockResolvedValue({
+        blackboard: { result: 42 },
+        stdout: "",
+        stderr: "",
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          executePythonScript: mockPythonActivity,
+        },
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "bb['result'] = 21 * 2",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.SUCCESS);
+      expect(mockPythonActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          code: "bb['result'] = 21 * 2",
+        })
+      );
+    });
+
+    it("should pass blackboard state to Python", async () => {
+      blackboard.set("x", 10);
+      blackboard.set("y", 20);
+
+      const mockPythonActivity = vi.fn().mockResolvedValue({
+        blackboard: { sum: 30 },
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          executePythonScript: mockPythonActivity,
+        },
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "bb['sum'] = bb['x'] + bb['y']",
+      });
+
+      await node.tick(context);
+
+      expect(mockPythonActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          blackboard: { x: 10, y: 20 },
+        })
+      );
+    });
+
+    it("should pass workflow input to Python", async () => {
+      const mockPythonActivity = vi.fn().mockResolvedValue({
+        blackboard: {},
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        input: { userId: "user-123", orderId: "order-456" },
+        activities: {
+          executePieceAction: vi.fn(),
+          executePythonScript: mockPythonActivity,
+        },
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "bb['uid'] = input['userId']",
+      });
+
+      await node.tick(context);
+
+      expect(mockPythonActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          input: { userId: "user-123", orderId: "order-456" },
+        })
+      );
+    });
+
+    it("should merge Python blackboard changes back", async () => {
+      blackboard.set("existing", "value");
+
+      const mockPythonActivity = vi.fn().mockResolvedValue({
+        blackboard: {
+          newKey: "newValue",
+          computed: 123,
+        },
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          executePythonScript: mockPythonActivity,
+        },
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "bb['newKey'] = 'newValue'\nbb['computed'] = 123",
+      });
+
+      await node.tick(context);
+
+      expect(blackboard.get("newKey")).toBe("newValue");
+      expect(blackboard.get("computed")).toBe(123);
+      // Original value should still be there
+      expect(blackboard.get("existing")).toBe("value");
+    });
+
+    it("should pass timeout to activity", async () => {
+      const mockPythonActivity = vi.fn().mockResolvedValue({
+        blackboard: {},
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          executePythonScript: mockPythonActivity,
+        },
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "import time; time.sleep(1)",
+        timeout: 5000,
+      });
+
+      await node.tick(context);
+
+      expect(mockPythonActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          timeout: 5000,
+        })
+      );
+    });
+
+    it("should handle activity errors", async () => {
+      const mockPythonActivity = vi.fn().mockRejectedValue(
+        new Error("Python execution failed: SyntaxError")
+      );
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          executePythonScript: mockPythonActivity,
+        },
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "this is not valid python",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("Python execution failed");
+    });
+  });
+
+  describe("Variable resolution in code", () => {
+    it("should resolve variables in code template", async () => {
+      const mockPythonActivity = vi.fn().mockResolvedValue({
+        blackboard: {},
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        input: { prefix: "result" },
+        activities: {
+          executePieceAction: vi.fn(),
+          executePythonScript: mockPythonActivity,
+        },
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "bb['${input.prefix}_data'] = 42",
+      });
+
+      await node.tick(context);
+
+      expect(mockPythonActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          code: "bb['result_data'] = 42",
+        })
+      );
+    });
+  });
+
+  describe("Environment variables", () => {
+    const originalEnv = process.env;
+
+    beforeEach(() => {
+      process.env = { ...originalEnv };
+    });
+
+    afterAll(() => {
+      process.env = originalEnv;
+    });
+
+    it("should pass allowed environment variables", async () => {
+      process.env.MY_API_KEY = "secret-123";
+      process.env.DEBUG_MODE = "true";
+
+      const mockPythonActivity = vi.fn().mockResolvedValue({
+        blackboard: {},
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          executePythonScript: mockPythonActivity,
+        },
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "import os; bb['key'] = os.environ.get('MY_API_KEY')",
+        allowedEnvVars: ["MY_API_KEY", "DEBUG_MODE"],
+      });
+
+      await node.tick(context);
+
+      expect(mockPythonActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          env: {
+            MY_API_KEY: "secret-123",
+            DEBUG_MODE: "true",
+          },
+        })
+      );
+    });
+
+    it("should not pass env vars that are not in allowedEnvVars", async () => {
+      process.env.SECRET_KEY = "should-not-pass";
+
+      const mockPythonActivity = vi.fn().mockResolvedValue({
+        blackboard: {},
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          executePythonScript: mockPythonActivity,
+        },
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "pass",
+        allowedEnvVars: [], // Explicitly empty
+      });
+
+      await node.tick(context);
+
+      expect(mockPythonActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          env: {},
+        })
+      );
+    });
+  });
+
+  describe("Node lifecycle", () => {
+    it("should clone correctly", () => {
+      const node = new PythonScript({
+        id: "original",
+        code: "bb['x'] = 1",
+        packages: ["pandas"],
+        timeout: 30000,
+      });
+
+      const cloned = node.clone() as PythonScript;
+
+      expect(cloned.id).toBe("original");
+    });
+
+    it("should reset status correctly", async () => {
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        // No activities - will fail
+      };
+
+      const node = new PythonScript({
+        id: "test",
+        code: "pass",
+      });
+
+      await node.tick(context);
+      expect(node.status()).toBe(NodeStatus.FAILURE);
+
+      node.reset();
+      expect(node.status()).toBe(NodeStatus.IDLE);
+      expect(node.lastError).toBeUndefined();
+    });
+  });
+});