@onlineapps/cookbook-core 1.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/cookbook-core",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "description": "Core cookbook parsing and validation - lightweight foundation for workflow definitions",
   "main": "src/index.js",
   "scripts": {

package/schemas/cookbook.v2.schema.json

@@ -0,0 +1,728 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://onlineapps.com/schemas/cookbook/v2.1.0/cookbook.schema.json",
+  "title": "Cookbook Workflow Schema v2.1",
+  "description": "Schema for defining workflow orchestration with snake_case convention",
+  "type": "object",
+  "required": ["version", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^2\\.\\d+\\.\\d+$",
+      "description": "Schema version (must start with 2.x.x)"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable workflow name"
+    },
+    "description": {
+      "type": "string",
+      "description": "Workflow description"
+    },
+    "config": {
+      "$ref": "#/definitions/Config",
+      "description": "Global configuration and defaults"
+    },
+    "api_input": {
+      "type": "object",
+      "description": "Expected input parameters for the workflow",
+      "additionalProperties": true
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/definitions/Step"
+      },
+      "description": "Array of workflow steps"
+    },
+    "delivery": {
+      "$ref": "#/definitions/DeliveryConfig",
+      "description": "Delivery strategy and destinations for workflow output"
+    }
+  },
+  "definitions": {
+    "Config": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "default_timeout_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Default timeout for all steps in milliseconds"
+        },
+        "default_retry": {
+          "$ref": "#/definitions/RetryConfig",
+          "description": "Default retry configuration for all steps"
+        }
+      }
+    },
+    "Step": {
+      "type": "object",
+      "required": ["step_id", "type"],
+      "oneOf": [
+        { "$ref": "#/definitions/TaskStep" },
+        { "$ref": "#/definitions/ForeachStep" },
+        { "$ref": "#/definitions/ForkJoinStep" },
+        { "$ref": "#/definitions/SwitchStep" },
+        { "$ref": "#/definitions/SubWorkflowStep" },
+        { "$ref": "#/definitions/WaitStep" },
+        { "$ref": "#/definitions/DispatchStep" }
+      ]
+    },
+    "TaskStep": {
+      "type": "object",
+      "required": ["step_id", "type", "service", "operation"],
+      "additionalProperties": false,
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_]+$",
+          "description": "Unique identifier for the step"
+        },
+        "type": {
+          "const": "task",
+          "description": "Step type"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable step name"
+        },
+        "service": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$",
+          "description": "Target microservice name"
+        },
+        "operation": {
+          "type": "string",
+          "description": "Operation ID from OpenAPI spec (required for task steps)"
+        },
+        "input": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Input parameters for the operation"
+        },
+        "output": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Output mapping to workflow context"
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Timeout in milliseconds (overrides default)"
+        },
+        "retry": {
+          "$ref": "#/definitions/RetryConfig",
+          "description": "Retry configuration (overrides default)"
+        },
+        "on_error": {
+          "$ref": "#/definitions/ErrorHandler",
+          "description": "Error handling configuration"
+        },
+        "compensate": {
+          "$ref": "#/definitions/CompensationStep",
+          "description": "Rollback/compensation configuration"
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Array of step_ids this step depends on"
+        }
+      }
+    },
+    "ForeachStep": {
+      "type": "object",
+      "required": ["step_id", "type", "iterator", "steps"],
+      "additionalProperties": false,
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_]+$"
+        },
+        "type": {
+          "const": "foreach"
+        },
+        "name": {
+          "type": "string"
+        },
+        "iterator": {
+          "type": "string",
+          "pattern": "^\\$\\{.+\\}$",
+          "description": "Reference to array to iterate over"
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/Step"
+          },
+          "description": "Steps to execute for each item"
+        },
+        "output": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "How to aggregate results"
+        },
+        "max_concurrency": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum parallel executions"
+        },
+        "on_error": {
+          "$ref": "#/definitions/ErrorHandler"
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "ForkJoinStep": {
+      "type": "object",
+      "required": ["step_id", "type", "branches", "join"],
+      "additionalProperties": false,
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_]+$"
+        },
+        "type": {
+          "const": "fork_join"
+        },
+        "name": {
+          "type": "string"
+        },
+        "branches": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "type": "object",
+            "required": ["branch_id", "steps"],
+            "properties": {
+              "branch_id": {
+                "type": "string"
+              },
+              "steps": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "$ref": "#/definitions/Step"
+                }
+              }
+            }
+          },
+          "description": "Parallel branches to execute"
+        },
+        "join": {
+          "type": "object",
+          "required": ["strategy"],
+          "properties": {
+            "strategy": {
+              "enum": ["all", "first", "race", "merge"],
+              "description": "How to join branch results"
+            },
+            "timeout_ms": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        "output": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "on_error": {
+          "$ref": "#/definitions/ErrorHandler"
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "SwitchStep": {
+      "type": "object",
+      "required": ["step_id", "type", "expression", "cases", "default"],
+      "additionalProperties": false,
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_]+$"
+        },
+        "type": {
+          "const": "switch"
+        },
+        "name": {
+          "type": "string"
+        },
+        "expression": {
+          "type": "string",
+          "pattern": "^\\$\\{.+\\}$",
+          "description": "Expression to evaluate for switch"
+        },
+        "cases": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["steps"],
+            "properties": {
+              "steps": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "$ref": "#/definitions/Step"
+                }
+              }
+            }
+          },
+          "description": "Case branches"
+        },
+        "default": {
+          "type": "object",
+          "required": ["steps"],
+          "properties": {
+            "steps": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/definitions/Step"
+              }
+            }
+          },
+          "description": "Default branch (required)"
+        },
+        "on_error": {
+          "$ref": "#/definitions/ErrorHandler"
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "SubWorkflowStep": {
+      "type": "object",
+      "required": ["step_id", "type", "workflow_id"],
+      "additionalProperties": false,
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_]+$"
+        },
+        "type": {
+          "const": "sub_workflow"
+        },
+        "name": {
+          "type": "string"
+        },
+        "workflow_id": {
+          "type": "string",
+          "description": "ID of workflow to execute"
+        },
+        "parameters": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Parameters to pass to sub-workflow"
+        },
+        "output": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "on_error": {
+          "$ref": "#/definitions/ErrorHandler"
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "WaitStep": {
+      "type": "object",
+      "required": ["step_id", "type", "duration_ms"],
+      "additionalProperties": false,
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_]+$"
+        },
+        "type": {
+          "const": "wait"
+        },
+        "name": {
+          "type": "string"
+        },
+        "duration_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Wait duration in milliseconds"
+        },
+        "message": {
+          "type": "string",
+          "description": "Optional message explaining the wait"
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "DispatchStep": {
+      "type": "object",
+      "required": ["step_id", "type", "method", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_]+$"
+        },
+        "type": {
+          "const": "dispatch"
+        },
+        "name": {
+          "type": "string"
+        },
+        "method": {
+          "enum": ["webhook", "http", "grpc", "kafka", "sqs"],
+          "description": "Dispatch method"
+        },
+        "target": {
+          "type": "string",
+          "description": "Target URL or address"
+        },
+        "input": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "retry": {
+          "$ref": "#/definitions/RetryConfig"
+        },
+        "on_error": {
+          "$ref": "#/definitions/ErrorHandler"
+        },
+        "depends_on": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "RetryConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_attempts": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum retry attempts"
+        },
+        "delay_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Delay between retries in milliseconds"
+        },
+        "backoff": {
+          "enum": ["linear", "exponential"],
+          "description": "Backoff strategy"
+        },
+        "max_delay_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum delay for exponential backoff"
+        }
+      }
+    },
+    "ErrorHandler": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "strategy": {
+          "enum": ["retry", "fail", "continue", "compensate"],
+          "description": "Error handling strategy"
+        },
+        "retry": {
+          "$ref": "#/definitions/RetryConfig"
+        },
+        "catch": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["error_type", "handler_step"],
+            "properties": {
+              "error_type": {
+                "type": "string",
+                "description": "Type of error to catch"
+              },
+              "handler_step": {
+                "type": "string",
+                "description": "Step to execute on this error"
+              }
+            }
+          },
+          "description": "Specific error handlers"
+        },
+        "finally": {
+          "type": "string",
+          "description": "Step to always execute"
+        }
+      }
+    },
+    "CompensationStep": {
+      "type": "object",
+      "required": ["step_id", "service", "operation"],
+      "additionalProperties": false,
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_]+$",
+          "description": "ID for compensation step"
+        },
+        "service": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$"
+        },
+        "operation": {
+          "type": "string"
+        },
+        "input": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "DeliveryConfig": {
+      "type": "object",
+      "required": ["handler"],
+      "additionalProperties": false,
+      "properties": {
+        "handler": {
+          "enum": ["dispatcher", "service_step", "none"],
+          "description": "Delivery handler selection"
+        },
+        "allow_skip": {
+          "type": "boolean",
+          "default": false,
+          "description": "Allow dispatcher to skip delivery without failing workflow"
+        },
+        "delivery_step": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_]+$",
+          "description": "Step ID that performs delivery when handler=service_step"
+        },
+        "destinations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/DeliveryDestination"
+          },
+          "default": []
+        },
+        "output": {
+          "$ref": "#/definitions/DeliveryOutput"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "handler": { "const": "dispatcher" }
+            }
+          },
+          "then": {
+            "required": ["destinations", "output"],
+            "properties": {
+              "destinations": {
+                "minItems": 1
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "handler": { "const": "service_step" }
+            }
+          },
+          "then": {
+            "required": ["delivery_step", "output"]
+          }
+        }
+      ]
+    },
+    "DeliveryDestination": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "enum": ["webhook", "websocket", "public_url"],
+          "description": "Delivery channel type"
+        },
+        "name": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9._-]+$",
+          "description": "Optional identifier for monitoring"
+        },
+        "enabled": {
+          "type": "boolean",
+          "default": true
+        },
+        "retry": {
+          "$ref": "#/definitions/RetryConfig"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": { "const": "webhook" }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/DeliveryWebhookOptions"
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": { "const": "websocket" }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/DeliveryWebsocketOptions"
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": { "const": "public_url" }
+            }
+          },
+          "then": {
+            "$ref": "#/definitions/DeliveryPublicUrlOptions"
+          }
+        }
+      ]
+    },
+    "DeliveryWebhookOptions": {
+      "type": "object",
+      "required": ["url", "method"],
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Target webhook URL"
+        },
+        "method": {
+          "type": "string",
+          "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "body_template": {
+          "type": ["object", "array"],
+          "description": "Optional custom payload template"
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 100,
+          "description": "Request timeout"
+        }
+      }
+    },
+    "DeliveryWebsocketOptions": {
+      "type": "object",
+      "properties": {
+        "client_id": {
+          "type": "string",
+          "description": "Client session identifier"
+        },
+        "tenant_id": {
+          "type": "string",
+          "description": "Tenant/topic identifier"
+        },
+        "events": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "anyOf": [
+        { "required": ["client_id"] },
+        { "required": ["tenant_id"] }
+      ]
+    },
+    "DeliveryPublicUrlOptions": {
+      "type": "object",
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9._\\-/\\${}]+$",
+          "description": "Storage key / relative path"
+        },
+        "ttl_seconds": {
+          "type": "integer",
+          "minimum": 60,
+          "description": "Time to live for generated URL"
+        },
+        "access": {
+          "type": "string",
+          "enum": ["public", "signed"],
+          "default": "signed"
+        },
+        "max_downloads": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "DeliveryOutput": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-zA-Z0-9_]+$"
+      },
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "boolean",
+          "object",
+          "array"
+        ]
+      }
+    }
+  }
+}

