@onlineapps/cookbook-core 2.1.8 → 2.1.10

package/package.json

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

package/src/CookbookHelpers.js

@@ -0,0 +1,276 @@
+'use strict';
+
+/**
+ * @fileoverview
+ * Cookbook 2.1 Helper Functions
+ * 
+ * STRICT RULES:
+ * - steps is ALWAYS an array
+ * - Access by index is FORBIDDEN - use findStep(stepId) instead
+ * - Reference steps ONLY by step_id
+ * - Iteration via forEach/map/filter ONLY
+ * 
+ * These helpers enforce safe access patterns for cookbook steps.
+ */
+
+/**
+ * CookbookHelpers - Safe access to cookbook steps
+ * 
+ * Usage:
+ *   const { findStep, forEachStep, getStepIds } = require('@onlineapps/cookbook-core');
+ *   
+ *   // Find step by step_id
+ *   const step = findStep(cookbook.steps, 'my-step-id');
+ *   
+ *   // Iterate all steps
+ *   forEachStep(cookbook.steps, (step, stepId) => { ... });
+ *   
+ *   // Get all step IDs in order
+ *   const ids = getStepIds(cookbook.steps);
+ */
+class CookbookHelpers {
+  /**
+   * Find a step by its step_id
+   * This is the PRIMARY method for accessing steps - NEVER use index!
+   * 
+   * @param {Array} steps - Array of step objects
+   * @param {string} stepId - The step_id to find
+   * @returns {Object|null} The step object or null if not found
+   * @throws {Error} If steps is not an array or stepId is not provided
+   */
+  static findStep(steps, stepId) {
+    if (!stepId) {
+      throw new Error('[CookbookHelpers.findStep] stepId is required - never access by index!');
+    }
+    
+    if (!Array.isArray(steps)) {
+      // Handle V2.0 object format for backwards compatibility during transition
+      if (steps && typeof steps === 'object') {
+        return steps[stepId] || null;
+      }
+      throw new Error('[CookbookHelpers.findStep] steps must be an array (V2.1 format)');
+    }
+    
+    return steps.find(step => step.step_id === stepId) || null;
+  }
+
+  /**
+   * Iterate over all steps with their step_ids
+   * 
+   * @param {Array} steps - Array of step objects
+   * @param {Function} callback - Function(step, stepId, index) - index for internal use only!
+   * @throws {Error} If steps is not an array
+   */
+  static forEachStep(steps, callback) {
+    if (!Array.isArray(steps)) {
+      // Handle V2.0 object format for backwards compatibility during transition
+      if (steps && typeof steps === 'object') {
+        Object.entries(steps).forEach(([stepId, step], index) => {
+          callback(step, stepId, index);
+        });
+        return;
+      }
+      throw new Error('[CookbookHelpers.forEachStep] steps must be an array (V2.1 format)');
+    }
+    
+    steps.forEach((step, index) => {
+      callback(step, step.step_id, index);
+    });
+  }
+
+  /**
+   * Map over all steps
+   * 
+   * @param {Array} steps - Array of step objects
+   * @param {Function} callback - Function(step, stepId) => newValue
+   * @returns {Array} Mapped values
+   * @throws {Error} If steps is not an array
+   */
+  static mapSteps(steps, callback) {
+    if (!Array.isArray(steps)) {
+      // Handle V2.0 object format for backwards compatibility during transition
+      if (steps && typeof steps === 'object') {
+        return Object.entries(steps).map(([stepId, step]) => callback(step, stepId));
+      }
+      throw new Error('[CookbookHelpers.mapSteps] steps must be an array (V2.1 format)');
+    }
+    
+    return steps.map(step => callback(step, step.step_id));
+  }
+
+  /**
+   * Get all step IDs in their defined order
+   * 
+   * @param {Array} steps - Array of step objects
+   * @returns {Array<string>} Array of step_ids in order
+   * @throws {Error} If steps is not an array
+   */
+  static getStepIds(steps) {
+    if (!Array.isArray(steps)) {
+      // Handle V2.0 object format for backwards compatibility during transition
+      if (steps && typeof steps === 'object') {
+        return Object.keys(steps);
+      }
+      throw new Error('[CookbookHelpers.getStepIds] steps must be an array (V2.1 format)');
+    }
+    
+    return steps.map(step => step.step_id);
+  }
+
+  /**
+   * Get the first step (for workflow initiation)
+   * 
+   * @param {Array} steps - Array of step objects
+   * @returns {Object|null} The first step or null if empty
+   * @throws {Error} If steps is not an array
+   */
+  static getFirstStep(steps) {
+    if (!Array.isArray(steps)) {
+      // Handle V2.0 object format for backwards compatibility during transition
+      if (steps && typeof steps === 'object') {
+        const keys = Object.keys(steps);
+        return keys.length > 0 ? steps[keys[0]] : null;
+      }
+      throw new Error('[CookbookHelpers.getFirstStep] steps must be an array (V2.1 format)');
+    }
+    
+    return steps.length > 0 ? steps[0] : null;
+  }
+
+  /**
+   * Get the next step after a given step_id
+   * 
+   * @param {Array} steps - Array of step objects
+   * @param {string} currentStepId - The current step_id
+   * @returns {Object|null} The next step or null if last/not found
+   * @throws {Error} If steps is not an array
+   */
+  static getNextStep(steps, currentStepId) {
+    if (!Array.isArray(steps)) {
+      // Handle V2.0 object format for backwards compatibility during transition
+      if (steps && typeof steps === 'object') {
+        const keys = Object.keys(steps);
+        const currentIndex = keys.indexOf(currentStepId);
+        if (currentIndex === -1 || currentIndex >= keys.length - 1) {
+          return null;
+        }
+        return steps[keys[currentIndex + 1]];
+      }
+      throw new Error('[CookbookHelpers.getNextStep] steps must be an array (V2.1 format)');
+    }
+    
+    const currentIndex = steps.findIndex(step => step.step_id === currentStepId);
+    if (currentIndex === -1 || currentIndex >= steps.length - 1) {
+      return null;
+    }
+    return steps[currentIndex + 1];
+  }
+
+  /**
+   * Get total step count
+   * 
+   * @param {Array} steps - Array of step objects
+   * @returns {number} Number of steps
+   */
+  static getStepCount(steps) {
+    if (!Array.isArray(steps)) {
+      // Handle V2.0 object format for backwards compatibility during transition
+      if (steps && typeof steps === 'object') {
+        return Object.keys(steps).length;
+      }
+      return 0;
+    }
+    
+    return steps.length;
+  }
+
+  /**
+   * Check if a step_id exists
+   * 
+   * @param {Array} steps - Array of step objects
+   * @param {string} stepId - The step_id to check
+   * @returns {boolean} True if step exists
+   */
+  static hasStep(steps, stepId) {
+    return this.findStep(steps, stepId) !== null;
+  }
+
+  /**
+   * Filter steps by a predicate
+   * 
+   * @param {Array} steps - Array of step objects
+   * @param {Function} predicate - Function(step, stepId) => boolean
+   * @returns {Array} Filtered steps
+   */
+  static filterSteps(steps, predicate) {
+    if (!Array.isArray(steps)) {
+      // Handle V2.0 object format for backwards compatibility during transition
+      if (steps && typeof steps === 'object') {
+        return Object.entries(steps)
+          .filter(([stepId, step]) => predicate(step, stepId))
+          .map(([_, step]) => step);
+      }
+      throw new Error('[CookbookHelpers.filterSteps] steps must be an array (V2.1 format)');
+    }
+    
+    return steps.filter(step => predicate(step, step.step_id));
+  }
+
+  /**
+   * Check if steps format is V2.1 (array)
+   * 
+   * @param {any} steps - Steps to check
+   * @returns {boolean} True if V2.1 array format
+   */
+  static isV21Format(steps) {
+    return Array.isArray(steps);
+  }
+
+  /**
+   * Check if steps format is V2.0 (object)
+   * 
+   * @param {any} steps - Steps to check
+   * @returns {boolean} True if V2.0 object format
+   */
+  static isV20Format(steps) {
+    return steps && typeof steps === 'object' && !Array.isArray(steps);
+  }
+
+  /**
+   * Convert V2.0 object format to V2.1 array format
+   * 
+   * @param {Object} stepsObject - V2.0 steps object
+   * @returns {Array} V2.1 steps array
+   */
+  static convertV20ToV21(stepsObject) {
+    if (Array.isArray(stepsObject)) {
+      return stepsObject; // Already V2.1
+    }
+    
+    if (!stepsObject || typeof stepsObject !== 'object') {
+      return [];
+    }
+    
+    return Object.entries(stepsObject).map(([stepId, step]) => ({
+      ...step,
+      step_id: step.step_id || stepId // Ensure step_id is set
+    }));
+  }
+}
+
+// Export both class and individual functions for convenience
+module.exports = {
+  CookbookHelpers,
+  findStep: CookbookHelpers.findStep.bind(CookbookHelpers),
+  forEachStep: CookbookHelpers.forEachStep.bind(CookbookHelpers),
+  mapSteps: CookbookHelpers.mapSteps.bind(CookbookHelpers),
+  getStepIds: CookbookHelpers.getStepIds.bind(CookbookHelpers),
+  getFirstStep: CookbookHelpers.getFirstStep.bind(CookbookHelpers),
+  getNextStep: CookbookHelpers.getNextStep.bind(CookbookHelpers),
+  getStepCount: CookbookHelpers.getStepCount.bind(CookbookHelpers),
+  hasStep: CookbookHelpers.hasStep.bind(CookbookHelpers),
+  filterSteps: CookbookHelpers.filterSteps.bind(CookbookHelpers),
+  isV21Format: CookbookHelpers.isV21Format.bind(CookbookHelpers),
+  isV20Format: CookbookHelpers.isV20Format.bind(CookbookHelpers),
+  convertV20ToV21: CookbookHelpers.convertV20ToV21.bind(CookbookHelpers)
+};

