@q1k-oss/btree-workflows 0.0.1

package/src/yaml/parser.ts

@@ -0,0 +1,286 @@
+/**
+ * YAML parser for behavior tree definitions
+ * Implements 4-stage validation pipeline
+ */
+
+import * as yaml from "js-yaml";
+import type { Registry } from "../registry.js";
+import type { TreeNode } from "../types.js";
+import type { TreeDefinition } from "../schemas/tree-definition.schema.js";
+import {
+  YamlSyntaxError,
+  StructureValidationError,
+  ValidationErrors,
+  ValidationError,
+} from "./errors.js";
+import { treeDefinitionSchema } from "../schemas/tree-definition.schema.js";
+import { semanticValidator } from "./validation/semantic-validator.js";
+
+/**
+ * Options for YAML loading and validation
+ */
+export interface LoadOptions {
+  /**
+   * Enable validation (default: true)
+   */
+  validate?: boolean;
+
+  /**
+   * Fail on first error or collect all errors (default: true - fail fast)
+   */
+  failFast?: boolean;
+
+  /**
+   * Auto-generate IDs for nodes without IDs (default: true)
+   */
+  autoGenerateIds?: boolean;
+}
+
+/**
+ * Validation options for validateYaml()
+ */
+export interface ValidationOptions {
+  /**
+   * Collect all errors instead of failing fast (default: false)
+   */
+  collectAllErrors?: boolean;
+
+  /**
+   * Check semantic rules like references and circular deps (default: true)
+   */
+  checkReferences?: boolean;
+}
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings?: string[];
+}
+
+/**
+ * Parse YAML string to TreeDefinition
+ * Stage 1: YAML Syntax Validation
+ *
+ * @param yamlString - YAML content to parse
+ * @returns Parsed tree definition object
+ * @throws YamlSyntaxError if YAML is malformed
+ */
+export function parseYaml(yamlString: string): TreeDefinition {
+  try {
+    const parsed = yaml.load(yamlString);
+
+    if (!parsed || typeof parsed !== "object") {
+      throw new YamlSyntaxError(
+        "Invalid YAML: expected an object",
+        undefined,
+        undefined,
+        "Ensure your YAML defines a tree structure with 'type' field",
+      );
+    }
+
+    return parsed as TreeDefinition;
+  } catch (error) {
+    if (error instanceof YamlSyntaxError) {
+      throw error;
+    }
+
+    // Convert js-yaml errors to our error format
+    if (error instanceof yaml.YAMLException) {
+      throw new YamlSyntaxError(
+        error.message,
+        error.mark?.line,
+        error.mark?.column,
+        "Check YAML syntax (indentation, colons, quotes)",
+      );
+    }
+
+    throw new YamlSyntaxError(
+      `Failed to parse YAML: ${error instanceof Error ? error.message : String(error)}`,
+      undefined,
+      undefined,
+      "Ensure your YAML is well-formed",
+    );
+  }
+}
+
+/**
+ * Validate tree definition structure
+ * Stage 2: Structure Validation (using Zod schema)
+ *
+ * @param definition - Parsed tree definition
+ * @throws StructureValidationError if structure is invalid
+ */
+function validateStructure(definition: unknown): TreeDefinition {
+  try {
+    return treeDefinitionSchema.parse(definition) as TreeDefinition;
+  } catch (error) {
+    // Convert Zod errors to StructureValidationError
+    throw new StructureValidationError(
+      `Invalid tree structure: ${error instanceof Error ? error.message : String(error)}`,
+      undefined,
+      "Ensure all nodes have 'type' field and children are arrays",
+    );
+  }
+}
+
+/**
+ * Load and create tree from YAML string
+ *
+ * @param yamlString - YAML content defining the tree
+ * @param registry - Registry with registered node types
+ * @param options - Loading options
+ * @returns Created tree node
+ * @throws ValidationError if validation fails
+ *
+ * @example
+ * ```typescript
+ * const yaml = `
+ * type: Sequence
+ * id: my-seq
+ * children:
+ *   - type: PrintAction
+ *     id: action1
+ * `;
+ *
+ * const tree = loadTreeFromYaml(yaml, registry);
+ * ```
+ */
+export function loadTreeFromYaml(
+  yamlString: string,
+  registry: Registry,
+  options: LoadOptions = {},
+): TreeNode {
+  const { validate = true, failFast = true, autoGenerateIds = true } = options;
+
+  // Stage 1: Parse YAML syntax
+  const parsed = parseYaml(yamlString);
+
+  if (validate) {
+    // Stage 2: Validate structure
+    const definition = validateStructure(parsed);
+
+    // Stage 3 & 4: Node config and semantic validation happen in Registry.createTree()
+    // which calls schema validation for each node
+    if (failFast) {
+      // Semantic validation
+      const semanticErrors = semanticValidator.validate(definition, registry);
+      if (semanticErrors.length > 0) {
+        if (failFast) {
+          throw semanticErrors[0];
+        } else {
+          throw new ValidationErrors(semanticErrors);
+        }
+      }
+    }
+
+    // Create tree (this validates node configs via schemas)
+    return registry.createTree(definition);
+  }
+
+  // No validation - directly create tree
+  return registry.createTree(parsed);
+}
+
+/**
+ * Validate YAML without creating tree
+ * Useful for editors and validators
+ *
+ * @param yamlString - YAML content to validate
+ * @param registry - Registry with registered node types
+ * @param options - Validation options
+ * @returns Validation result with errors
+ *
+ * @example
+ * ```typescript
+ * const result = validateYaml(yaml, registry);
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+export function validateYaml(
+  yamlString: string,
+  registry: Registry,
+  options: ValidationOptions = {},
+): ValidationResult {
+  const { collectAllErrors = false, checkReferences = true } = options;
+  const errors: ValidationError[] = [];
+
+  try {
+    // Stage 1: Parse YAML
+    const parsed = parseYaml(yamlString);
+
+    // Stage 2: Validate structure
+    const definition = validateStructure(parsed);
+
+    // Stage 4: Semantic validation
+    if (checkReferences) {
+      const semanticErrors = semanticValidator.validate(definition, registry);
+      errors.push(...semanticErrors);
+    }
+
+    // Stage 3: Node config validation (via safe create)
+    if (errors.length === 0 || collectAllErrors) {
+      const result = registry.safeCreateTree(definition);
+      if (!result.success) {
+        errors.push(
+          new StructureValidationError(
+            result.error.message,
+            undefined,
+            "Check node configurations match their schema requirements",
+          ),
+        );
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  } catch (error) {
+    if (error instanceof ValidationErrors) {
+      return {
+        valid: false,
+        errors: error.errors,
+      };
+    }
+
+    if (error instanceof ValidationError) {
+      errors.push(error);
+    } else {
+      errors.push(
+        new YamlSyntaxError(
+          error instanceof Error ? error.message : String(error),
+        ),
+      );
+    }
+
+    return {
+      valid: false,
+      errors,
+    };
+  }
+}
+
+/**
+ * Convert TreeDefinition to YAML string
+ *
+ * @param definition - Tree definition to convert
+ * @returns YAML string representation
+ *
+ * @example
+ * ```typescript
+ * const definition = { type: 'Sequence', id: 'root', children: [] };
+ * const yamlString = toYaml(definition);
+ * ```
+ */
+export function toYaml(definition: TreeDefinition): string {
+  return yaml.dump(definition, {
+    indent: 2,
+    lineWidth: 80,
+    noRefs: true,
+  });
+}

