@q1k-oss/btree-workflows 0.0.1

package/src/schemas/integration.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Integration tests for schema validation with Registry
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { Registry } from "../registry.js";
+import { Timeout } from "../decorators/timeout.js";
+import { Delay } from "../decorators/delay.js";
+import { Parallel } from "../composites/parallel.js";
+import { Sequence } from "../composites/sequence.js";
+import { ConfigurationError } from "../errors.js";
+
+describe("Schema Validation Integration", () => {
+  let registry: Registry;
+
+  beforeEach(() => {
+    registry = new Registry();
+    registry.register("Timeout", Timeout, { category: "decorator" });
+    registry.register("Delay", Delay, { category: "decorator" });
+    registry.register("Parallel", Parallel, { category: "composite" });
+    registry.register("Sequence", Sequence, { category: "composite" });
+  });
+
+  describe("Timeout validation", () => {
+    it("should accept valid timeoutMs", () => {
+      const node = registry.create("Timeout", {
+        id: "test",
+        timeoutMs: 1000,
+      });
+
+      expect(node).toBeInstanceOf(Timeout);
+    });
+
+    it("should reject negative timeoutMs", () => {
+      expect(() => {
+        registry.create("Timeout", {
+          id: "test",
+          timeoutMs: -100,
+        });
+      }).toThrow(ConfigurationError);
+    });
+
+    it("should reject zero timeoutMs", () => {
+      expect(() => {
+        registry.create("Timeout", {
+          id: "test",
+          timeoutMs: 0,
+        });
+      }).toThrow(ConfigurationError);
+    });
+
+    it("should provide helpful error message", () => {
+      try {
+        registry.create("Timeout", {
+          id: "test-timeout",
+          timeoutMs: -100,
+        });
+        expect.fail("Should have thrown");
+      } catch (error) {
+        expect(error).toBeInstanceOf(ConfigurationError);
+        const message = (error as ConfigurationError).message;
+        expect(message).toContain("Timeout:test-timeout");
+        expect(message).toContain("timeoutMs");
+        expect(message).toContain("positive");
+      }
+    });
+  });
+
+  describe("Delay validation", () => {
+    it("should accept positive delayMs", () => {
+      const node = registry.create("Delay", {
+        id: "test",
+        delayMs: 500,
+      });
+
+      expect(node).toBeInstanceOf(Delay);
+    });
+
+    it("should accept zero delayMs", () => {
+      const node = registry.create("Delay", {
+        id: "test",
+        delayMs: 0,
+      });
+
+      expect(node).toBeInstanceOf(Delay);
+    });
+
+    it("should reject negative delayMs", () => {
+      expect(() => {
+        registry.create("Delay", {
+          id: "test",
+          delayMs: -100,
+        });
+      }).toThrow(ConfigurationError);
+    });
+  });
+
+  describe("Parallel validation", () => {
+    it("should accept valid strategy", () => {
+      const node = registry.create("Parallel", {
+        id: "test",
+        strategy: "strict",
+      });
+
+      expect(node).toBeInstanceOf(Parallel);
+    });
+
+    it("should accept 'any' strategy", () => {
+      const node = registry.create("Parallel", {
+        id: "test",
+        strategy: "any",
+      });
+
+      expect(node).toBeInstanceOf(Parallel);
+    });
+
+    it("should use default strategy if not provided", () => {
+      const node = registry.create("Parallel", {
+        id: "test",
+      });
+
+      expect(node).toBeInstanceOf(Parallel);
+    });
+
+    it("should reject invalid strategy", () => {
+      expect(() => {
+        registry.create("Parallel", {
+          id: "test",
+          strategy: "invalid" as never,
+        });
+      }).toThrow(ConfigurationError);
+    });
+
+    it("should accept positive thresholds", () => {
+      const node = registry.create("Parallel", {
+        id: "test",
+        successThreshold: 2,
+        failureThreshold: 1,
+      });
+
+      expect(node).toBeInstanceOf(Parallel);
+    });
+  });
+
+  describe("Tree creation validation", () => {
+    it("should validate entire tree structure", () => {
+      const definition = {
+        type: "Sequence",
+        id: "root",
+        children: [
+          {
+            type: "Timeout",
+            id: "timeout1",
+            props: {
+              timeoutMs: 1000,
+            },
+            children: [
+              {
+                type: "Delay",
+                id: "delay1",
+                props: {
+                  delayMs: 500,
+                },
+              },
+            ],
+          },
+        ],
+      };
+
+      const tree = registry.createTree(definition);
+      expect(tree).toBeInstanceOf(Sequence);
+    });
+
+    it("should catch validation errors in nested nodes", () => {
+      const definition = {
+        type: "Sequence",
+        id: "root",
+        children: [
+          {
+            type: "Timeout",
+            id: "timeout1",
+            props: {
+              timeoutMs: -100, // Invalid!
+            },
+          },
+        ],
+      };
+
+      expect(() => {
+        registry.createTree(definition);
+      }).toThrow(ConfigurationError);
+    });
+
+    it("should validate tree structure schema", () => {
+      const definition = {
+        id: "missing-type",
+      };
+
+      expect(() => {
+        registry.createTree(definition);
+      }).toThrow(/type/);
+    });
+  });
+
+  describe("safeCreateTree", () => {
+    it("should return success for valid tree", () => {
+      const definition = {
+        type: "Sequence",
+        id: "root",
+      };
+
+      const result = registry.safeCreateTree(definition);
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.tree).toBeInstanceOf(Sequence);
+      }
+    });
+
+    it("should return error for invalid tree", () => {
+      const definition = {
+        type: "Timeout",
+        id: "invalid",
+        props: {
+          timeoutMs: -100,
+        },
+      };
+
+      const result = registry.safeCreateTree(definition);
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toBeInstanceOf(Error);
+        expect(result.error.message).toContain("timeoutMs");
+      }
+    });
+  });
+});