package/src/index.js

@@ -16,7 +16,9 @@ const {
 const {
   validateCookbook,
   validateStep,
-  CookbookValidationError
+  CookbookValidationError,
+  detectVersion,
+  loadSchema: loadValidatorSchema
 } = require('./validator');
 
 const {
@@ -40,6 +42,7 @@ module.exports = {
   // Validator functions
   validateCookbook,
   validateStep,
+  detectVersion,
 
   // Reference validation
   validateAllReferences,
@@ -50,11 +53,12 @@ module.exports = {
   // Schema access
   CookbookSchema,
   loadSchema,
+  loadValidatorSchema,
 
   // Error classes
   CookbookValidationError,
 
   // Utility exports
-  VERSION: '1.0.0',
-  SCHEMA_VERSION: '1.0.0'
+  VERSION: '2.0.0',
+  SCHEMA_VERSION: '2.1.0'
 };

package/src/parser/cookbookValidator.js

@@ -281,7 +281,7 @@ function validateStep(step, context, mode = 'default') {
         }
       }
 
-      allowedProps = new Set([...commonAllowed, 'name', 'service', 'action', 'endpoint', 'input', 'output', 'depends_on', 'retry', 'timeoutMs']);
+      allowedProps = new Set([...commonAllowed, 'name', 'service', 'action', 'endpoint', 'operation', 'input', 'output', 'depends_on', 'retry', 'timeoutMs', 'on_error']);
       break;
     }
     case 'foreach': {

package/src/parser/cookbookValidatorV2.js

@@ -0,0 +1,339 @@
+/**
+ * @fileoverview
+ * Cookbook Validator v2.0 - Single Source of Truth through JSON Schema
+ *
+ * This validator uses ONLY JSON Schema (v2.0) for validation.
+ * No duplicate manual validation logic.
+ *
+ * Features:
+ * - Full JSON Schema draft-07 validation via AJV
+ * - Support for v1.0 backwards compatibility
+ * - Automatic migration suggestions for v1.0 cookbooks
+ * - Comprehensive error messages with paths
+ */
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Custom Error class for validation errors
+ */
+class CookbookValidationError extends Error {
+  constructor(message, errors = null) {
+    super(message);
+    this.name = 'CookbookValidationError';
+    this.validationErrors = errors;
+  }
+}
+
+/**
+ * Load schema file with version detection
+ */
+function loadSchema(version = '2.0') {
+  const schemaMap = {
+    '1.0': 'cookbook.schema.json',       // Legacy v1.0 schema
+    '2.0': 'cookbook.v2.schema.json'     // New v2.0 schema with snake_case
+  };
+
+  const filename = schemaMap[version.split('.')[0] + '.0'] || schemaMap['2.0'];
+  const schemaPath = path.join(__dirname, '../../schemas', filename);
+
+  if (!fs.existsSync(schemaPath)) {
+    throw new CookbookValidationError(`Schema file not found: ${filename}`);
+  }
+
+  return JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+}
+
+/**
+ * Create AJV validator instance with custom error messages
+ */
+function createValidator(schema) {
+  const ajv = new Ajv({
+    allErrors: true,
+    strict: false,  // Needed for 'condition' property
+    verbose: true
+  });
+
+  addFormats(ajv);
+
+  // Add custom error messages
+  ajv.addKeyword({
+    keyword: 'errorMessage',
+    schemaType: 'string',
+    compile: (schemaVal) => {
+      return function validate(data, dataPath) {
+        validate.errors = [{
+          keyword: 'errorMessage',
+          message: schemaVal,
+          params: {}
+        }];
+        return true;
+      };
+    }
+  });
+
+  return ajv.compile(schema);
+}
+
+/**
+ * Format AJV errors into readable messages
+ */
+function formatErrors(errors) {
+  if (!errors || errors.length === 0) return 'Unknown validation error';
+
+  return errors.map(err => {
+    const path = err.instancePath || err.dataPath || '/';
+    const field = path.split('/').pop() || 'root';
+
+    switch (err.keyword) {
+      case 'required':
+        return `Missing required field '${err.params.missingProperty}' at ${path}`;
+
+      case 'additionalProperties':
+        return `Unexpected field '${err.params.additionalProperty}' at ${path}`;
+
+      case 'enum':
+        return `Invalid value for '${field}' at ${path}. Allowed: ${err.params.allowedValues.join(', ')}`;
+
+      case 'type':
+        return `Invalid type for '${field}' at ${path}. Expected ${err.params.type}, got ${typeof err.data}`;
+
+      case 'pattern':
+        return `Invalid format for '${field}' at ${path}. Must match pattern: ${err.params.pattern}`;
+
+      case 'const':
+        return `Field '${field}' at ${path} must be exactly '${err.params.allowedValue}'`;
+
+      default:
+        return err.message || `Validation error at ${path}`;
+    }
+  }).join('\n');
+}
+
+/**
+ * Detect cookbook version and suggest migration if needed
+ */
+function detectVersion(cookbook) {
+  // Check version field first
+  if (cookbook.version) {
+    const major = cookbook.version.split('.')[0];
+    if (major === '1') return '1.0';
+    if (major === '2') return '2.0';
+  }
+
+  // Auto-detect based on field names
+  const hasV1Fields = cookbook.steps && cookbook.steps.some(step =>
+    'id' in step && !('step_id' in step)
+  );
+
+  const hasV2Fields = cookbook.steps && cookbook.steps.some(step =>
+    'step_id' in step && !('id' in step)
+  );
+
+  if (hasV1Fields) return '1.0';
+  if (hasV2Fields) return '2.0';
+
+  // Default to v2.0 for new cookbooks
+  return '2.0';
+}
+
+/**
+ * Check if migration is needed and provide suggestions
+ */
+function checkMigration(cookbook, detectedVersion) {
+  if (detectedVersion === '1.0') {
+    const suggestions = [];
+
+    // Check for camelCase fields that should be snake_case
+    if (cookbook.steps) {
+      cookbook.steps.forEach((step, idx) => {
+        if ('id' in step) {
+          suggestions.push(`- Step ${idx}: Rename 'id' to 'step_id'`);
+        }
+        if ('timeoutMs' in step) {
+          suggestions.push(`- Step ${idx}: Rename 'timeoutMs' to 'timeout_ms'`);
+        }
+        const retry = step.retry || {};
+        if ('maxAttempts' in retry) {
+          suggestions.push(`- Step ${idx}: Rename 'retry.maxAttempts' to 'retry.max_attempts'`);
+        }
+        if ('delayMs' in retry) {
+          suggestions.push(`- Step ${idx}: Rename 'retry.delayMs' to 'retry.delay_ms'`);
+        }
+      });
+    }
+
+    if (suggestions.length > 0) {
+      console.warn('\n⚠️  Migration suggestions for v2.0:');
+      console.warn(suggestions.join('\n'));
+      console.warn('\nRun migration script: npm run migrate:cookbook v1-to-v2 <input> <output>\n');
+    }
+  }
+}
+
+/**
+ * Main validation function
+ *
+ * @param {object} cookbook - The cookbook object to validate
+ * @param {object} options - Validation options
+ * @param {string} options.version - Force specific version validation
+ * @param {boolean} options.strict - Use strict validation (default: true)
+ * @param {boolean} options.warnOnly - Only warn, don't throw (default: false)
+ * @returns {boolean} True if valid, throws error otherwise
+ */
+function validateCookbook(cookbook, options = {}) {
+  const {
+    version = null,
+    strict = true,
+    warnOnly = false
+  } = options;
+
+  // Detect version if not specified
+  const cookbookVersion = version || detectVersion(cookbook);
+
+  // Check if migration needed
+  checkMigration(cookbook, cookbookVersion);
+
+  // Load appropriate schema
+  const schema = loadSchema(cookbookVersion);
+
+  // Create validator
+  const validate = createValidator(schema);
+
+  // Validate
+  const isValid = validate(cookbook);
+
+  if (!isValid) {
+    const errorMessage = formatErrors(validate.errors);
+
+    if (warnOnly) {
+      console.warn('⚠️  Cookbook validation warnings:\n' + errorMessage);
+      return false;
+    } else {
+      throw new CookbookValidationError(
+        'Cookbook validation failed:\n' + errorMessage,
+        validate.errors
+      );
+    }
+  }
+
+  // Additional semantic validation (still using schema as source of truth)
+  validateSemantics(cookbook, cookbookVersion);
+
+  return true;
+}
+
+/**
+ * Semantic validation for things JSON Schema can't easily express
+ */
+function validateSemantics(cookbook, version) {
+  const stepIds = new Set();
+
+  // Check for duplicate step_ids (or ids in v1)
+  const idField = version === '1.0' ? 'id' : 'step_id';
+
+  function checkStep(step, path) {
+    const stepId = step[idField];
+    if (stepId) {
+      if (stepIds.has(stepId)) {
+        throw new CookbookValidationError(
+          `Duplicate ${idField} '${stepId}' found at ${path}`
+        );
+      }
+      stepIds.add(stepId);
+    }
+
+    // Check nested steps
+    if (step.steps) {
+      step.steps.forEach((nested, idx) =>
+        checkStep(nested, `${path}.steps[${idx}]`)
+      );
+    }
+    if (step.body) {
+      step.body.forEach((nested, idx) =>
+        checkStep(nested, `${path}.body[${idx}]`)
+      );
+    }
+    if (step.branches) {
+      step.branches.forEach((branch, idx) => {
+        if (branch.steps) {
+          branch.steps.forEach((nested, jdx) =>
+            checkStep(nested, `${path}.branches[${idx}].steps[${jdx}]`)
+          );
+        }
+      });
+    }
+    if (step.cases) {
+      Object.keys(step.cases).forEach(caseKey => {
+        const caseVal = step.cases[caseKey];
+        if (caseVal.steps) {
+          caseVal.steps.forEach((nested, idx) =>
+            checkStep(nested, `${path}.cases.${caseKey}.steps[${idx}]`)
+          );
+        }
+      });
+    }
+  }
+
+  // Check all steps
+  if (cookbook.steps) {
+    cookbook.steps.forEach((step, idx) =>
+      checkStep(step, `steps[${idx}]`)
+    );
+  }
+
+  // Check dependencies exist
+  if (version === '2.0' && cookbook.steps) {
+    cookbook.steps.forEach((step, idx) => {
+      if (step.depends_on) {
+        step.depends_on.forEach(dep => {
+          if (!stepIds.has(dep)) {
+            throw new CookbookValidationError(
+              `Step ${idx} depends on non-existent step_id '${dep}'`
+            );
+          }
+        });
+      }
+    });
+  }
+}
+
+/**
+ * Validate a single step (for testing purposes)
+ */
+function validateStep(step, version = '2.0') {
+  const schema = loadSchema(version);
+  const stepSchema = schema.definitions?.Step || schema.definitions?.TaskStep;
+
+  if (!stepSchema) {
+    throw new CookbookValidationError('Step schema definition not found');
+  }
+
+  const validate = createValidator({
+    ...stepSchema,
+    $schema: schema.$schema
+  });
+
+  const isValid = validate(step);
+
+  if (!isValid) {
+    throw new CookbookValidationError(
+      'Step validation failed:\n' + formatErrors(validate.errors),
+      validate.errors
+    );
+  }
+
+  return true;
+}
+
+// Export functions
+module.exports = {
+  validateCookbook,
+  validateStep,
+  CookbookValidationError,
+  detectVersion,
+  loadSchema
+};

package/src/validator.js

@@ -1,17 +1,22 @@
 'use strict';
 
 /**
- * Re-export validator functions from the parser module
+ * Re-export validator functions from the v2.0 parser module
+ * This now uses the v2.0 validator as the primary validator
  */
 
 const {
   validateCookbook,
   validateStep,
-  CookbookValidationError
-} = require('./parser/cookbookValidator');
+  CookbookValidationError,
+  detectVersion,
+  loadSchema
+} = require('./parser/cookbookValidatorV2');
 
 module.exports = {
   validateCookbook,
   validateStep,
-  CookbookValidationError
+  CookbookValidationError,
+  detectVersion,
+  loadSchema
 };