package/src/yaml/validation/semantic-validator.ts

@@ -0,0 +1,196 @@
+/**
+ * Semantic validation (Stage 4)
+ * Validates semantic rules like ID uniqueness, circular references, etc.
+ */
+
+import type { Registry } from "../../registry.js";
+import type { TreeDefinition } from "../../schemas/tree-definition.schema.js";
+import { SemanticValidationError } from "../errors.js";
+
+/**
+ * Semantic validator for tree definitions
+ * Validates cross-node rules that can't be expressed in schemas
+ */
+class SemanticValidator {
+  /**
+   * Validate semantic rules for a tree definition
+   *
+   * @param definition - Tree definition to validate
+   * @param registry - Registry to check node types and tree references
+   * @returns Array of validation errors (empty if valid)
+   */
+  validate(definition: TreeDefinition, registry: Registry): SemanticValidationError[] {
+    const errors: SemanticValidationError[] = [];
+
+    // Track IDs for uniqueness checking
+    const seenIds = new Set<string>();
+
+    // Track SubTree references for circular dependency detection
+    const subTreePath: string[] = [];
+
+    // Recursive validation
+    this.validateNode(definition, registry, seenIds, subTreePath, "", errors);
+
+    return errors;
+  }
+
+  /**
+   * Recursively validate a node and its children
+   */
+  private validateNode(
+    node: TreeDefinition,
+    registry: Registry,
+    seenIds: Set<string>,
+    subTreePath: string[],
+    path: string,
+    errors: SemanticValidationError[],
+  ): void {
+    const nodePath = path ? `${path}.${node.id || node.type}` : node.id || node.type;
+
+    // Validate node type exists in registry
+    if (!registry.has(node.type)) {
+      errors.push(
+        new SemanticValidationError(
+          `Unknown node type '${node.type}'`,
+          nodePath,
+          `Available types: ${registry.getRegisteredTypes().join(", ")}`,
+        ),
+      );
+      return; // Can't continue validation without valid type
+    }
+
+    // Validate ID uniqueness
+    if (node.id) {
+      if (seenIds.has(node.id)) {
+        errors.push(
+          new SemanticValidationError(
+            `Duplicate ID '${node.id}'`,
+            nodePath,
+            "Use unique IDs for each node in the tree",
+          ),
+        );
+      } else {
+        seenIds.add(node.id);
+      }
+    }
+
+    // Validate SubTree references for circular dependencies
+    if (node.type === "SubTree") {
+      const treeId = (node.props?.treeId as string) || "";
+
+      if (!treeId) {
+        errors.push(
+          new SemanticValidationError(
+            "SubTree node missing 'treeId' property",
+            nodePath,
+            "Specify which tree to reference with 'treeId' in props",
+          ),
+        );
+      } else {
+        // Check for circular reference
+        if (subTreePath.includes(treeId)) {
+          errors.push(
+            new SemanticValidationError(
+              `Circular SubTree reference detected: ${subTreePath.join(" -> ")} -> ${treeId}`,
+              nodePath,
+              "Remove circular tree references",
+            ),
+          );
+        }
+
+        // Check if referenced tree exists (if registry has tree lookup)
+        if (registry.hasTree && !registry.hasTree(treeId)) {
+          errors.push(
+            new SemanticValidationError(
+              `SubTree references unknown tree '${treeId}'`,
+              nodePath,
+              `Register the tree '${treeId}' before referencing it`,
+            ),
+          );
+        }
+      }
+    }
+
+    // Validate children based on node category
+    const metadata = registry.getMetadata(node.type);
+    if (metadata) {
+      if (metadata.category === "decorator") {
+        // Decorators must have exactly 1 child
+        const childCount = node.children?.length || 0;
+        if (childCount !== 1) {
+          errors.push(
+            new SemanticValidationError(
+              `Decorator '${node.type}' must have exactly 1 child (has ${childCount})`,
+              nodePath,
+              "Decorators wrap a single child node",
+            ),
+          );
+        }
+      }
+
+      // Some composites have specific child requirements
+      if (node.type === "While") {
+        const childCount = node.children?.length || 0;
+        if (childCount !== 2) {
+          errors.push(
+            new SemanticValidationError(
+              `While node requires exactly 2 children: condition and body (has ${childCount})`,
+              nodePath,
+              "First child is the condition, second is the body to execute",
+            ),
+          );
+        }
+      }
+
+      if (node.type === "Conditional") {
+        const childCount = node.children?.length || 0;
+        if (childCount < 2 || childCount > 3) {
+          errors.push(
+            new SemanticValidationError(
+              `Conditional node requires 2-3 children: condition, then, optional else (has ${childCount})`,
+              nodePath,
+              "First child is condition, second is 'then' branch, third is optional 'else' branch",
+            ),
+          );
+        }
+      }
+
+      if (node.type === "ForEach") {
+        const childCount = node.children?.length || 0;
+        if (childCount === 0) {
+          errors.push(
+            new SemanticValidationError(
+              "ForEach node requires at least 1 child (the body to execute for each item)",
+              nodePath,
+              "Add a child node to execute for each item in the collection",
+            ),
+          );
+        }
+      }
+    }
+
+    // Recursively validate children
+    if (node.children && Array.isArray(node.children)) {
+      const newSubTreePath =
+        node.type === "SubTree" && node.props?.treeId
+          ? [...subTreePath, node.props.treeId as string]
+          : subTreePath;
+
+      node.children.forEach((child, index) => {
+        this.validateNode(
+          child,
+          registry,
+          seenIds,
+          newSubTreePath,
+          `${nodePath}.children[${index}]`,
+          errors,
+        );
+      });
+    }
+  }
+}
+
+/**
+ * Singleton semantic validator instance
+ */
+export const semanticValidator = new SemanticValidator();

