@q1k-oss/btree-workflows 0.0.1

package/src/registry.ts

@@ -0,0 +1,334 @@
+/**
+ * Registry for behavior tree nodes
+ * Handles registration and creation of nodes by type
+ */
+
+import type { BehaviorTree } from "./behavior-tree.js";
+import type {
+  NodeConfiguration,
+  NodeConstructor,
+  NodeMetadata,
+  TreeNode,
+} from "./types.js";
+import { z } from "zod";
+import {
+  schemaRegistry,
+  validateConfiguration,
+  treeDefinitionSchema,
+  type TreeDefinition,
+} from "./schemas/index.js";
+
+/**
+ * Entry for a registered BehaviorTree with metadata
+ */
+interface TreeEntry {
+  tree: BehaviorTree;
+  sourceFile: string;
+}
+
+export class Registry {
+  private nodeTypes: Map<string, NodeConstructor> = new Map();
+  private nodeMetadata: Map<string, NodeMetadata> = new Map();
+  private behaviorTrees: Map<string, TreeEntry> = new Map();
+
+  constructor() {
+    this.log("Registry created");
+  }
+
+  /**
+   * Register a node type with the registry
+   */
+  register<T extends TreeNode>(
+    type: string,
+    ctor: NodeConstructor<T>,
+    metadata?: Partial<NodeMetadata>,
+  ): void {
+    if (this.nodeTypes.has(type)) {
+      throw new Error(`Node type '${type}' is already registered`);
+    }
+
+    this.nodeTypes.set(type, ctor);
+
+    // Store metadata
+    const fullMetadata: NodeMetadata = {
+      type,
+      category: metadata?.category || "action",
+      description: metadata?.description,
+      ports: metadata?.ports || [],
+    };
+
+    this.nodeMetadata.set(type, fullMetadata);
+    this.log(`Registered node type: ${type} (${fullMetadata.category})`);
+  }
+
+  /**
+   * Create a node instance by type
+   * Validates configuration against schema before creating node
+   */
+  create(type: string, config: NodeConfiguration): TreeNode {
+    const Constructor = this.nodeTypes.get(type);
+
+    if (!Constructor) {
+      throw new Error(
+        `Unknown node type: '${type}'. Available types: ${this.getRegisteredTypes().join(", ")}`,
+      );
+    }
+
+    // Validate configuration using schema registry
+    const validatedConfig = validateConfiguration<NodeConfiguration>(
+      schemaRegistry.getSchema(type) as z.ZodSchema<NodeConfiguration>,
+      config,
+      type,
+      config.id,
+    );
+
+    this.log(`Creating node of type: ${type} with id: ${validatedConfig.id}`);
+    return new Constructor(validatedConfig);
+  }
+
+  /**
+   * Check if a node type is registered
+   */
+  has(type: string): boolean {
+    return this.nodeTypes.has(type);
+  }
+
+  /**
+   * Get metadata for a node type
+   */
+  getMetadata(type: string): NodeMetadata | undefined {
+    return this.nodeMetadata.get(type);
+  }
+
+  /**
+   * Get all registered node types
+   */
+  getRegisteredTypes(): string[] {
+    return Array.from(this.nodeTypes.keys());
+  }
+
+  /**
+   * Get registered types by category
+   */
+  getTypesByCategory(category: NodeMetadata["category"]): string[] {
+    const types: string[] = [];
+
+    for (const [type, metadata] of this.nodeMetadata) {
+      if (metadata.category === category) {
+        types.push(type);
+      }
+    }
+
+    return types;
+  }
+
+  /**
+   * Clear all registrations (node types, metadata, and behavior trees)
+   */
+  clear(): void {
+    this.nodeTypes.clear();
+    this.nodeMetadata.clear();
+    this.behaviorTrees.clear();
+    this.log("Registry cleared (nodes and trees)");
+  }
+
+  /**
+   * Register a behavior tree instance with source file metadata.
+   * Used for reusable trees like elements, step groups, and test cases.
+   *
+   * @param id Unique identifier for the tree
+   * @param tree BehaviorTree instance to register
+   * @param sourceFile Path to the source .sigma file
+   * @throws Error if a tree with the same ID is already registered
+   */
+  registerTree(id: string, tree: BehaviorTree, sourceFile: string): void {
+    if (this.behaviorTrees.has(id)) {
+      throw new Error(`Behavior tree '${id}' is already registered`);
+    }
+    this.behaviorTrees.set(id, { tree, sourceFile });
+    this.log(`Registered behavior tree: ${id}`);
+  }
+
+  /**
+   * Unregister a behavior tree by ID.
+   * Useful for cleanup in long-running processes or tests.
+   *
+   * @param id Tree ID to unregister
+   * @returns true if tree was found and removed, false otherwise
+   */
+  unregisterTree(id: string): boolean {
+    const deleted = this.behaviorTrees.delete(id);
+    if (deleted) {
+      this.log(`Unregistered behavior tree: ${id}`);
+    }
+    return deleted;
+  }
+
+  /**
+   * Replace an existing behavior tree registration.
+   * If the tree doesn't exist, it will be registered as new.
+   *
+   * @param id Tree ID to replace
+   * @param tree New BehaviorTree instance
+   * @param sourceFile Path to the source .sigma file
+   */
+  replaceTree(id: string, tree: BehaviorTree, sourceFile: string): void {
+    const existed = this.behaviorTrees.has(id);
+    this.behaviorTrees.set(id, { tree, sourceFile });
+    this.log(`${existed ? "Replaced" : "Registered"} behavior tree: ${id}`);
+  }
+
+  /**
+   * Get a behavior tree instance by ID
+   */
+  getTree(id: string): BehaviorTree | undefined {
+    return this.behaviorTrees.get(id)?.tree;
+  }
+
+  /**
+   * Get the source file path for a behavior tree
+   */
+  getTreeSourceFile(id: string): string | undefined {
+    return this.behaviorTrees.get(id)?.sourceFile;
+  }
+
+  /**
+   * Get all trees that belong to a specific source file
+   */
+  getTreesForFile(filePath: string): Map<string, BehaviorTree> {
+    const result = new Map<string, BehaviorTree>();
+    for (const [id, entry] of this.behaviorTrees) {
+      if (entry.sourceFile === filePath) {
+        result.set(id, entry.tree);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Check if a behavior tree is registered
+   */
+  hasTree(id: string): boolean {
+    return this.behaviorTrees.has(id);
+  }
+
+  /**
+   * Clone a registered behavior tree for instantiation
+   * Returns the cloned BehaviorTree (caller should use getRoot() for TreeNode)
+   */
+  cloneTree(id: string): BehaviorTree {
+    const entry = this.behaviorTrees.get(id);
+    if (!entry) {
+      throw new Error(
+        `Behavior tree '${id}' not found. Available trees: ${this.getAllTreeIds().join(", ") || "none"}`,
+      );
+    }
+    this.log(`Cloning behavior tree: ${id}`);
+    return entry.tree.clone();
+  }
+
+  /**
+   * Get all registered behavior tree IDs
+   */
+  getAllTreeIds(): string[] {
+    return Array.from(this.behaviorTrees.keys());
+  }
+
+  /**
+   * Clear all registered behavior trees
+   */
+  clearTrees(): void {
+    this.behaviorTrees.clear();
+    this.log("Cleared all behavior trees");
+  }
+
+  /**
+   * Create a tree from a JSON definition
+   * Validates tree structure before creating nodes
+   */
+  createTree(definition: unknown): TreeNode {
+    // Validate tree definition structure
+    const validatedDef = treeDefinitionSchema.parse(definition) as TreeDefinition;
+
+    if (!validatedDef.type) {
+      throw new Error("Node definition must have a type");
+    }
+
+    // Create the node configuration
+    const config: NodeConfiguration = {
+      id: validatedDef.id || `${validatedDef.type}_${Date.now()}`,
+      name: validatedDef.name || validatedDef.id,
+      ...validatedDef.props,
+    };
+
+    // Create node with validated configuration (uses schema validation)
+    const node = this.create(validatedDef.type, config);
+
+    // Handle children for composite/decorator nodes
+    if (validatedDef.children && Array.isArray(validatedDef.children)) {
+      if ("setChild" in node && typeof node.setChild === "function") {
+        // Decorator node - single child
+        if (validatedDef.children.length !== 1) {
+          throw new Error(
+            `Decorator ${validatedDef.type} must have exactly one child`,
+          );
+        }
+        const child = this.createTree(validatedDef.children[0]);
+        (node as { setChild: (child: TreeNode) => void }).setChild(child);
+      } else if (
+        "addChildren" in node &&
+        typeof node.addChildren === "function"
+      ) {
+        // Composite node - multiple children
+        const children = validatedDef.children.map((childDef) =>
+          this.createTree(childDef),
+        );
+        (node as { addChildren: (children: TreeNode[]) => void }).addChildren(
+          children,
+        );
+      }
+    }
+
+    return node;
+  }
+
+  /**
+   * Safe tree creation that returns success/error result
+   * Useful for user-facing tools that need graceful error handling
+   *
+   * @param definition - Tree definition to create
+   * @returns Success result with tree or failure result with error
+   *
+   * @example
+   * ```typescript
+   * const result = registry.safeCreateTree({
+   *   type: 'Sequence',
+   *   id: 'root',
+   *   children: [...]
+   * });
+   *
+   * if (result.success) {
+   *   console.log('Tree created:', result.tree);
+   * } else {
+   *   console.error('Failed:', result.error.message);
+   * }
+   * ```
+   */
+  safeCreateTree(
+    definition: unknown,
+  ): { success: true; tree: TreeNode } | { success: false; error: Error } {
+    try {
+      const tree = this.createTree(definition);
+      return { success: true, tree };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
+
+  private log(message: string): void {
+    console.log(`[Registry] ${message}`);
+  }
+}

package/src/schemas/base.schema.ts

@@ -0,0 +1,104 @@
+/**
+ * Base Zod schemas for node configurations
+ * Foundation for all node-specific validation schemas
+ */
+
+import { z } from "zod";
+
+/**
+ * Base schema for all node configurations
+ * Matches NodeConfiguration interface from types.ts
+ */
+export const nodeConfigurationSchema = z
+  .object({
+    id: z.string().min(1, "Node ID cannot be empty"),
+    name: z.string().optional(),
+  })
+  .passthrough(); // Allow additional properties for node-specific configs
+
+/**
+ * Branded type for validated configurations
+ * Ensures runtime type matches compile-time type
+ */
+export type ValidatedNodeConfiguration = z.infer<
+  typeof nodeConfigurationSchema
+>;
+
+/**
+ * Helper to create node-specific configuration schemas
+ * Extends base schema with node-specific fields
+ *
+ * @param nodeType - Name of the node type for error messages
+ * @param fields - Node-specific field definitions
+ * @returns Extended Zod schema
+ *
+ * @example
+ * ```typescript
+ * const timeoutSchema = createNodeSchema('Timeout', {
+ *   timeoutMs: validations.positiveNumber('timeoutMs'),
+ * });
+ * ```
+ */
+export function createNodeSchema<T extends z.ZodRawShape>(
+  nodeType: string,
+  fields: T,
+) {
+  return nodeConfigurationSchema
+    .extend(fields)
+    .describe(`${nodeType} configuration`);
+}
+
+/**
+ * Common validation helpers
+ * Reusable validators for standard patterns
+ */
+export const validations = {
+  /**
+   * Positive number validator (> 0)
+   */
+  positiveNumber: (fieldName: string) =>
+    z.number().positive(`${fieldName} must be positive`),
+
+  /**
+   * Non-negative number validator (>= 0)
+   */
+  nonNegativeNumber: (fieldName: string) =>
+    z.number().nonnegative(`${fieldName} must be non-negative`),
+
+  /**
+   * Positive integer validator (> 0, whole number)
+   */
+  positiveInteger: (fieldName: string) =>
+    z.number().int().positive(`${fieldName} must be a positive integer`),
+
+  /**
+   * Non-negative integer validator (>= 0, whole number)
+   */
+  nonNegativeInteger: (fieldName: string) =>
+    z
+      .number()
+      .int()
+      .nonnegative(`${fieldName} must be a non-negative integer`),
+
+  /**
+   * Blackboard key validator (non-empty string)
+   */
+  blackboardKey: z.string().min(1, "Blackboard key cannot be empty"),
+
+  /**
+   * Tree ID validator (non-empty string for SubTree references)
+   */
+  treeId: z.string().min(1, "Tree ID cannot be empty"),
+
+  /**
+   * Duration in milliseconds validator (non-negative)
+   */
+  durationMs: (fieldName: string = "duration") =>
+    z.number().nonnegative(`${fieldName} must be non-negative milliseconds`),
+};
+
+/**
+ * Infer TypeScript type from schema
+ * Helper for type-safe configuration interfaces
+ */
+export type InferSchema<T extends z.ZodSchema> = z.infer<T>;

package/src/schemas/index.ts

@@ -0,0 +1,223 @@
+/**
+ * Schema registry and validation exports
+ * Central registry mapping node types to their validation schemas
+ */
+
+import { z } from "zod";
+import { nodeConfigurationSchema } from "./base.schema.js";
+
+// Import decorator schemas
+import { timeoutConfigurationSchema } from "../decorators/timeout.schema.js";
+import { delayConfigurationSchema } from "../decorators/delay.schema.js";
+import { repeatConfigurationSchema } from "../decorators/repeat.schema.js";
+import { invertConfigurationSchema } from "../decorators/invert.schema.js";
+import {
+  forceSuccessConfigurationSchema,
+  forceFailureConfigurationSchema,
+} from "../decorators/force-result.schema.js";
+import { preconditionConfigurationSchema } from "../decorators/precondition.schema.js";
+import { runOnceConfigurationSchema } from "../decorators/run-once.schema.js";
+import { keepRunningUntilFailureConfigurationSchema } from "../decorators/keep-running.schema.js";
+import { softAssertConfigurationSchema } from "../decorators/soft-assert.schema.js";
+
+// Import composite schemas
+import { parallelConfigurationSchema } from "../composites/parallel.schema.js";
+import { forEachConfigurationSchema } from "../composites/for-each.schema.js";
+import { whileConfigurationSchema } from "../composites/while.schema.js";
+import { subTreeConfigurationSchema } from "../composites/sub-tree.schema.js";
+import { sequenceConfigurationSchema } from "../composites/sequence.schema.js";
+import { selectorConfigurationSchema } from "../composites/selector.schema.js";
+import { conditionalConfigurationSchema } from "../composites/conditional.schema.js";
+import { reactiveSequenceConfigurationSchema } from "../composites/reactive-sequence.schema.js";
+import { memorySequenceConfigurationSchema } from "../composites/memory-sequence.schema.js";
+import { recoveryConfigurationSchema } from "../composites/recovery.schema.js";
+
+// Action schemas - Script removed, use CodeExecution instead
+
+/**
+ * Central registry mapping node types to their validation schemas
+ *
+ * Responsibilities:
+ * - Register Zod schemas for each node type
+ * - Provide schema lookup by node type
+ * - Validate configurations against registered schemas
+ * - Fallback to base schema for unregistered types
+ *
+ * Usage:
+ * ```typescript
+ * // Register a schema
+ * schemaRegistry.register('Timeout', timeoutConfigurationSchema);
+ *
+ * // Get a schema
+ * const schema = schemaRegistry.getSchema('Timeout');
+ *
+ * // Validate configuration
+ * const config = schemaRegistry.validate('Timeout', { id: 'test', timeoutMs: 1000 });
+ * ```
+ */
+export class SchemaRegistry {
+  private schemas = new Map<string, z.ZodSchema>();
+
+  constructor() {
+    this.registerAllSchemas();
+  }
+
+  /**
+   * Register all node schemas
+   * Called automatically on construction
+   */
+  private registerAllSchemas(): void {
+    // Register decorator schemas
+    this.register("Timeout", timeoutConfigurationSchema);
+    this.register("Delay", delayConfigurationSchema);
+    this.register("Repeat", repeatConfigurationSchema);
+    this.register("Invert", invertConfigurationSchema);
+    this.register("ForceSuccess", forceSuccessConfigurationSchema);
+    this.register("ForceFailure", forceFailureConfigurationSchema);
+    this.register("Precondition", preconditionConfigurationSchema);
+    this.register("RunOnce", runOnceConfigurationSchema);
+    this.register(
+      "KeepRunningUntilFailure",
+      keepRunningUntilFailureConfigurationSchema,
+    );
+    this.register("SoftAssert", softAssertConfigurationSchema);
+
+    // Register composite schemas
+    this.register("Parallel", parallelConfigurationSchema);
+    this.register("ForEach", forEachConfigurationSchema);
+    this.register("While", whileConfigurationSchema);
+    this.register("SubTree", subTreeConfigurationSchema);
+    this.register("Sequence", sequenceConfigurationSchema);
+    this.register("Selector", selectorConfigurationSchema);
+    this.register("Conditional", conditionalConfigurationSchema);
+    this.register("ReactiveSequence", reactiveSequenceConfigurationSchema);
+    this.register("MemorySequence", memorySequenceConfigurationSchema);
+    this.register("Recovery", recoveryConfigurationSchema);
+
+    // Action schemas - Script removed, use CodeExecution instead
+  }
+
+  /**
+   * Register a validation schema for a node type
+   *
+   * @param nodeType - Name of the node type (e.g., 'Timeout', 'Sequence')
+   * @param schema - Zod schema for validating this node type's configuration
+   * @throws Error if node type is already registered
+   *
+   * @example
+   * ```typescript
+   * schemaRegistry.register('Timeout', timeoutConfigurationSchema);
+   * ```
+   */
+  register(nodeType: string, schema: z.ZodSchema): void {
+    if (this.schemas.has(nodeType)) {
+      throw new Error(`Schema for node type '${nodeType}' already registered`);
+    }
+    this.schemas.set(nodeType, schema);
+  }
+
+  /**
+   * Get schema for a node type
+   * Returns base schema if no specific schema registered
+   *
+   * @param nodeType - Name of the node type
+   * @returns Zod schema for the node type (or base schema if not found)
+   *
+   * @example
+   * ```typescript
+   * const schema = schemaRegistry.getSchema('Timeout');
+   * const validated = schema.parse({ id: 'test', timeoutMs: 1000 });
+   * ```
+   */
+  getSchema(nodeType: string): z.ZodSchema {
+    return this.schemas.get(nodeType) || nodeConfigurationSchema;
+  }
+
+  /**
+   * Check if a schema is registered for a node type
+   *
+   * @param nodeType - Name of the node type
+   * @returns True if schema is registered, false otherwise
+   */
+  hasSchema(nodeType: string): boolean {
+    return this.schemas.has(nodeType);
+  }
+
+  /**
+   * Get all registered node types
+   *
+   * @returns Array of registered node type names
+   */
+  getRegisteredTypes(): string[] {
+    return Array.from(this.schemas.keys());
+  }
+
+  /**
+   * Validate configuration for a specific node type
+   * Throws ZodError if validation fails
+   *
+   * @param nodeType - Name of the node type
+   * @param config - Configuration object to validate
+   * @returns Validated and parsed configuration
+   * @throws ZodError if validation fails
+   *
+   * @example
+   * ```typescript
+   * const config = schemaRegistry.validate('Timeout', {
+   *   id: 'test',
+   *   timeoutMs: 1000
+   * });
+   * ```
+   */
+  validate<T>(nodeType: string, config: unknown): T {
+    const schema = this.getSchema(nodeType);
+    return schema.parse(config) as T;
+  }
+
+  /**
+   * Safe validation that returns success/error result
+   * Does not throw errors
+   *
+   * @param nodeType - Name of the node type
+   * @param config - Configuration object to validate
+   * @returns Result with success/error
+   *
+   * @example
+   * ```typescript
+   * const result = schemaRegistry.safeParse('Timeout', { id: 'test', timeoutMs: -100 });
+   * if (result.success) {
+   *   console.log(result.data);
+   * } else {
+   *   console.error(result.error);
+   * }
+   * ```
+   */
+  safeParse(
+    nodeType: string,
+    config: unknown,
+  ):
+    | { success: true; data: unknown }
+    | { success: false; error: z.ZodError<unknown> } {
+    const schema = this.getSchema(nodeType);
+    return schema.safeParse(config);
+  }
+
+  /**
+   * Clear all registered schemas
+   * Useful for testing
+   */
+  clear(): void {
+    this.schemas.clear();
+  }
+}
+
+/**
+ * Global singleton schema registry instance
+ * Used by Registry class for validation
+ */
+export const schemaRegistry = new SchemaRegistry();
+
+// Re-export for convenience
+export * from "./base.schema.js";
+export * from "./validation.js";
+export * from "./tree-definition.schema.js";