package/src/schemas/tree-definition.schema.ts

@@ -0,0 +1,170 @@
+/**
+ * Tree definition schemas
+ * Validates the structure of tree definitions before node creation
+ */
+
+import { z } from "zod";
+
+/**
+ * Tree definition type
+ * Matches the format expected by Registry.createTree()
+ */
+export interface TreeDefinition {
+  type: string;
+  id?: string;
+  name?: string;
+  props?: Record<string, unknown>;
+  children?: TreeDefinition[];
+}
+
+/**
+ * Recursive schema for tree definitions
+ * Supports nested children and arbitrary props
+ *
+ * Validates:
+ * - type is a non-empty string
+ * - id is optional string
+ * - name is optional string
+ * - props is optional record of unknown values
+ * - children is optional array of tree definitions
+ */
+const treeDefSchemaObject = z.object({
+  type: z.string().min(1, "Node type is required"),
+  id: z.string().optional(),
+  name: z.string().optional(),
+  props: z.record(z.string(), z.unknown()).optional(),
+  children: z
+    .array(
+      z.lazy(() => treeDefinitionSchema) as z.ZodType<TreeDefinition>,
+    )
+    .optional(),
+});
+
+export const treeDefinitionSchema: z.ZodType<TreeDefinition> =
+  treeDefSchemaObject;
+
+/**
+ * Validate tree definition structure (without type-specific validation)
+ * Type-specific validation happens in Registry.create()
+ *
+ * @param definition - Tree definition to validate
+ * @returns Validated tree definition
+ * @throws ZodError if structure is invalid
+ *
+ * @example
+ * ```typescript
+ * const definition = validateTreeDefinition({
+ *   type: 'Sequence',
+ *   id: 'root',
+ *   children: [
+ *     { type: 'PrintAction', id: 'action1' }
+ *   ]
+ * });
+ * ```
+ */
+export function validateTreeDefinition(definition: unknown): TreeDefinition {
+  return treeDefinitionSchema.parse(definition) as TreeDefinition;
+}
+
+/**
+ * Validate decorator has exactly one child
+ *
+ * @param nodeType - Type of the decorator node
+ * @param children - Children array to validate
+ * @throws Error if child count is not exactly 1
+ */
+export function validateDecoratorChildren(
+  nodeType: string,
+  children?: TreeDefinition[],
+): void {
+  const childCount = children?.length || 0;
+  if (childCount !== 1) {
+    throw new Error(
+      `Decorator ${nodeType} must have exactly one child (got ${childCount})`,
+    );
+  }
+}
+
+/**
+ * Validate composite has at least minimum children
+ *
+ * @param nodeType - Type of the composite node
+ * @param children - Children array to validate
+ * @param minChildren - Minimum required children (default: 0)
+ * @throws Error if child count is less than minimum
+ */
+export function validateCompositeChildren(
+  nodeType: string,
+  children?: TreeDefinition[],
+  minChildren: number = 0,
+): void {
+  const count = children?.length || 0;
+  if (count < minChildren) {
+    throw new Error(
+      `Composite ${nodeType} requires at least ${minChildren} children (got ${count})`,
+    );
+  }
+}
+
+/**
+ * Validate specific child count for composites with fixed requirements
+ *
+ * @param nodeType - Type of the composite node
+ * @param children - Children array to validate
+ * @param expectedCount - Exact number of expected children
+ * @throws Error if child count doesn't match expected
+ *
+ * @example
+ * ```typescript
+ * // While node requires exactly 2 children (condition, body)
+ * validateChildCount('While', children, 2);
+ * ```
+ */
+export function validateChildCount(
+  nodeType: string,
+  children?: TreeDefinition[],
+  expectedCount: number = 0,
+): void {
+  const count = children?.length || 0;
+  if (count !== expectedCount) {
+    throw new Error(
+      `${nodeType} requires exactly ${expectedCount} children (got ${count})`,
+    );
+  }
+}
+
+/**
+ * Validate child count range for composites with flexible requirements
+ *
+ * @param nodeType - Type of the composite node
+ * @param children - Children array to validate
+ * @param minChildren - Minimum required children
+ * @param maxChildren - Maximum allowed children
+ * @throws Error if child count is outside range
+ *
+ * @example
+ * ```typescript
+ * // Conditional node requires 2-3 children (condition, then, optional else)
+ * validateChildCountRange('Conditional', children, 2, 3);
+ * ```
+ */
+export function validateChildCountRange(
+  nodeType: string,
+  children?: TreeDefinition[],
+  minChildren: number = 0,
+  maxChildren?: number,
+): void {
+  const count = children?.length || 0;
+
+  if (count < minChildren) {
+    throw new Error(
+      `${nodeType} requires at least ${minChildren} children (got ${count})`,
+    );
+  }
+
+  if (maxChildren !== undefined && count > maxChildren) {
+    throw new Error(
+      `${nodeType} allows at most ${maxChildren} children (got ${count})`,
+    );
+  }
+}