package/templates/google-sheets/insert-row.yaml

@@ -0,0 +1,76 @@
+# Template: GoogleSheets.InsertRow
+#
+# Friendly interface for inserting rows into Google Sheets.
+# Handles data transformation to Active Pieces format.
+#
+# Expected inputs (set on blackboard before calling):
+#   tpl_spreadsheet: string   - Spreadsheet ID
+#   tpl_sheet: number         - Sheet index (default: 0)
+#   tpl_values: array|object  - Values as array or { "Column": "value" }
+#
+# Output:
+#   tpl_result: object        - Result from insert operation
+
+type: Sequence
+id: google-sheets-insert-row
+children:
+  # Step 1: Validate and prepare inputs
+  - type: CodeExecution
+    id: _prepare-inputs
+    props:
+      language: javascript
+      code: |
+        const spreadsheet = getBB('tpl_spreadsheet');
+        if (!spreadsheet) {
+          throw new Error('Missing required input: tpl_spreadsheet');
+        }
+
+        const sheet = getBB('tpl_sheet');
+        const sheetId = (sheet === undefined || sheet === null) ? 0 : Number(sheet);
+
+        const values = getBB('tpl_values');
+        if (!values) {
+          throw new Error('Missing required input: tpl_values');
+        }
+
+        // Transform values to Active Pieces format
+        let transformed;
+        if (Array.isArray(values)) {
+          transformed = { values: values };
+        } else if (typeof values === 'object') {
+          transformed = { values: Object.values(values) };
+        }
+
+        // Store prepared values
+        setBB('tpl_spreadsheetId', spreadsheet);
+        setBB('tpl_sheetId', sheetId);
+        setBB('tpl_transformedValues', transformed);
+
+  # Step 2: Log what we're doing
+  - type: LogMessage
+    id: _log-insert
+    props:
+      message: "Inserting row into sheet ${tpl_spreadsheetId}"
+      level: debug
+
+  # Step 3: Execute the insert
+  - type: IntegrationAction
+    id: _do-insert
+    props:
+      provider: google
+      action: insert_row
+      inputs:
+        spreadsheetId: "${bb.tpl_spreadsheetId}"
+        sheetId: "${bb.tpl_sheetId}"
+        first_row_headers: false
+        as_string: true
+        values: "${bb.tpl_transformedValues}"
+
+  # Step 4: Store result for caller
+  - type: CodeExecution
+    id: _store-result
+    props:
+      language: javascript
+      code: |
+        const result = getBB('_do-insert.result');
+        setBB('tpl_result', result);