package/src/index.js

@@ -5,6 +5,11 @@
  *
  * Core cookbook parsing and validation library.
  * Lightweight foundation for workflow definitions - no heavy dependencies.
+ * 
+ * V2.1 FORMAT:
+ * - steps is an ARRAY (guaranteed order)
+ * - Access via step_id ONLY (use findStep, forEachStep)
+ * - Index access is FORBIDDEN
  */
 
 const {
@@ -33,6 +38,23 @@ const {
   validateErrorHandlerReferences
 } = require('./referenceValidator');
 
+// V2.1 Helper functions for safe step access
+const {
+  CookbookHelpers,
+  findStep,
+  forEachStep,
+  mapSteps,
+  getStepIds,
+  getFirstStep,
+  getNextStep,
+  getStepCount,
+  hasStep,
+  filterSteps,
+  isV21Format,
+  isV20Format,
+  convertV20ToV21
+} = require('./CookbookHelpers');
+
 module.exports = {
   // Parser functions
   parseCookbookFromFile,
@@ -58,7 +80,22 @@ module.exports = {
   // Error classes
   CookbookValidationError,
 
+  // V2.1 Helper class and functions
+  CookbookHelpers,
+  findStep,
+  forEachStep,
+  mapSteps,
+  getStepIds,
+  getFirstStep,
+  getNextStep,
+  getStepCount,
+  hasStep,
+  filterSteps,
+  isV21Format,
+  isV20Format,
+  convertV20ToV21,
+
   // Utility exports
-  VERSION: '2.0.0',
+  VERSION: '2.1.0',
   SCHEMA_VERSION: '2.1.0'
 };

package/src/parser/cookbookValidator.js

@@ -35,11 +35,11 @@ const loadSchemaFile = (filename) => {
   if (fs.existsSync(schemaPath)) {
     return JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
   }
-  // Fallback to default schema
-  return JSON.parse(fs.readFileSync(path.join(__dirname, '../../schemas/cookbook.schema.json'), 'utf-8'));
+  // Fallback to default v2 schema
+  return JSON.parse(fs.readFileSync(path.join(__dirname, '../../schemas/cookbook.v2.schema.json'), 'utf-8'));
 };
 
-const cookbookSchema = loadSchemaFile('cookbook.schema.json');
+const cookbookSchema = loadSchemaFile('cookbook.v2.schema.json');
 const strictSchema = loadSchemaFile('cookbook.strict.schema.json');
 const relaxedSchema = loadSchemaFile('cookbook.relaxed.schema.json');
 

package/src/parser/cookbookValidatorV2.js

@@ -29,18 +29,27 @@ class CookbookValidationError extends Error {
 }
 
 /**
- * Load V2 schema - V1 IS BANNED, only one schema exists
+ * Load V2.1 schema - V1 and V2.0 are BANNED
  */
-function loadSchema(version = '2.0') {
+function loadSchema(version = '2.1') {
   // V1 is BANNED - reject immediately
   if (version.startsWith('1.')) {
-    throw new CookbookValidationError('V1 FORMAT BANNED! Use version 2.x.x');
+    throw new CookbookValidationError(
+      'FAIL-FAST: V1 FORMAT BANNED! Use version 2.1.x with array steps.'
+    );
+  }
+  
+  // V2.0 is BANNED - reject immediately
+  if (version === '2.0') {
+    throw new CookbookValidationError(
+      'FAIL-FAST: V2.0 FORMAT BANNED! Use version 2.1.x with array steps (not object).'
+    );
   }
 
-  const schemaPath = path.join(__dirname, '../../schemas/cookbook.schema.json');
+  const schemaPath = path.join(__dirname, '../../schemas/cookbook.v2.schema.json');
 
   if (!fs.existsSync(schemaPath)) {
-    throw new CookbookValidationError('Schema file not found: cookbook.schema.json');
+    throw new CookbookValidationError('Schema file not found: cookbook.v2.schema.json');
   }
 
   return JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
@@ -113,30 +122,39 @@ function formatErrors(errors) {
 }
 
 /**
- * Detect cookbook version and suggest migration if needed
+ * Detect cookbook version
+ * 
+ * V1.x - BANNED (array steps with 'id')
+ * V2.0 - BANNED (object steps keyed by step_id)
+ * V2.1 - REQUIRED (array steps with 'step_id')
  */
 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';
+    const [major, minor] = cookbook.version.split('.').map(Number);
+    if (major === 1) return '1.0';
+    if (major === 2 && minor >= 1) return '2.1';
+    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';
+  // Auto-detect based on steps format
+  if (cookbook.steps) {
+    // V2.1: steps is array with step_id
+    if (Array.isArray(cookbook.steps)) {
+      const hasStepId = cookbook.steps.length === 0 || cookbook.steps.every(s => s.step_id);
+      const hasId = cookbook.steps.some(s => s.id && !s.step_id);
+      
+      if (hasId) return '1.0'; // V1 format (array with 'id')
+      if (hasStepId) return '2.1'; // V2.1 format (array with 'step_id')
+    }
+    // V2.0: steps is object
+    if (typeof cookbook.steps === 'object' && !Array.isArray(cookbook.steps)) {
+      return '2.0';
+    }
+  }
 
-  // Default to v2.0 for new cookbooks
-  return '2.0';
+  // Default to v2.1 for new cookbooks
+  return '2.1';
 }
 
 /**
@@ -179,6 +197,8 @@ function checkMigration(cookbook, detectedVersion) {
 /**
  * Main validation function
  *
+ * V2.1 ONLY - V1 and V2.0 are BANNED
+ * 
  * @param {object} cookbook - The cookbook object to validate
  * @param {object} options - Validation options
  * @param {string} options.version - Force specific version validation
@@ -196,11 +216,34 @@ function validateCookbook(cookbook, options = {}) {
   // Detect version if not specified
   const cookbookVersion = version || detectVersion(cookbook);
 
-  // Check if migration needed
+  // STRICT: Reject V1 and V2.0
+  if (cookbookVersion === '1.0') {
+    throw new CookbookValidationError(
+      'FAIL-FAST: V1 format (1.x.x) is BANNED. ' +
+      'Migrate to V2.1 format:\n' +
+      '  - Change version to "2.1.0"\n' +
+      '  - Keep steps as array\n' +
+      '  - Rename "id" to "step_id" in each step\n' +
+      '  - Access steps via findStep(stepId), not by index'
+    );
+  }
+  
+  if (cookbookVersion === '2.0') {
+    throw new CookbookValidationError(
+      'FAIL-FAST: V2.0 format (object steps) is BANNED. ' +
+      'Migrate to V2.1 format:\n' +
+      '  - Change version to "2.1.0"\n' +
+      '  - Convert steps from object to array\n' +
+      '  - Each step must have step_id property\n' +
+      '  - Access steps via findStep(stepId), not by key'
+    );
+  }
+
+  // Check if migration needed (for warnings)
   checkMigration(cookbook, cookbookVersion);
 
-  // Load appropriate schema
-  const schema = loadSchema(cookbookVersion);
+  // Load V2.1 schema
+  const schema = loadSchema('2.1');
 
   // Create validator
   const validate = createValidator(schema);
@@ -222,7 +265,7 @@ function validateCookbook(cookbook, options = {}) {
     }
   }
 
-  // Additional semantic validation (still using schema as source of truth)
+  // Additional semantic validation
   validateSemantics(cookbook, cookbookVersion);
 
   return true;
@@ -230,66 +273,108 @@ function validateCookbook(cookbook, options = {}) {
 
 /**
  * Semantic validation for things JSON Schema can't easily express
+ * 
+ * V2.1 REQUIREMENTS:
+ * - steps MUST be an array
+ * - Each step MUST have step_id
+ * - No index-based access allowed
  */
 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 - V2: all nested steps are objects keyed by step_id
-    if (step.steps && typeof step.steps === 'object') {
-      Object.entries(step.steps).forEach(([nestedKey, nested]) =>
-        checkStep(nested, `${path}.steps.${nestedKey}`)
+    // V2.1: step_id is REQUIRED
+    const stepId = step.step_id;
+    if (!stepId) {
+      throw new CookbookValidationError(
+        `Missing required 'step_id' at ${path}. V2.1 requires step_id for all steps.`
       );
     }
-    if (step.body && typeof step.body === 'object') {
-      Object.entries(step.body).forEach(([nestedKey, nested]) =>
-        checkStep(nested, `${path}.body.${nestedKey}`)
+    
+    if (stepIds.has(stepId)) {
+      throw new CookbookValidationError(
+        `Duplicate step_id '${stepId}' found at ${path}`
       );
     }
-    if (step.branches && typeof step.branches === 'object') {
-      Object.entries(step.branches).forEach(([branchKey, branch]) => {
-        checkStep(branch, `${path}.branches.${branchKey}`);
-      });
+    stepIds.add(stepId);
+
+    // Check nested steps - V2.1: nested steps are also arrays
+    if (step.steps) {
+      if (Array.isArray(step.steps)) {
+        step.steps.forEach((nested, idx) =>
+          checkStep(nested, `${path}.steps[${idx}]`)
+        );
+      } else if (typeof step.steps === 'object') {
+        // Allow object format for nested steps (backwards compat during transition)
+        Object.entries(step.steps).forEach(([nestedKey, nested]) =>
+          checkStep(nested, `${path}.steps.${nestedKey}`)
+        );
+      }
+    }
+    
+    if (step.body) {
+      if (Array.isArray(step.body)) {
+        step.body.forEach((nested, idx) =>
+          checkStep(nested, `${path}.body[${idx}]`)
+        );
+      } else if (typeof step.body === 'object') {
+        Object.entries(step.body).forEach(([nestedKey, nested]) =>
+          checkStep(nested, `${path}.body.${nestedKey}`)
+        );
+      }
     }
+    
+    if (step.branches) {
+      if (Array.isArray(step.branches)) {
+        step.branches.forEach((branch, idx) => {
+          if (branch.steps) {
+            if (Array.isArray(branch.steps)) {
+              branch.steps.forEach((nested, nidx) =>
+                checkStep(nested, `${path}.branches[${idx}].steps[${nidx}]`)
+              );
+            }
+          }
+        });
+      } else if (typeof step.branches === 'object') {
+        Object.entries(step.branches).forEach(([branchKey, branch]) => {
+          checkStep(branch, `${path}.branches.${branchKey}`);
+        });
+      }
+    }
+    
     if (step.cases) {
       Object.keys(step.cases).forEach(caseKey => {
         const caseVal = step.cases[caseKey];
-        checkStep(caseVal, `${path}.cases.${caseKey}`);
+        if (caseVal && typeof caseVal === 'object') {
+          checkStep(caseVal, `${path}.cases.${caseKey}`);
+        }
       });
     }
   }
 
-  // Check all steps - V2: steps is an OBJECT keyed by step_id, NOT an array
+  // V2.1: steps MUST be an array
   if (cookbook.steps) {
-    if (Array.isArray(cookbook.steps)) {
-      throw new CookbookValidationError('V1 FORMAT BANNED! steps must be an object keyed by step_id, not an array');
+    if (!Array.isArray(cookbook.steps)) {
+      throw new CookbookValidationError(
+        'FAIL-FAST: V2.0 format (object steps) is DEPRECATED. ' +
+        'Use V2.1 format with steps as an ARRAY. ' +
+        'Each step must have step_id. Access steps via findStep(stepId), not by index.'
+      );
     }
-    Object.entries(cookbook.steps).forEach(([stepKey, step]) =>
-      checkStep(step, `steps.${stepKey}`)
+    
+    cookbook.steps.forEach((step, idx) =>
+      checkStep(step, `steps[${idx}]`)
     );
   }
 
   // Check dependencies exist
-  if (version === '2.0' && cookbook.steps) {
-    Object.entries(cookbook.steps).forEach(([stepKey, step]) => {
+  if (cookbook.steps && Array.isArray(cookbook.steps)) {
+    cookbook.steps.forEach((step) => {
       if (step.depends_on) {
         step.depends_on.forEach(dep => {
           if (!stepIds.has(dep)) {
             throw new CookbookValidationError(
-              `Step '${stepKey}' depends on non-existent step_id '${dep}'`
+              `Step '${step.step_id}' depends on non-existent step_id '${dep}'`
             );
           }
         });

package/src/schema.js

@@ -22,15 +22,15 @@ function loadSchema(mode = 'default') {
       schemaFile = 'cookbook.relaxed.schema.json';
       break;
     default:
-      schemaFile = 'cookbook.schema.json';
+      schemaFile = 'cookbook.v2.schema.json';
   }
 
   const schemaPath = path.join(__dirname, '../schemas', schemaFile);
 
   // Check if file exists
   if (!fs.existsSync(schemaPath)) {
-    // Fall back to default schema
-    const defaultPath = path.join(__dirname, '../schemas/cookbook.schema.json');
+    // Fall back to default v2 schema
+    const defaultPath = path.join(__dirname, '../schemas/cookbook.v2.schema.json');
     return JSON.parse(fs.readFileSync(defaultPath, 'utf-8'));
   }