package/src/schemas/validation.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Tests for schema validation utilities
+ */
+
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import {
+  zodErrorToConfigurationError,
+  validateConfiguration,
+  safeValidateConfiguration,
+} from "./validation.js";
+import { ConfigurationError } from "../errors.js";
+
+describe("Schema Validation Utilities", () => {
+  describe("zodErrorToConfigurationError", () => {
+    it("should convert Zod error to ConfigurationError", () => {
+      const schema = z.object({
+        id: z.string(),
+        value: z.number().positive(),
+      });
+
+      try {
+        schema.parse({ id: "test", value: -5 });
+        expect.fail("Should have thrown");
+      } catch (error) {
+        if (error instanceof z.ZodError) {
+          const configError = zodErrorToConfigurationError(
+            error,
+            "TestNode",
+            "test-id",
+          );
+
+          expect(configError).toBeInstanceOf(ConfigurationError);
+          expect(configError.message).toContain("TestNode:test-id");
+          expect(configError.message).toContain("value");
+        }
+      }
+    });
+
+    it("should include field path in error message", () => {
+      const schema = z.object({
+        nested: z.object({
+          value: z.number(),
+        }),
+      });
+
+      try {
+        schema.parse({ nested: { value: "not a number" } });
+        expect.fail("Should have thrown");
+      } catch (error) {
+        if (error instanceof z.ZodError) {
+          const configError = zodErrorToConfigurationError(error, "TestNode");
+
+          expect(configError.message).toContain("nested.value");
+        }
+      }
+    });
+  });
+
+  describe("validateConfiguration", () => {
+    const testSchema = z.object({
+      id: z.string(),
+      count: z.number().int().positive(),
+    });
+
+    it("should validate and return valid configuration", () => {
+      const config = { id: "test", count: 5 };
+      const result = validateConfiguration(
+        testSchema,
+        config,
+        "TestNode",
+        "test-id",
+      );
+
+      expect(result).toEqual(config);
+    });
+
+    it("should throw ConfigurationError for invalid configuration", () => {
+      const config = { id: "test", count: -5 };
+
+      expect(() => {
+        validateConfiguration(testSchema, config, "TestNode", "test-id");
+      }).toThrow(ConfigurationError);
+    });
+
+    it("should include node type and ID in error message", () => {
+      const config = { id: "test", count: 0 };
+
+      try {
+        validateConfiguration(testSchema, config, "TestNode", "test-id");
+        expect.fail("Should have thrown");
+      } catch (error) {
+        expect(error).toBeInstanceOf(ConfigurationError);
+        expect((error as ConfigurationError).message).toContain(
+          "TestNode:test-id",
+        );
+      }
+    });
+  });
+
+  describe("safeValidateConfiguration", () => {
+    const testSchema = z.object({
+      id: z.string(),
+      value: z.number(),
+    });
+
+    it("should return success result for valid configuration", () => {
+      const config = { id: "test", value: 42 };
+      const result = safeValidateConfiguration(
+        testSchema,
+        config,
+        "TestNode",
+        "test-id",
+      );
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data).toEqual(config);
+      }
+    });
+
+    it("should return error result for invalid configuration", () => {
+      const config = { id: "test", value: "not a number" };
+      const result = safeValidateConfiguration(
+        testSchema,
+        config,
+        "TestNode",
+        "test-id",
+      );
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toBeInstanceOf(ConfigurationError);
+        expect(result.error.message).toContain("value");
+      }
+    });
+
+    it("should not throw errors", () => {
+      const config = { id: 123, value: "invalid" }; // Multiple errors
+
+      expect(() => {
+        safeValidateConfiguration(testSchema, config, "TestNode");
+      }).not.toThrow();
+    });
+  });
+});