package/templates/notification-sender.yaml

@@ -0,0 +1,33 @@
+# Notification Sender Template
+# Sends notifications through configured channels
+#
+# Inputs (expected on blackboard):
+#   - notificationMessage: string
+#   - notificationType: string (email, slack, sms)
+#   - recipient: string
+#
+# Outputs (set on blackboard):
+#   - notificationSent: boolean
+#   - notificationId: string (optional)
+
+type: Sequence
+id: notification-sender
+name: Notification Sender
+
+children:
+  - type: LogMessage
+    id: log-start
+    props:
+      message: "Preparing to send notification: ${notificationMessage}"
+      level: info
+
+  - type: LogMessage
+    id: log-type
+    props:
+      message: "Notification type: ${notificationType}, Recipient: ${recipient}"
+
+  - type: LogMessage
+    id: log-complete
+    props:
+      message: "Notification sent successfully"
+      level: info

package/templates/order-validation.yaml

@@ -0,0 +1,44 @@
+# Order Validation Template
+# Validates order data before processing
+#
+# Inputs (expected on blackboard):
+#   - orderId: string
+#   - items: array of order items
+#   - customerId: string (optional)
+#
+# Outputs (set on blackboard):
+#   - validationPassed: boolean
+#   - validationErrors: array of error messages
+
+type: Sequence
+id: order-validation
+name: Order Validation
+
+children:
+  - type: LogMessage
+    id: start-validation
+    props:
+      message: "Starting order validation for order: ${orderId}"
+      level: info
+
+  - type: Selector
+    id: validate-all
+    children:
+      - type: Sequence
+        id: all-checks
+        children:
+          - type: LogMessage
+            id: check-order-id
+            props:
+              message: "Validating order ID..."
+
+          - type: LogMessage
+            id: check-items
+            props:
+              message: "Validating order items..."
+
+          - type: LogMessage
+            id: validation-complete
+            props:
+              message: "Order validation completed successfully"
+              level: info

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "incremental": false,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "declaration": true,
+    "declarationMap": true,
+    "lib": ["ES2022"],
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*", "examples/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    watch: false,
+    globals: true,
+    environment: "node",
+    include: ["src/**/*.{test,spec}.{js,ts}"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      include: ["src/**/*.ts"],
+      exclude: [
+        "src/index.ts",
+        "src/**/*.test.ts",
+        "src/**/*.spec.ts",
+        "src/test-nodes.ts", // Test utilities
+        "src/scripting/generated/**/*", // Generated files
+      ],
+    },
+  },
+  resolve: {
+    extensions: [".ts", ".js"],
+  },
+});