@q1k-oss/btree-workflows 0.0.1

package/src/templates/template-loader.test.ts

@@ -0,0 +1,281 @@
+/**
+ * Template Loader Tests
+ * TDD: Write tests first, then implement to make them pass
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { Registry } from "../registry.js";
+import { registerStandardNodes } from "../registry-utils.js";
+import {
+  loadTemplatesFromDirectory,
+  loadTemplate,
+} from "./template-loader.js";
+
+describe("Template Loader", () => {
+  let registry: Registry;
+  let tempDir: string;
+
+  beforeEach(() => {
+    // Create fresh registry with standard nodes
+    registry = new Registry();
+    registerStandardNodes(registry);
+
+    // Create temp directory for test templates
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "btree-templates-"));
+  });
+
+  afterEach(() => {
+    // Clean up temp directory
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe("loadTemplatesFromDirectory", () => {
+    it("should load all YAML files from directory", async () => {
+      // Create test template files
+      const template1 = `
+type: Sequence
+id: template-one
+children:
+  - type: LogMessage
+    id: log1
+    props:
+      message: "Template 1"
+`;
+      const template2 = `
+type: Sequence
+id: template-two
+children:
+  - type: LogMessage
+    id: log2
+    props:
+      message: "Template 2"
+`;
+
+      fs.writeFileSync(path.join(tempDir, "template-one.yaml"), template1);
+      fs.writeFileSync(path.join(tempDir, "template-two.yaml"), template2);
+
+      const loadedIds = await loadTemplatesFromDirectory(registry, {
+        templatesDir: tempDir,
+      });
+
+      expect(loadedIds).toHaveLength(2);
+      expect(loadedIds).toContain("template-one");
+      expect(loadedIds).toContain("template-two");
+    });
+
+    it("should register templates in the registry", async () => {
+      const template = `
+type: Sequence
+id: my-template
+children:
+  - type: LogMessage
+    id: log
+    props:
+      message: "Hello"
+`;
+      fs.writeFileSync(path.join(tempDir, "my-template.yaml"), template);
+
+      await loadTemplatesFromDirectory(registry, { templatesDir: tempDir });
+
+      expect(registry.hasTree("my-template")).toBe(true);
+    });
+
+    it("should use filename as template ID", async () => {
+      const template = `
+type: Sequence
+id: internal-id
+children:
+  - type: LogMessage
+    id: log
+    props:
+      message: "Test"
+`;
+      fs.writeFileSync(path.join(tempDir, "external-name.yaml"), template);
+
+      await loadTemplatesFromDirectory(registry, { templatesDir: tempDir });
+
+      // Template ID should be filename, not internal id
+      expect(registry.hasTree("external-name")).toBe(true);
+    });
+
+    it("should support .yml extension", async () => {
+      const template = `
+type: Sequence
+id: yml-template
+children:
+  - type: LogMessage
+    id: log
+    props:
+      message: "YML extension"
+`;
+      fs.writeFileSync(path.join(tempDir, "yml-template.yml"), template);
+
+      const loadedIds = await loadTemplatesFromDirectory(registry, {
+        templatesDir: tempDir,
+      });
+
+      expect(loadedIds).toContain("yml-template");
+    });
+
+    it("should apply ID prefix when provided", async () => {
+      const template = `
+type: Sequence
+id: test
+children:
+  - type: LogMessage
+    id: log
+    props:
+      message: "Prefixed"
+`;
+      fs.writeFileSync(path.join(tempDir, "my-template.yaml"), template);
+
+      await loadTemplatesFromDirectory(registry, {
+        templatesDir: tempDir,
+        idPrefix: "tpl:",
+      });
+
+      expect(registry.hasTree("tpl:my-template")).toBe(true);
+    });
+
+    it("should return empty array for empty directory", async () => {
+      const loadedIds = await loadTemplatesFromDirectory(registry, {
+        templatesDir: tempDir,
+      });
+
+      expect(loadedIds).toHaveLength(0);
+    });
+
+    it("should ignore non-YAML files", async () => {
+      fs.writeFileSync(path.join(tempDir, "readme.md"), "# README");
+      fs.writeFileSync(path.join(tempDir, "config.json"), "{}");
+
+      const template = `
+type: Sequence
+id: only-yaml
+children:
+  - type: LogMessage
+    id: log
+    props:
+      message: "Only YAML"
+`;
+      fs.writeFileSync(path.join(tempDir, "valid.yaml"), template);
+
+      const loadedIds = await loadTemplatesFromDirectory(registry, {
+        templatesDir: tempDir,
+      });
+
+      expect(loadedIds).toHaveLength(1);
+      expect(loadedIds).toContain("valid");
+    });
+
+    it("should throw error for invalid YAML syntax", async () => {
+      fs.writeFileSync(path.join(tempDir, "invalid.yaml"), "invalid: yaml: content:");
+
+      await expect(
+        loadTemplatesFromDirectory(registry, { templatesDir: tempDir })
+      ).rejects.toThrow();
+    });
+
+    it("should throw error for invalid tree structure", async () => {
+      const invalidTemplate = `
+type: UnknownNodeType
+id: invalid
+`;
+      fs.writeFileSync(path.join(tempDir, "invalid.yaml"), invalidTemplate);
+
+      await expect(
+        loadTemplatesFromDirectory(registry, { templatesDir: tempDir })
+      ).rejects.toThrow();
+    });
+  });
+
+  describe("loadTemplate", () => {
+    it("should load a single template file", () => {
+      const template = `
+type: Sequence
+id: single
+children:
+  - type: LogMessage
+    id: log
+    props:
+      message: "Single template"
+`;
+      const filePath = path.join(tempDir, "single.yaml");
+      fs.writeFileSync(filePath, template);
+
+      const id = loadTemplate(registry, filePath);
+
+      expect(id).toBe("single");
+      expect(registry.hasTree("single")).toBe(true);
+    });
+
+    it("should use custom ID when provided", () => {
+      const template = `
+type: Sequence
+id: default
+children:
+  - type: LogMessage
+    id: log
+    props:
+      message: "Custom ID"
+`;
+      const filePath = path.join(tempDir, "default.yaml");
+      fs.writeFileSync(filePath, template);
+
+      const id = loadTemplate(registry, filePath, "custom-id");
+
+      expect(id).toBe("custom-id");
+      expect(registry.hasTree("custom-id")).toBe(true);
+    });
+
+    it("should throw error for non-existent file", () => {
+      expect(() => {
+        loadTemplate(registry, "/non/existent/path.yaml");
+      }).toThrow();
+    });
+  });
+
+  describe("Template execution via SubTree", () => {
+    it("should allow SubTree to reference loaded template", async () => {
+      // Create and load a template
+      const template = `
+type: Sequence
+id: reusable
+children:
+  - type: LogMessage
+    id: log
+    props:
+      message: "Reusable template executed"
+`;
+      const filePath = path.join(tempDir, "reusable.yaml");
+      fs.writeFileSync(filePath, template);
+      loadTemplate(registry, filePath);
+
+      // Verify template can be cloned (as SubTree would do)
+      const clonedTree = registry.cloneTree("reusable");
+      expect(clonedTree).toBeDefined();
+      expect(clonedTree.getRoot()).toBeDefined();
+    });
+
+    it("should track source file for templates", () => {
+      const template = `
+type: Sequence
+id: tracked
+children:
+  - type: LogMessage
+    id: log
+    props:
+      message: "Tracked"
+`;
+      const filePath = path.join(tempDir, "tracked.yaml");
+      fs.writeFileSync(filePath, template);
+      loadTemplate(registry, filePath);
+
+      const sourceFile = registry.getTreeSourceFile("tracked");
+      expect(sourceFile).toBe(filePath);
+    });
+  });
+});

package/src/templates/template-loader.ts

@@ -0,0 +1,152 @@
+/**
+ * Template Loader
+ * Load YAML template files from a directory and register them in the btree Registry.
+ * Templates can then be referenced by SubTree nodes using their template ID.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { Registry } from "../registry.js";
+import { loadTreeFromYaml } from "../yaml/index.js";
+import { BehaviorTree } from "../behavior-tree.js";
+
+/**
+ * Options for loading templates from a directory
+ */
+export interface TemplateLoaderOptions {
+  /** Path to the templates directory */
+  templatesDir: string;
+  /** Optional prefix to add to all template IDs (e.g., "tpl:") */
+  idPrefix?: string;
+}
+
+/**
+ * Load all template YAML files from a directory and register them in the registry.
+ *
+ * Each YAML file becomes a registered BehaviorTree that can be referenced
+ * by SubTree nodes using the filename (without extension) as the tree ID.
+ *
+ * @param registry - The Registry instance to register templates in
+ * @param options - Configuration options
+ * @returns Array of template IDs that were loaded
+ *
+ * @example
+ * ```typescript
+ * const registry = new Registry();
+ * registerStandardNodes(registry);
+ *
+ * const loadedIds = await loadTemplatesFromDirectory(registry, {
+ *   templatesDir: './templates',
+ *   idPrefix: 'tpl:'
+ * });
+ *
+ * // Templates can now be used via SubTree:
+ * // type: SubTree
+ * //   props:
+ * //     treeId: "tpl:order-validation"
+ * ```
+ */
+export async function loadTemplatesFromDirectory(
+  registry: Registry,
+  options: TemplateLoaderOptions
+): Promise<string[]> {
+  const { templatesDir, idPrefix = "" } = options;
+  const loadedIds: string[] = [];
+
+  // Ensure directory exists
+  if (!fs.existsSync(templatesDir)) {
+    console.warn(
+      `[TemplateLoader] Templates directory not found: ${templatesDir}`
+    );
+    return loadedIds;
+  }
+
+  // Find all YAML files in directory
+  const files = fs
+    .readdirSync(templatesDir)
+    .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+
+  // Load each file
+  for (const file of files) {
+    const filePath = path.join(templatesDir, file);
+
+    try {
+      // Read and parse YAML content
+      const yamlContent = fs.readFileSync(filePath, "utf-8");
+      const rootNode = loadTreeFromYaml(yamlContent, registry);
+      const tree = new BehaviorTree(rootNode);
+
+      // Derive template ID from filename (without extension)
+      const baseName = path.basename(file, path.extname(file));
+      const templateId = idPrefix + baseName;
+
+      // Register in registry
+      registry.registerTree(templateId, tree, filePath);
+      loadedIds.push(templateId);
+
+      console.log(`[TemplateLoader] Registered template: ${templateId}`);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Failed to load template '${file}': ${errorMessage}`
+      );
+    }
+  }
+
+  console.log(
+    `[TemplateLoader] Loaded ${loadedIds.length} template(s) from ${templatesDir}`
+  );
+  return loadedIds;
+}
+
+/**
+ * Load a single template file and register it in the registry.
+ *
+ * @param registry - The Registry instance to register the template in
+ * @param filePath - Path to the YAML template file
+ * @param templateId - Optional custom ID for the template (defaults to filename)
+ * @returns The template ID that was registered
+ *
+ * @example
+ * ```typescript
+ * const id = loadTemplate(registry, './templates/order-validation.yaml');
+ * // Template is now available as "order-validation"
+ *
+ * const customId = loadTemplate(registry, './special.yaml', 'my-custom-id');
+ * // Template is now available as "my-custom-id"
+ * ```
+ */
+export function loadTemplate(
+  registry: Registry,
+  filePath: string,
+  templateId?: string
+): string {
+  // Read and parse YAML content
+  const yamlContent = fs.readFileSync(filePath, "utf-8");
+  const rootNode = loadTreeFromYaml(yamlContent, registry);
+  const tree = new BehaviorTree(rootNode);
+
+  // Derive template ID from filename if not provided
+  const id = templateId || path.basename(filePath, path.extname(filePath));
+
+  // Register in registry
+  registry.registerTree(id, tree, filePath);
+
+  console.log(`[TemplateLoader] Registered template: ${id} from ${filePath}`);
+  return id;
+}
+
+/**
+ * Check if a template exists in the registry
+ */
+export function hasTemplate(registry: Registry, templateId: string): boolean {
+  return registry.hasTree(templateId);
+}
+
+/**
+ * Get all registered template IDs
+ */
+export function getTemplateIds(registry: Registry): string[] {
+  return registry.getAllTreeIds();
+}

package/src/temporal-integration.test.ts

@@ -0,0 +1,213 @@
+/**
+ * Temporal Integration Tests
+ * Validates that behavior trees work correctly as Temporal workflows
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { TestWorkflowEnvironment } from "@temporalio/testing";
+import { BehaviorTree } from "./behavior-tree.js";
+import { Sequence } from "./composites/sequence.js";
+import { Selector } from "./composites/selector.js";
+import { Parallel, ParallelStrategy } from "./composites/parallel.js";
+import { PrintAction, MockAction, CounterAction } from "./test-nodes.js";
+import { Timeout } from "./decorators/timeout.js";
+import { Delay } from "./decorators/delay.js";
+import { NodeStatus } from "./types.js";
+import { Registry } from "./registry.js";
+
+describe.skip("Temporal Integration", () => {
+  let testEnv: TestWorkflowEnvironment;
+
+  beforeAll(async () => {
+    testEnv = await TestWorkflowEnvironment.createLocal();
+  }, 60000); // 60 second timeout for creating test environment
+
+  afterAll(async () => {
+    await testEnv?.teardown();
+  });
+
+  it("should execute simple sequence workflow", async () => {
+    const root = new Sequence({ id: "root" });
+    root.addChild(new PrintAction({ id: "step1", message: "Hello" }));
+    root.addChild(new PrintAction({ id: "step2", message: "World" }));
+
+    const tree = new BehaviorTree(root);
+    const workflow = tree.toWorkflow();
+
+    const treeRegistry = new Registry();
+    const result = await workflow({ input: {}, treeRegistry });
+
+    expect(result.status).toBe(NodeStatus.SUCCESS);
+    expect(result.output).toBeDefined();
+  });
+
+  it("should handle selector (fallback) logic", async () => {
+    const root = new Selector({ id: "root" });
+    root.addChild(new MockAction({ id: "fail1", returnStatus: NodeStatus.FAILURE }));
+    root.addChild(new MockAction({ id: "fail2", returnStatus: NodeStatus.FAILURE }));
+    root.addChild(new MockAction({ id: "success", returnStatus: NodeStatus.SUCCESS }));
+
+    const tree = new BehaviorTree(root);
+    const workflow = tree.toWorkflow();
+
+    const treeRegistry = new Registry();
+    const result = await workflow({ input: {}, treeRegistry });
+
+    expect(result.status).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should execute parallel nodes concurrently", async () => {
+    const root = new Parallel({
+      id: "root",
+      strategy: ParallelStrategy.JOIN_ALL,
+      threshold: 3,
+    });
+    root.addChild(new MockAction({ id: "task1", returnStatus: NodeStatus.SUCCESS }));
+    root.addChild(new MockAction({ id: "task2", returnStatus: NodeStatus.SUCCESS }));
+    root.addChild(new MockAction({ id: "task3", returnStatus: NodeStatus.SUCCESS }));
+
+    const tree = new BehaviorTree(root);
+    const workflow = tree.toWorkflow();
+
+    const treeRegistry = new Registry();
+    const result = await workflow({ input: {}, treeRegistry });
+
+    expect(result.status).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should handle blackboard input and output", async () => {
+    const root = new Sequence({ id: "root" });
+    root.addChild(new CounterAction({ id: "increment1", counterKey: "count", increment: 5 }));
+    root.addChild(new CounterAction({ id: "increment2", counterKey: "count", increment: 3 }));
+
+    const tree = new BehaviorTree(root);
+    const workflow = tree.toWorkflow();
+
+    const treeRegistry = new Registry();
+    const result = await workflow({
+      input: { count: 10 },
+      treeRegistry
+    });
+
+    expect(result.status).toBe(NodeStatus.SUCCESS);
+    expect(result.output.count).toBe(18); // 10 + 5 + 3
+  });
+
+  // NOTE: Retry decorator removed - use Temporal's native RetryPolicy instead
+
+  it("should handle timeout decorator", async () => {
+    const timeout = new Timeout({
+      id: "timeout",
+      timeoutMs: 100,
+    });
+    const fastAction = new MockAction({
+      id: "fast",
+      returnStatus: NodeStatus.SUCCESS,
+      ticksBeforeComplete: 1,
+    });
+    timeout.setChild(fastAction);
+
+    const tree = new BehaviorTree(timeout);
+    const workflow = tree.toWorkflow();
+
+    const treeRegistry = new Registry();
+    const result = await workflow({ input: {}, treeRegistry });
+
+    expect(result.status).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should handle delay decorator", async () => {
+    const delay = new Delay({
+      id: "delay",
+      delayMs: 50,
+    });
+    const action = new PrintAction({
+      id: "action",
+      message: "Delayed action",
+    });
+    delay.setChild(action);
+
+    const tree = new BehaviorTree(delay);
+    const workflow = tree.toWorkflow();
+
+    const treeRegistry = new Registry();
+    const startTime = Date.now();
+    const result = await workflow({ input: {}, treeRegistry });
+    const duration = Date.now() - startTime;
+
+    expect(result.status).toBe(NodeStatus.SUCCESS);
+    expect(duration).toBeGreaterThanOrEqual(50);
+  });
+
+  it("should handle complex nested trees", async () => {
+    // Create a complex tree: Sequence -> (Selector, Parallel, Action)
+    const root = new Sequence({ id: "root" });
+
+    const selector = new Selector({ id: "selector" });
+    selector.addChild(new MockAction({ id: "fail", returnStatus: NodeStatus.FAILURE }));
+    selector.addChild(new MockAction({ id: "success", returnStatus: NodeStatus.SUCCESS }));
+
+    const parallel = new Parallel({
+      id: "parallel",
+      strategy: ParallelStrategy.JOIN_ALL,
+      threshold: 2,
+    });
+    parallel.addChild(new PrintAction({ id: "p1", message: "Parallel 1" }));
+    parallel.addChild(new PrintAction({ id: "p2", message: "Parallel 2" }));
+
+    const action = new MockAction({ id: "finalAction", returnStatus: NodeStatus.SUCCESS });
+
+    root.addChildren([selector, parallel, action]);
+
+    const tree = new BehaviorTree(root);
+    const workflow = tree.toWorkflow();
+
+    const treeRegistry = new Registry();
+    const result = await workflow({ input: {}, treeRegistry });
+
+    expect(result.status).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should preserve workflow info in context", async () => {
+    let capturedWorkflowInfo: any = null;
+
+    const action = new MockAction({
+      id: "capture",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    // Override tick to capture workflow info
+    const originalTick = action.tick.bind(action);
+    action.tick = async (context) => {
+      capturedWorkflowInfo = context.workflowInfo;
+      return originalTick(context);
+    };
+
+    const tree = new BehaviorTree(action);
+    const workflow = tree.toWorkflow();
+
+    const treeRegistry = new Registry();
+    const result = await workflow({ input: {}, treeRegistry });
+
+    expect(result.status).toBe(NodeStatus.SUCCESS);
+    // In test environment, workflowInfo might not be available
+    // This test just validates the structure doesn't break
+  });
+
+  it("should handle session ID properly", async () => {
+    const root = new PrintAction({ id: "root", message: "Session test" });
+
+    const tree = new BehaviorTree(root);
+    const workflow = tree.toWorkflow();
+
+    const treeRegistry = new Registry();
+    const customSessionId = "test-session-123";
+    const result = await workflow({
+      input: {},
+      treeRegistry,
+      sessionId: customSessionId,
+    });
+
+    expect(result.status).toBe(NodeStatus.SUCCESS);
+  });
+});