@q1k-oss/btree-workflows 0.0.1

package/src/utils/signal-check.test.ts

@@ -0,0 +1,234 @@
+/**
+ * Tests for signal checking utilities
+ * These utilities provide cancellation support across behavior tree nodes
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  checkSignal,
+  createAbortPromise,
+  OperationCancelledError,
+} from "./signal-check.js";
+
+describe("signal-check utilities", () => {
+  describe("checkSignal", () => {
+    it("should fail with OperationCancelledError when signal is aborted", () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      try {
+        checkSignal(controller.signal);
+        expect.fail("Should have thrown an error");
+      } catch (error) {
+        expect(error).toBeInstanceOf(OperationCancelledError);
+        expect((error as OperationCancelledError).message).toBe("Operation was cancelled");
+      }
+    });
+
+    it("should succeed when signal is undefined", () => {
+      expect(() => checkSignal(undefined)).not.toThrow();
+    });
+
+    it("should succeed when signal is provided but not aborted", () => {
+      const controller = new AbortController();
+      expect(() => checkSignal(controller.signal)).not.toThrow();
+    });
+
+    it("should include custom message in error when provided", () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      try {
+        checkSignal(controller.signal, "Custom operation");
+        expect.fail("Should have thrown an error");
+      } catch (error) {
+        expect((error as OperationCancelledError).message).toBe("Custom operation");
+      }
+    });
+  });
+
+  describe("createAbortPromise", () => {
+    it("should reject with OperationCancelledError when signal is aborted", async () => {
+      const controller = new AbortController();
+      const promise = createAbortPromise(controller.signal);
+
+      // Abort after a short delay
+      setTimeout(() => controller.abort(), 10);
+
+      await expect(promise).rejects.toThrow(OperationCancelledError);
+      await expect(promise).rejects.toThrow("Operation was cancelled");
+    });
+
+    it("should reject immediately if signal is already aborted", async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const promise = createAbortPromise(controller.signal);
+
+      await expect(promise).rejects.toThrow(OperationCancelledError);
+    });
+
+    it("should never resolve if signal is never aborted (race with timeout)", async () => {
+      const controller = new AbortController();
+      const abortPromise = createAbortPromise(controller.signal);
+
+      // Race with a timeout - abort promise should not resolve
+      const timeoutPromise = new Promise((resolve) =>
+        setTimeout(() => resolve("timeout"), 50),
+      );
+
+      const result = await Promise.race([abortPromise, timeoutPromise]);
+      expect(result).toBe("timeout");
+    });
+
+    it("should not reject when signal is undefined (race with timeout)", async () => {
+      const abortPromise = createAbortPromise(undefined);
+      const timeoutPromise = new Promise((resolve) =>
+        setTimeout(() => resolve("timeout"), 50),
+      );
+
+      const result = await Promise.race([abortPromise, timeoutPromise]);
+      expect(result).toBe("timeout");
+    });
+
+    it("should include custom message in error when provided", async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const promise = createAbortPromise(controller.signal, "Async operation");
+
+      await expect(promise).rejects.toThrow("Async operation");
+    });
+
+    it("should clean up event listener when signal is aborted", async () => {
+      const controller = new AbortController();
+      const promise = createAbortPromise(controller.signal);
+
+      // Abort the signal
+      controller.abort();
+
+      // Wait for rejection
+      await expect(promise).rejects.toThrow(OperationCancelledError);
+
+      // Verify event listener was removed (no way to directly test, but we can check it doesn't throw)
+      expect(() => controller.abort()).not.toThrow();
+    });
+  });
+
+  describe("OperationCancelledError", () => {
+    it("should be an instance of Error", () => {
+      const error = new OperationCancelledError();
+      expect(error).toBeInstanceOf(Error);
+    });
+
+    it("should have correct name", () => {
+      const error = new OperationCancelledError();
+      expect(error.name).toBe("OperationCancelledError");
+    });
+
+    it("should support custom message", () => {
+      const error = new OperationCancelledError("Custom message");
+      expect(error.message).toBe("Custom message");
+    });
+
+    it("should have default message", () => {
+      const error = new OperationCancelledError();
+      expect(error.message).toBe("Operation was cancelled");
+    });
+  });
+
+  describe("integration scenarios", () => {
+    it("should support using checkSignal in loops", async () => {
+      const controller = new AbortController();
+      let iterations = 0;
+
+      const performWork = async () => {
+        for (let i = 0; i < 1000; i++) {
+          await checkSignal(controller.signal);
+          iterations++;
+
+          if (i === 5) {
+            controller.abort();
+          }
+        }
+      };
+
+      try {
+        await performWork();
+        expect.fail("Should have thrown an error");
+      } catch (error) {
+        expect(error).toBeInstanceOf(OperationCancelledError);
+        expect(iterations).toBe(6); // 0, 1, 2, 3, 4, 5, then abort
+      }
+    });
+
+    it("should support racing abort promise with actual work", async () => {
+      const controller = new AbortController();
+
+      const work = new Promise<string>((resolve) => {
+        setTimeout(() => resolve("work completed"), 100);
+      });
+
+      const abort = createAbortPromise(controller.signal);
+
+      // Abort after 20ms
+      setTimeout(() => controller.abort(), 20);
+
+      // Abort should win the race
+      await expect(Promise.race([work, abort])).rejects.toThrow(
+        OperationCancelledError,
+      );
+    });
+
+    it("should support checking signal before async operations", async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const performAsyncWork = async () => {
+        // Check signal before starting work
+        await checkSignal(controller.signal);
+
+        // This should never execute
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        return "completed";
+      };
+
+      try {
+        await performAsyncWork();
+        expect.fail("Should have thrown an error");
+      } catch (error) {
+        expect(error).toBeInstanceOf(OperationCancelledError);
+      }
+    });
+
+    it("should support checking signal multiple times during execution", async () => {
+      const controller = new AbortController();
+      let checkpointReached = 0;
+
+      const performWork = async () => {
+        await checkSignal(controller.signal);
+        checkpointReached = 1;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+
+        await checkSignal(controller.signal);
+        checkpointReached = 2;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+
+        await checkSignal(controller.signal);
+        checkpointReached = 3;
+      };
+
+      // Start work and abort after checkpoint 1 but before checkpoint 2
+      const workPromise = performWork();
+      setTimeout(() => controller.abort(), 5);
+
+      try {
+        await workPromise;
+        expect.fail("Should have thrown an error");
+      } catch (error) {
+        expect(error).toBeInstanceOf(OperationCancelledError);
+        expect(checkpointReached).toBe(1);
+      }
+    });
+  });
+});

package/src/utils/signal-check.ts

@@ -0,0 +1,140 @@
+/**
+ * Signal checking utilities for cancellation support
+ *
+ * These utilities provide a consistent way to check for cancellation signals
+ * across all behavior tree nodes. They work with AbortController/AbortSignal
+ * to enable interruption of long-running operations.
+ *
+ * Usage:
+ * 1. checkSignal() - Use in loops and before operations to check if cancelled
+ * 2. createAbortPromise() - Use with Promise.race() to cancel async operations
+ *
+ * @module signal-check
+ */
+
+/**
+ * Error thrown when an operation is cancelled via AbortSignal
+ */
+export class OperationCancelledError extends Error {
+  constructor(message: string = "Operation was cancelled") {
+    super(message);
+    this.name = "OperationCancelledError";
+
+    // Maintains proper stack trace in V8 environments (Chrome, Node.js)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, OperationCancelledError);
+    }
+  }
+}
+
+/**
+ * Synchronously check if an abort signal has been triggered
+ *
+ * This is the primary mechanism for cooperative cancellation in behavior tree nodes.
+ * Call this function:
+ * - At the start of node execution
+ * - Before ticking each child in a composite
+ * - Inside loops during long-running operations
+ * - Before starting expensive operations
+ *
+ * @param signal - Optional AbortSignal from TickContext
+ * @param message - Optional custom error message (defaults to "Operation was cancelled")
+ * @throws OperationCancelledError if signal is aborted
+ *
+ * @example
+ * ```typescript
+ * // In a composite node
+ * async executeTick(context: TemporalContext): Promise<NodeStatus> {
+ *   checkSignal(context.signal); // Throws if cancelled
+ *   for (const child of this._children) {
+ *     const status = await child.tick(context);
+ *     // ...
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In a decorator with loops
+ * async executeTick(context: TemporalContext): Promise<NodeStatus> {
+ *   for (let i = 0; i < maxAttempts; i++) {
+ *     checkSignal(context.signal, 'Retry operation');
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function checkSignal(signal?: AbortSignal, message?: string): void {
+  if (signal?.aborted) {
+    throw new OperationCancelledError(message);
+  }
+}
+
+/**
+ * Create a promise that rejects when an abort signal is triggered
+ *
+ * This enables true async cancellation by racing with actual work.
+ * Use with Promise.race() to cancel Promises that don't natively support signals.
+ *
+ * The promise:
+ * - Rejects immediately if signal is already aborted
+ * - Rejects when signal fires 'abort' event
+ * - Never resolves (only rejects or remains pending)
+ * - Cleans up event listener when aborted
+ *
+ * @param signal - Optional AbortSignal from TickContext
+ * @param message - Optional custom error message (defaults to "Operation was cancelled")
+ * @returns Promise that rejects with OperationCancelledError when signal aborts
+ *
+ * @example
+ * ```typescript
+ * // Racing with a Promise that doesn't support signals
+ * protected async executeWithPlaywright(adapter: PlaywrightAdapter, context: TickContext) {
+ *   const work = someAsyncOperation();
+ *   const abort = createAbortPromise(context.signal);
+ *
+ *   const result = await Promise.race([work, abort]);
+ *   return result;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In a node that performs multiple async steps
+ * protected async executeWithPlaywright(adapter: PlaywrightAdapter, context: TickContext) {
+ *   const abort = createAbortPromise(context.signal);
+ *
+ *   const step1 = adapter.page.waitForSelector('.loading', { state: 'hidden' });
+ *   await Promise.race([step1, abort]);
+ *
+ *   const step2 = adapter.page.click('.button');
+ *   await Promise.race([step2, abort]);
+ *
+ *   return NodeStatus.SUCCESS;
+ * }
+ * ```
+ */
+export function createAbortPromise(
+  signal?: AbortSignal,
+  message?: string,
+): Promise<never> {
+  return new Promise((_, reject) => {
+    // If no signal provided, never reject (infinite pending)
+    if (!signal) {
+      return;
+    }
+
+    // If already aborted, reject immediately
+    if (signal.aborted) {
+      reject(new OperationCancelledError(message));
+      return;
+    }
+
+    // Listen for abort event
+    const onAbort = () => {
+      reject(new OperationCancelledError(message));
+    };
+
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/yaml/errors.ts

@@ -0,0 +1,143 @@
+/**
+ * YAML parser and validation error types
+ */
+
+/**
+ * Base class for all YAML validation errors
+ */
+export class ValidationError extends Error {
+  constructor(
+    message: string,
+    public path?: string,
+    public suggestion?: string,
+  ) {
+    super(message);
+    this.name = "ValidationError";
+  }
+
+  /**
+   * Format error message with path and suggestion
+   */
+  format(): string {
+    let formatted = this.message;
+
+    if (this.path) {
+      formatted = `${this.path}: ${formatted}`;
+    }
+
+    if (this.suggestion) {
+      formatted += `\nSuggestion: ${this.suggestion}`;
+    }
+
+    return formatted;
+  }
+}
+
+/**
+ * YAML syntax error (Stage 1)
+ * Thrown when YAML is malformed
+ */
+export class YamlSyntaxError extends ValidationError {
+  constructor(
+    message: string,
+    public line?: number,
+    public column?: number,
+    suggestion?: string,
+  ) {
+    super(message, undefined, suggestion);
+    this.name = "YamlSyntaxError";
+  }
+
+  format(): string {
+    let formatted = this.message;
+
+    if (this.line !== undefined) {
+      formatted = `Line ${this.line}${this.column !== undefined ? `, Column ${this.column}` : ""}: ${formatted}`;
+    }
+
+    if (this.suggestion) {
+      formatted += `\nSuggestion: ${this.suggestion}`;
+    }
+
+    return formatted;
+  }
+}
+
+/**
+ * Tree structure validation error (Stage 2)
+ * Thrown when tree definition structure is invalid
+ */
+export class StructureValidationError extends ValidationError {
+  constructor(message: string, path?: string, suggestion?: string) {
+    super(message, path, suggestion);
+    this.name = "StructureValidationError";
+  }
+}
+
+/**
+ * Node configuration validation error (Stage 3)
+ * Thrown when node-specific configuration is invalid
+ */
+export class ConfigValidationError extends ValidationError {
+  constructor(
+    message: string,
+    public nodeType: string,
+    path?: string,
+    suggestion?: string,
+  ) {
+    super(message, path, suggestion);
+    this.name = "ConfigValidationError";
+  }
+
+  format(): string {
+    let formatted = `Invalid configuration for node type '${this.nodeType}'`;
+
+    if (this.path) {
+      formatted += ` at ${this.path}`;
+    }
+
+    formatted += `:\n${this.message}`;
+
+    if (this.suggestion) {
+      formatted += `\nSuggestion: ${this.suggestion}`;
+    }
+
+    return formatted;
+  }
+}
+
+/**
+ * Semantic validation error (Stage 4)
+ * Thrown when semantic rules are violated (duplicate IDs, circular refs, etc.)
+ */
+export class SemanticValidationError extends ValidationError {
+  constructor(message: string, path?: string, suggestion?: string) {
+    super(message, path, suggestion);
+    this.name = "SemanticValidationError";
+  }
+}
+
+/**
+ * Collect multiple validation errors
+ */
+export class ValidationErrors extends Error {
+  constructor(public errors: ValidationError[]) {
+    super(`Validation failed with ${errors.length} error(s)`);
+    this.name = "ValidationErrors";
+  }
+
+  /**
+   * Format all errors as a single message
+   */
+  format(): string {
+    const header = `YAML validation failed\n\nIssues found:`;
+    const issues = this.errors
+      .map((error, index) => {
+        const formatted = error.format();
+        return `  ${index + 1}. ${formatted.split("\n").join("\n     ")}`;
+      })
+      .join("\n\n");
+
+    return `${header}\n${issues}`;
+  }
+}

package/src/yaml/index.ts

@@ -0,0 +1,30 @@
+/**
+ * YAML parser and loader for behavior trees
+ * Provides 4-stage validation pipeline for loading workflows from YAML
+ */
+
+// Core functions
+export {
+  parseYaml,
+  loadTreeFromYaml,
+  validateYaml,
+  toYaml,
+  type LoadOptions,
+  type ValidationOptions,
+  type ValidationResult,
+} from "./parser.js";
+
+export { loadTreeFromFile } from "./loader.js";
+
+// Error types
+export {
+  ValidationError,
+  YamlSyntaxError,
+  StructureValidationError,
+  ConfigValidationError,
+  SemanticValidationError,
+  ValidationErrors,
+} from "./errors.js";
+
+// Validators
+export { semanticValidator } from "./validation/semantic-validator.js";

package/src/yaml/loader.ts

@@ -0,0 +1,39 @@
+/**
+ * File system integration for YAML loading
+ */
+
+import { readFile } from "fs/promises";
+import type { Registry } from "../registry.js";
+import type { TreeNode } from "../types.js";
+import { loadTreeFromYaml, type LoadOptions } from "./parser.js";
+
+/**
+ * Load and create tree from YAML file
+ *
+ * @param filePath - Path to YAML file
+ * @param registry - Registry with registered node types
+ * @param options - Loading options
+ * @returns Created tree node
+ * @throws ValidationError if validation fails
+ * @throws Error if file cannot be read
+ *
+ * @example
+ * ```typescript
+ * const tree = await loadTreeFromFile('./workflows/checkout.yaml', registry);
+ * ```
+ */
+export async function loadTreeFromFile(
+  filePath: string,
+  registry: Registry,
+  options: LoadOptions = {},
+): Promise<TreeNode> {
+  try {
+    const yamlContent = await readFile(filePath, "utf-8");
+    return loadTreeFromYaml(yamlContent, registry, options);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    throw error;
+  }
+}