@q1k-oss/btree-workflows 0.0.1

package/src/actions/generate-file.test.ts

@@ -0,0 +1,516 @@
+/**
+ * GenerateFile 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 { GenerateFile, type GenerateFileConfig } from "./generate-file.js";
+
+describe("GenerateFile 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 GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "data",
+        filename: "export.csv",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      expect(node).toBeDefined();
+      expect(node.id).toBe("test");
+    });
+
+    it("should require format", () => {
+      expect(() => {
+        new GenerateFile({
+          id: "test",
+          dataKey: "data",
+          filename: "export.csv",
+          storage: "temp",
+          outputKey: "fileResult",
+        } as GenerateFileConfig);
+      }).toThrow(/requires format/i);
+    });
+
+    it("should require dataKey", () => {
+      expect(() => {
+        new GenerateFile({
+          id: "test",
+          format: "csv",
+          filename: "export.csv",
+          storage: "temp",
+          outputKey: "fileResult",
+        } as GenerateFileConfig);
+      }).toThrow(/requires dataKey/i);
+    });
+
+    it("should require filename", () => {
+      expect(() => {
+        new GenerateFile({
+          id: "test",
+          format: "csv",
+          dataKey: "data",
+          storage: "temp",
+          outputKey: "fileResult",
+        } as GenerateFileConfig);
+      }).toThrow(/requires filename/i);
+    });
+
+    it("should require storage", () => {
+      expect(() => {
+        new GenerateFile({
+          id: "test",
+          format: "csv",
+          dataKey: "data",
+          filename: "export.csv",
+          outputKey: "fileResult",
+        } as GenerateFileConfig);
+      }).toThrow(/requires storage/i);
+    });
+
+    it("should require outputKey", () => {
+      expect(() => {
+        new GenerateFile({
+          id: "test",
+          format: "csv",
+          dataKey: "data",
+          filename: "export.csv",
+          storage: "temp",
+        } as GenerateFileConfig);
+      }).toThrow(/requires outputKey/i);
+    });
+  });
+
+  describe("Activity requirement", () => {
+    it("should fail without generateFile activity", async () => {
+      blackboard.set("data", [{ a: 1 }]);
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: undefined,
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "data",
+        filename: "export.csv",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("requires activities.generateFile");
+    });
+
+    it("should fail when activities object exists but generateFile is missing", async () => {
+      blackboard.set("data", [{ a: 1 }]);
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          // generateFile is not provided
+        } as BtreeActivities,
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "data",
+        filename: "export.csv",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("requires activities.generateFile");
+    });
+  });
+
+  describe("Data validation", () => {
+    it("should fail if data is not an array", async () => {
+      blackboard.set("data", { notAnArray: true });
+
+      const mockGenerateActivity = vi.fn();
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          generateFile: mockGenerateActivity,
+        },
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "data",
+        filename: "export.csv",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("is not an array");
+      expect(mockGenerateActivity).not.toHaveBeenCalled();
+    });
+
+    it("should fail if data key does not exist", async () => {
+      // Don't set anything in blackboard
+
+      const mockGenerateActivity = vi.fn();
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          generateFile: mockGenerateActivity,
+        },
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "missingData",
+        filename: "export.csv",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("is not an array");
+    });
+  });
+
+  describe("Execution with activity", () => {
+    it("should generate CSV file via activity", async () => {
+      blackboard.set("orders", [
+        { orderId: "1", amount: 100 },
+        { orderId: "2", amount: 200 },
+      ]);
+
+      const mockGenerateActivity = vi.fn().mockResolvedValue({
+        filename: "export.csv",
+        contentType: "text/csv",
+        size: 1024,
+        path: "/tmp/export.csv",
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          generateFile: mockGenerateActivity,
+        },
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "orders",
+        filename: "export.csv",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.SUCCESS);
+      expect(mockGenerateActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          format: "csv",
+          data: [
+            { orderId: "1", amount: 100 },
+            { orderId: "2", amount: 200 },
+          ],
+          filename: "export.csv",
+          storage: "temp",
+        })
+      );
+    });
+
+    it("should store file metadata in blackboard", async () => {
+      blackboard.set("data", [{ a: 1 }]);
+
+      const fileMetadata = {
+        filename: "export-123.csv",
+        contentType: "text/csv",
+        size: 2048,
+        path: "/storage/exports/export-123.csv",
+        url: "https://storage.example.com/exports/export-123.csv",
+      };
+
+      const mockGenerateActivity = vi.fn().mockResolvedValue(fileMetadata);
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          generateFile: mockGenerateActivity,
+        },
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "data",
+        filename: "export.csv",
+        storage: "persistent",
+        outputKey: "exportedFile",
+      });
+
+      await node.tick(context);
+
+      expect(blackboard.get("exportedFile")).toEqual(fileMetadata);
+    });
+
+    it("should resolve filename from variables", async () => {
+      blackboard.set("data", [{ a: 1 }]);
+      blackboard.set("timestamp", "2024-01-15");
+
+      const mockGenerateActivity = vi.fn().mockResolvedValue({
+        filename: "report-2024-01-15.csv",
+        contentType: "text/csv",
+        size: 512,
+        path: "/tmp/report-2024-01-15.csv",
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        input: { reportType: "sales" },
+        activities: {
+          executePieceAction: vi.fn(),
+          generateFile: mockGenerateActivity,
+        },
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "data",
+        filename: "${input.reportType}-${bb.timestamp}.csv",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      await node.tick(context);
+
+      expect(mockGenerateActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filename: "sales-2024-01-15.csv",
+        })
+      );
+    });
+
+    it("should pass column definitions to activity", async () => {
+      blackboard.set("orders", [
+        { id: "1", customer: "Alice", total: 100 },
+      ]);
+
+      const mockGenerateActivity = vi.fn().mockResolvedValue({
+        filename: "orders.xlsx",
+        contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        size: 4096,
+        path: "/tmp/orders.xlsx",
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          generateFile: mockGenerateActivity,
+        },
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "xlsx",
+        dataKey: "orders",
+        columns: [
+          { header: "Order ID", key: "id", width: 10 },
+          { header: "Customer Name", key: "customer", width: 25 },
+          { header: "Total Amount", key: "total", width: 15 },
+        ],
+        filename: "orders.xlsx",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      await node.tick(context);
+
+      expect(mockGenerateActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          format: "xlsx",
+          columns: [
+            { header: "Order ID", key: "id", width: 10 },
+            { header: "Customer Name", key: "customer", width: 25 },
+            { header: "Total Amount", key: "total", width: 15 },
+          ],
+        })
+      );
+    });
+
+    it("should generate JSON file", async () => {
+      blackboard.set("data", [{ key: "value" }]);
+
+      const mockGenerateActivity = vi.fn().mockResolvedValue({
+        filename: "data.json",
+        contentType: "application/json",
+        size: 256,
+        path: "/tmp/data.json",
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          generateFile: mockGenerateActivity,
+        },
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "json",
+        dataKey: "data",
+        filename: "data.json",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      await node.tick(context);
+
+      expect(mockGenerateActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          format: "json",
+        })
+      );
+    });
+
+    it("should handle activity errors", async () => {
+      blackboard.set("data", [{ a: 1 }]);
+
+      const mockGenerateActivity = vi.fn().mockRejectedValue(
+        new Error("Disk full: cannot write file")
+      );
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          generateFile: mockGenerateActivity,
+        },
+      };
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "data",
+        filename: "export.csv",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("Disk full");
+    });
+  });
+
+  describe("Node lifecycle", () => {
+    it("should clone correctly", () => {
+      const node = new GenerateFile({
+        id: "original",
+        format: "csv",
+        dataKey: "data",
+        filename: "export.csv",
+        storage: "persistent",
+        outputKey: "fileResult",
+      });
+
+      const cloned = node.clone() as GenerateFile;
+
+      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
+      };
+
+      blackboard.set("data", [{ a: 1 }]);
+
+      const node = new GenerateFile({
+        id: "test",
+        format: "csv",
+        dataKey: "data",
+        filename: "export.csv",
+        storage: "temp",
+        outputKey: "fileResult",
+      });
+
+      await node.tick(context);
+      expect(node.status()).toBe(NodeStatus.FAILURE);
+
+      node.reset();
+      expect(node.status()).toBe(NodeStatus.IDLE);
+      expect(node.lastError).toBeUndefined();
+    });
+  });
+});

package/src/actions/generate-file.ts

@@ -0,0 +1,166 @@
+/**
+ * GenerateFile Node
+ *
+ * Generates CSV/Excel/JSON files from data via a Temporal activity.
+ * This node requires the `generateFile` 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, Excel (xlsx), and JSON output formats
+ * - Column definitions with header names and widths
+ * - Temporary or persistent storage
+ * - Result metadata stored in blackboard (filename, path, URL)
+ */
+
+import { ActionNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  type GenerateFileRequest,
+  NodeStatus,
+} from "../types.js";
+import { resolveValue, type VariableContext } from "../utilities/variable-resolver.js";
+
+/**
+ * Configuration for GenerateFile node
+ */
+export interface GenerateFileConfig extends NodeConfiguration {
+  /** Output format */
+  format: "csv" | "xlsx" | "json";
+  /** Data source (blackboard key) */
+  dataKey: string;
+  /** Column definitions */
+  columns?: Array<{ header: string; key: string; width?: number }>;
+  /** Output filename template (supports ${input.x}, ${bb.x}) */
+  filename: string;
+  /** Storage type */
+  storage: "temp" | "persistent";
+  /** Output key for file metadata (path, url, size) */
+  outputKey: string;
+}
+
+/**
+ * GenerateFile Node
+ *
+ * Generates a file from data in the blackboard and stores file metadata.
+ * Requires the `generateFile` activity to be configured.
+ *
+ * @example YAML
+ * ```yaml
+ * type: GenerateFile
+ * id: export-report
+ * props:
+ *   format: csv
+ *   dataKey: "processedOrders"
+ *   columns:
+ *     - header: "Order ID"
+ *       key: "orderId"
+ *     - header: "Customer"
+ *       key: "customerName"
+ *     - header: "Total"
+ *       key: "amount"
+ *       width: 15
+ *   filename: "orders-${bb.timestamp}.csv"
+ *   storage: persistent
+ *   outputKey: "exportedFile"
+ * ```
+ */
+export class GenerateFile extends ActionNode {
+  private format: GenerateFileConfig["format"];
+  private dataKey: string;
+  private columns?: GenerateFileConfig["columns"];
+  private filename: string;
+  private storage: GenerateFileConfig["storage"];
+  private outputKey: string;
+
+  constructor(config: GenerateFileConfig) {
+    super(config);
+
+    if (!config.format) {
+      throw new ConfigurationError("GenerateFile requires format");
+    }
+
+    if (!config.dataKey) {
+      throw new ConfigurationError("GenerateFile requires dataKey");
+    }
+
+    if (!config.filename) {
+      throw new ConfigurationError("GenerateFile requires filename");
+    }
+
+    if (!config.storage) {
+      throw new ConfigurationError("GenerateFile requires storage");
+    }
+
+    if (!config.outputKey) {
+      throw new ConfigurationError("GenerateFile requires outputKey");
+    }
+
+    this.format = config.format;
+    this.dataKey = config.dataKey;
+    this.columns = config.columns;
+    this.filename = config.filename;
+    this.storage = config.storage;
+    this.outputKey = config.outputKey;
+  }
+
+  protected async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    // Validate activity is available
+    if (!context.activities?.generateFile) {
+      this._lastError =
+        "GenerateFile requires activities.generateFile 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,
+      };
+
+      // Get data from blackboard
+      const data = context.blackboard.get(this.dataKey);
+      if (!Array.isArray(data)) {
+        this._lastError = `Data at '${this.dataKey}' is not an array (got ${typeof data})`;
+        this.log(`Error: ${this._lastError}`);
+        return NodeStatus.FAILURE;
+      }
+
+      const resolvedFilename = resolveValue(this.filename, varCtx) as string;
+
+      const request: GenerateFileRequest = {
+        format: this.format,
+        data: data as Record<string, unknown>[],
+        columns: this.columns,
+        filename: resolvedFilename,
+        storage: this.storage,
+      };
+
+      this.log(
+        `Generating ${this.format} file: ${resolvedFilename} ` +
+        `(${data.length} rows, storage: ${this.storage})`
+      );
+
+      const result = await context.activities.generateFile(request);
+
+      // Store file metadata in blackboard
+      context.blackboard.set(this.outputKey, result);
+
+      this.log(
+        `Generated file: ${result.filename} ` +
+        `(${result.size} bytes, path: ${result.path})`
+      );
+
+      return NodeStatus.SUCCESS;
+    } catch (error) {
+      this._lastError = error instanceof Error ? error.message : String(error);
+      this.log(`Generate file failed: ${this._lastError}`);
+      return NodeStatus.FAILURE;
+    }
+  }
+}