package/src/schemas/validation.ts

@@ -0,0 +1,122 @@
+/**
+ * Validation utilities and error conversion
+ * Converts Zod validation errors to ConfigurationError
+ */
+
+import { z } from "zod";
+import { ConfigurationError } from "../errors.js";
+
+/**
+ * Convert Zod validation errors to ConfigurationError
+ * Preserves detailed error context and provides helpful hints
+ *
+ * @param error - Zod validation error
+ * @param nodeType - Type of node being validated
+ * @param nodeId - Optional node ID for context
+ * @returns ConfigurationError with formatted message
+ */
+export function zodErrorToConfigurationError(
+  error: z.ZodError<unknown>,
+  nodeType: string,
+  nodeId?: string,
+): ConfigurationError {
+  const nodeIdentifier = nodeId ? `${nodeType}:${nodeId}` : nodeType;
+
+  // Format Zod errors into readable message
+  const issues = error.issues
+    .map((issue: z.ZodIssue) => {
+      const path = issue.path.join(".");
+      return `  - ${path ? path + ": " : ""}${issue.message}`;
+    })
+    .join("\n");
+
+  const message = `Invalid configuration for ${nodeIdentifier}:\n${issues}`;
+
+  // Include hint for common fixes
+  const hint =
+    "Check the node configuration and ensure all required fields are provided with valid values.";
+
+  return new ConfigurationError(message, hint);
+}
+
+/**
+ * Validate and parse configuration with ConfigurationError conversion
+ * Throws ConfigurationError if validation fails
+ *
+ * @param schema - Zod schema to validate against
+ * @param config - Configuration object to validate
+ * @param nodeType - Type of node being validated
+ * @param nodeId - Optional node ID for error context
+ * @returns Validated and parsed configuration
+ * @throws ConfigurationError if validation fails
+ *
+ * @example
+ * ```typescript
+ * const validatedConfig = validateConfiguration(
+ *   timeoutSchema,
+ *   { id: 'test', timeoutMs: 1000 },
+ *   'Timeout',
+ *   'test'
+ * );
+ * ```
+ */
+export function validateConfiguration<T = unknown>(
+  schema: z.ZodSchema<T>,
+  config: unknown,
+  nodeType: string,
+  nodeId?: string,
+): T {
+  try {
+    return schema.parse(config);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw zodErrorToConfigurationError(error, nodeType, nodeId);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Safe validation that returns result instead of throwing
+ * Useful for user-facing tools that need graceful error handling
+ *
+ * @param schema - Zod schema to validate against
+ * @param config - Configuration object to validate
+ * @param nodeType - Type of node being validated (for error messages)
+ * @param nodeId - Optional node ID for error context
+ * @returns Success result with data or failure result with error
+ *
+ * @example
+ * ```typescript
+ * const result = safeValidateConfiguration(
+ *   timeoutSchema,
+ *   { id: 'test', timeoutMs: -100 },
+ *   'Timeout'
+ * );
+ *
+ * if (result.success) {
+ *   console.log(result.data);
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export function safeValidateConfiguration<T>(
+  schema: z.ZodSchema<T>,
+  config: unknown,
+  nodeType: string,
+  nodeId?: string,
+):
+  | { success: true; data: T }
+  | { success: false; error: ConfigurationError } {
+  const result = schema.safeParse(config);
+
+  if (result.success) {
+    return { success: true, data: result.data };
+  } else {
+    return {
+      success: false,
+      error: zodErrorToConfigurationError(result.error, nodeType, nodeId),
+    };
+  }
+}

package/src/scripting/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Scripting module (deprecated)
+ *
+ * The Script node has been replaced by CodeExecution which uses
+ * Microsandbox for secure, isolated code execution.
+ *
+ * Use CodeExecution instead:
+ * @example
+ * ```yaml
+ * type: CodeExecution
+ * id: transform-data
+ * props:
+ *   language: javascript  # or 'python'
+ *   code: |
+ *     const users = getBB('users');
+ *     setBB('count', users.length);
+ * ```
+ *
+ * @see CodeExecution in src/actions/code-execution.ts
+ */
+
+// No exports - use CodeExecution instead