@q1k-oss/btree-workflows 0.0.1

package/src/utilities/log-message.test.ts

@@ -0,0 +1,275 @@
+/**
+ * Tests for LogMessage Node
+ */
+
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import { NodeEventEmitter, NodeEventType } from "../events.js";
+import {
+  type TemporalContext,
+  NodeStatus,
+  ScopedBlackboard,
+} from "../index.js";
+import { LogMessage } from "./log-message.js";
+
+describe("LogMessage", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+  let consoleLogSpy: unknown;
+  let consoleWarnSpy: unknown;
+  let consoleErrorSpy: unknown;
+  let consoleDebugSpy: unknown;
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard();
+    context = {
+      blackboard: blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+
+    // Spy on console methods
+    consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    consoleDebugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  it("should log a simple message", async () => {
+    const node = new LogMessage({
+      id: "log-1",
+      message: "Test message",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[LogMessage:log-1] Test message"),
+    );
+  });
+
+  it("should log message with blackboard value placeholder", async () => {
+    blackboard.set("username", "testuser");
+    blackboard.set("count", 42);
+
+    const node = new LogMessage({
+      id: "log-2",
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: This is intentional - LogMessage processes ${} syntax
+      message: "User: ${username}, Count: ${count}",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[LogMessage:log-2] User: testuser, Count: 42"),
+    );
+  });
+
+  it("should handle missing blackboard values", async () => {
+    const node = new LogMessage({
+      id: "log-3",
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: This is intentional - LogMessage processes ${} syntax
+      message: "Value: ${missingKey}",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    // Should keep the placeholder if value is missing
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: This is intentional - testing placeholder syntax
+      expect.stringContaining("[LogMessage:log-3] Value: ${missingKey}"),
+    );
+  });
+
+  it("should handle null values", async () => {
+    blackboard.set("nullValue", null);
+
+    const node = new LogMessage({
+      id: "log-4",
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: This is intentional - LogMessage processes ${} syntax
+      message: "Null value: ${nullValue}",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[LogMessage:log-4] Null value: null"),
+    );
+  });
+
+  it("should handle object values", async () => {
+    blackboard.set("user", { name: "John", age: 30 });
+
+    const node = new LogMessage({
+      id: "log-5",
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: This is intentional - LogMessage processes ${} syntax
+      message: "User: ${user}",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        '[LogMessage:log-5] User: {"name":"John","age":30}',
+      ),
+    );
+  });
+
+  it("should log with warn level", async () => {
+    const node = new LogMessage({
+      id: "log-6",
+      message: "Warning message",
+      level: "warn",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleWarnSpy).toHaveBeenCalled();
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+  });
+
+  it("should log with error level", async () => {
+    const node = new LogMessage({
+      id: "log-7",
+      message: "Error message",
+      level: "error",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+  });
+
+  it("should log with debug level", async () => {
+    const node = new LogMessage({
+      id: "log-8",
+      message: "Debug message",
+      level: "debug",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleDebugSpy).toHaveBeenCalled();
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+  });
+
+  it("should default to info level", async () => {
+    const node = new LogMessage({
+      id: "log-9",
+      message: "Info message",
+      // level not specified
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleLogSpy).toHaveBeenCalled();
+  });
+
+  it("should handle multiple placeholders", async () => {
+    blackboard.set("name", "Alice");
+    blackboard.set("age", 25);
+    blackboard.set("city", "New York");
+
+    const node = new LogMessage({
+      id: "log-10",
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: This is intentional - LogMessage processes ${} syntax
+      message: "${name} is ${age} years old and lives in ${city}",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "[LogMessage:log-10] Alice is 25 years old and lives in New York",
+      ),
+    );
+  });
+
+  it("should handle array values", async () => {
+    blackboard.set("items", ["apple", "banana", "cherry"]);
+
+    const node = new LogMessage({
+      id: "log-11",
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: This is intentional - LogMessage processes ${} syntax
+      message: "Items: ${items}",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        '[LogMessage:log-11] Items: ["apple","banana","cherry"]',
+      ),
+    );
+  });
+
+  describe("LOG event emission", () => {
+    it("should emit LOG event when executed with event emitter", async () => {
+      const eventEmitter = new NodeEventEmitter();
+      const receivedEvents: unknown[] = [];
+
+      eventEmitter.on(NodeEventType.LOG, (event) => {
+        receivedEvents.push(event);
+      });
+
+      const contextWithEmitter: TemporalContext = {
+        ...context,
+        eventEmitter,
+      };
+
+      const node = new LogMessage({
+        id: "log-event",
+        name: "EventTest",
+        message: "Event test message",
+        level: "warn",
+      });
+
+      await node.tick(contextWithEmitter);
+
+      expect(receivedEvents).toHaveLength(1);
+      const event = receivedEvents[0] as {
+        type: string;
+        nodeId: string;
+        data: { level: string; message: string };
+      };
+      expect(event.type).toBe(NodeEventType.LOG);
+      expect(event.nodeId).toBe("log-event");
+      expect(event.data.level).toBe("warn");
+      expect(event.data.message).toBe("Event test message");
+    });
+
+    it("should not fail when no event emitter present", async () => {
+      const node = new LogMessage({
+        id: "log-no-emitter",
+        message: "No emitter test",
+      });
+
+      // Context without eventEmitter
+      const result = await node.tick(context);
+
+      expect(result).toBe(NodeStatus.SUCCESS);
+    });
+  });
+});

package/src/utilities/log-message.ts

@@ -0,0 +1,134 @@
+/**
+ * LogMessage Node - Log messages for debugging and test visibility
+ *
+ * Utility node that logs messages to console with optional variable resolution.
+ * Useful for debugging test flows and tracking execution progress.
+ *
+ * Supports variable resolution:
+ * - ${key} - Shorthand for blackboard (backward compatible)
+ * - ${input.key} - Workflow input parameters
+ * - ${bb.key} - Blackboard values
+ * - ${env.KEY} - Environment variables
+ * - ${param.key} - Test data parameters
+ *
+ * Use Cases:
+ * - Log intermediate values during test execution
+ * - Debug blackboard state at specific points
+ * - Add visibility to test steps
+ * - Track execution flow
+ *
+ * Examples:
+ * - Log static message: <LogMessage message="Starting form submission" />
+ * - Log blackboard value: <LogMessage message="Current URL: ${currentUrl}" />
+ * - Log input value: <LogMessage message="Order ID: ${input.orderId}" />
+ * - Log with level: <LogMessage message="Error occurred" level="error" />
+ */
+
+import { ActionNode } from "../base-node.js";
+import { NodeEventType } from "../events.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  NodeStatus,
+} from "../types.js";
+import { resolveString, type VariableContext } from "./variable-resolver.js";
+
+/**
+ * Configuration for LogMessage node
+ */
+export interface LogMessageConfig extends NodeConfiguration {
+  message: string; // Message to log (supports ${key}, ${input.key}, ${bb.key}, ${env.KEY})
+  level?: "info" | "warn" | "error" | "debug"; // Log level (default: 'info')
+}
+
+/**
+ * LogMessage Node - Logs messages with optional variable resolution
+ */
+export class LogMessage extends ActionNode {
+  private message: string;
+  private level: "info" | "warn" | "error" | "debug";
+
+  constructor(config: LogMessageConfig) {
+    super(config);
+    this.message = config.message;
+    this.level = config.level || "info";
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    try {
+      // Resolve variable references in message
+      const resolvedMessage = this.resolveMessage(this.message, context);
+
+      // Log based on level
+      switch (this.level) {
+        case "warn":
+          console.warn(`[LogMessage:${this.name}] ${resolvedMessage}`);
+          break;
+        case "error":
+          console.error(`[LogMessage:${this.name}] ${resolvedMessage}`);
+          break;
+        case "debug":
+          console.debug(`[LogMessage:${this.name}] ${resolvedMessage}`);
+          break;
+        default:
+          console.log(`[LogMessage:${this.name}] ${resolvedMessage}`);
+          break;
+      }
+
+      // Emit LOG event for collection
+      context.eventEmitter?.emit({
+        type: NodeEventType.LOG,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { level: this.level, message: resolvedMessage },
+      });
+
+      this._status = NodeStatus.SUCCESS;
+      return NodeStatus.SUCCESS;
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      console.error(
+        `[LogMessage:${this.name}] Failed to log message: ${errorMessage}`,
+      );
+      this._status = NodeStatus.FAILURE;
+      return NodeStatus.FAILURE;
+    }
+  }
+
+  /**
+   * Resolve variable references in message string
+   * Supports ${key}, ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}
+   */
+  private resolveMessage(message: string, context: TemporalContext): string {
+    const varCtx: VariableContext = {
+      blackboard: context.blackboard,
+      input: context.input,
+      testData: context.testData,
+    };
+
+    const resolved = resolveString(message, varCtx);
+
+    // Always return a string for logging
+    if (typeof resolved === "string") {
+      return resolved;
+    }
+
+    // If resolved to non-string (shouldn't happen for message templates), stringify
+    if (resolved === null) {
+      return "null";
+    }
+
+    if (typeof resolved === "object") {
+      try {
+        return JSON.stringify(resolved);
+      } catch {
+        return String(resolved);
+      }
+    }
+
+    return String(resolved);
+  }
+}

package/src/utilities/regex-extract.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Tests for RegexExtract Node
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  type TemporalContext,
+  NodeStatus,
+  ScopedBlackboard,
+} from "../index.js";
+import { RegexExtract } from "./regex-extract.js";
+
+describe("RegexExtract", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard();
+    context = {
+      blackboard: blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should extract all matches when matchIndex is not specified", async () => {
+    blackboard.set("text", "Contact: support@example.com, sales@example.com");
+
+    const node = new RegexExtract({
+      id: "extract-emails",
+      input: "text",
+      pattern: "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
+      outputKey: "emails",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    const emails = blackboard.get("emails");
+    expect(emails).toEqual(["support@example.com", "sales@example.com"]);
+  });
+
+  it("should extract specific match when matchIndex is specified", async () => {
+    blackboard.set("text", "Price: $99.99 and $149.99");
+
+    const node = new RegexExtract({
+      id: "extract-price",
+      input: "text",
+      pattern: "\\$\\d+\\.\\d{2}",
+      outputKey: "firstPrice",
+      matchIndex: 0,
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    const price = blackboard.get("firstPrice");
+    expect(price).toBe("$99.99");
+  });
+
+  it("should return null when matchIndex is out of bounds", async () => {
+    blackboard.set("text", "No numbers here");
+
+    const node = new RegexExtract({
+      id: "extract-number",
+      input: "text",
+      pattern: "\\d+",
+      outputKey: "number",
+      matchIndex: 0,
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    const number = blackboard.get("number");
+    expect(number).toBeNull();
+  });
+
+  it("should return empty array when no matches found", async () => {
+    blackboard.set("text", "No emails here");
+
+    const node = new RegexExtract({
+      id: "extract-emails",
+      input: "text",
+      pattern: "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
+      outputKey: "emails",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    const emails = blackboard.get("emails");
+    expect(emails).toEqual([]);
+  });
+
+  it("should fail when input is not a string", async () => {
+    blackboard.set("text", 123);
+
+    const node = new RegexExtract({
+      id: "extract",
+      input: "text",
+      pattern: "\\d+",
+      outputKey: "result",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should fail when input is not found in blackboard", async () => {
+    const node = new RegexExtract({
+      id: "extract",
+      input: "missing",
+      pattern: "\\d+",
+      outputKey: "result",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should fail when regex pattern is invalid", async () => {
+    blackboard.set("text", "test");
+
+    const node = new RegexExtract({
+      id: "extract",
+      input: "text",
+      pattern: "[invalid",
+      outputKey: "result",
+    });
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.FAILURE);
+  });
+});

package/src/utilities/regex-extract.ts

@@ -0,0 +1,108 @@
+/**
+ * RegexExtract Node - Extract text using regular expressions
+ *
+ * Data manipulation utility node that operates on blackboard values.
+ * Extracts matches from a text string using a regex pattern.
+ *
+ * Use Cases:
+ * - Extract email addresses from text
+ * - Extract numbers/IDs from strings
+ * - Parse structured data from unstructured text
+ * - Extract URLs from content
+ */
+
+import { ActionNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  NodeStatus,
+} from "../types.js";
+
+/**
+ * Configuration for RegexExtract node
+ */
+export interface RegexExtractConfig extends NodeConfiguration {
+  input: string; // Blackboard key containing text to extract from
+  pattern: string; // Regular expression pattern
+  outputKey: string; // Blackboard key to store extracted matches
+  flags?: string; // Regex flags (default: "g" for global)
+  matchIndex?: number; // Which match to return (0 = first, undefined = all matches array)
+}
+
+/**
+ * RegexExtract Node - Extracts text using regular expressions
+ */
+export class RegexExtract extends ActionNode {
+  private input: string;
+  private pattern: string;
+  private outputKey: string;
+  private flags: string;
+  private matchIndex?: number;
+
+  constructor(config: RegexExtractConfig) {
+    super(config);
+    this.input = config.input;
+    this.pattern = config.pattern;
+    this.outputKey = config.outputKey;
+    this.flags = config.flags || "g";
+    this.matchIndex = config.matchIndex;
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    try {
+      // Get input text from blackboard
+      const text = context.blackboard.get(this.input);
+
+      // Validate input
+      if (text === undefined || text === null) {
+        throw new ConfigurationError(
+          `Input '${this.input}' not found in blackboard`,
+        );
+      }
+
+      if (typeof text !== "string") {
+        throw new ConfigurationError(
+          `Input '${this.input}' must be a string, got ${typeof text}`,
+        );
+      }
+
+      // Create regex from pattern and flags
+      let regex: RegExp;
+      try {
+        regex = new RegExp(this.pattern, this.flags);
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid regex pattern: ${errorMessage}`);
+      }
+
+      // Extract matches
+      const matches = text.match(regex) || [];
+
+      // Determine output value
+      let result: string | string[] | null;
+      if (this.matchIndex !== undefined && this.matchIndex >= 0) {
+        // Return specific match
+        result = matches[this.matchIndex] || null;
+        this.log(`Extracted match at index ${this.matchIndex}: ${result}`);
+      } else {
+        // Return all matches as array
+        result = matches;
+        this.log(`Extracted ${matches.length} match(es) from input`);
+      }
+
+      // Store result in blackboard
+      this.setOutput(context, this.outputKey, result);
+
+      this._status = NodeStatus.SUCCESS;
+      return NodeStatus.SUCCESS;
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      this.log(`RegexExtract failed: ${errorMessage}`);
+      this._status = NodeStatus.FAILURE;
+      return NodeStatus.FAILURE;
+    }
+  }
+}