@entergreat/step-pipeline 1.1.0

package/.npmrc.example

@@ -0,0 +1,5 @@
+# NPM Registry Configuration
+# For private packages, add your auth token:
+# //registry.npmjs.org/:_authToken=${NPM_TOKEN}
+
+registry=https://registry.npmjs.org/

package/README.md

@@ -0,0 +1,496 @@
+# @entergreat/step-pipeline
+
+Reusable step-based pipeline framework for EnterGreat services. Build robust, resumable, and maintainable data processing pipelines with ease.
+
+## Features
+
+- ✅ **Step-based architecture** - Break complex workflows into manageable steps
+- 🔄 **Resume capability** - Start from any step in the pipeline
+- 🔁 **Automatic retries** - Configure retries per step
+- ⏱️ **Timeout support** - Set execution timeouts for steps
+- 📊 **Built-in metrics** - Track execution time and success rates
+- 🎯 **Conditional execution** - Execute steps based on conditions
+- 🔌 **Event system** - Hook into step lifecycle events
+- 📝 **Comprehensive logging** - Configurable log levels
+- 🛡️ **Error handling** - Graceful error handling with detailed reporting
+
+## Installation
+
+```bash
+npm install @entergreat/step-pipeline
+```
+
+## Quick Start
+
+```javascript
+import { StepPipeline, StepDefinition } from '@entergreat/step-pipeline';
+
+// Create a pipeline
+const pipeline = new StepPipeline();
+
+// Define your steps
+const steps = [
+  new StepDefinition(
+    0,
+    'Load Data',
+    'Load data from source',
+    async (context) => {
+      // Your logic here
+      return { data: 'loaded' };
+    }
+  ),
+  new StepDefinition(
+    1,
+    'Process Data',
+    'Process the loaded data',
+    async (context) => {
+      // Your logic here
+      return { processed: true };
+    }
+  ),
+  new StepDefinition(
+    2,
+    'Save Results',
+    'Save processed results',
+    async (context) => {
+      // Your logic here
+      return { saved: true };
+    }
+  )
+];
+
+// Register steps
+pipeline.registerSteps(steps);
+
+// Execute the pipeline
+const context = { userId: '123', timestamp: Date.now() };
+const results = await pipeline.executeAll(context);
+
+// Print summary
+pipeline.printSummary(results);
+```
+
+## Core Concepts
+
+### StepDefinition
+
+Defines a single step in your pipeline:
+
+```javascript
+new StepDefinition(
+  id,              // Unique step ID (number)
+  name,            // Display name (string)
+  description,     // What this step does (string)
+  handler,         // Async function to execute (async function)
+  options          // Optional configuration (object)
+)
+```
+
+### StepPipeline
+
+Main class for managing and executing pipelines:
+
+```javascript
+const pipeline = new StepPipeline({
+  logLevel: 'info',        // 'error', 'warn', 'info', 'debug'
+  stopOnError: true,       // Stop pipeline on step failure
+  enableMetrics: true      // Track execution metrics
+});
+```
+
+### Context
+
+Data object that flows through all steps:
+
+```javascript
+const context = {
+  // Your custom data
+  userId: '123',
+  input: 'some data',
+  // Context is mutable and can be updated by steps
+};
+```
+
+## API Reference
+
+### StepPipeline Methods
+
+#### `registerSteps(stepDefinitions)`
+Register multiple steps at once.
+
+```javascript
+pipeline.registerSteps([step1, step2, step3]);
+```
+
+#### `executeAll(context, startStep?)`
+Execute all registered steps from start to end.
+
+```javascript
+// Execute all steps
+await pipeline.executeAll(context);
+
+// Resume from step 5
+await pipeline.executeAll(context, 5);
+```
+
+#### `executeStep(stepId, context, skip?)`
+Execute a single step by ID.
+
+```javascript
+const result = await pipeline.executeStep(2, context);
+```
+
+#### `executeRange(startStep, endStep, context)`
+Execute a specific range of steps.
+
+```javascript
+// Execute steps 2 through 5
+await pipeline.executeRange(2, 5, context);
+```
+
+#### `executeSteps(stepIds, context)`
+Execute only specific steps by IDs.
+
+```javascript
+// Execute only steps 1, 3, and 5
+await pipeline.executeSteps([1, 3, 5], context);
+```
+
+#### `listSteps()`
+Get a list of all registered steps.
+
+```javascript
+const steps = pipeline.listSteps();
+// Returns: [{ id, name, description, options }, ...]
+```
+
+#### `getStepCount()`
+Get the total number of registered steps.
+
+```javascript
+const count = pipeline.getStepCount();
+```
+
+#### `getSummary(results)`
+Get execution summary with statistics.
+
+```javascript
+const summary = pipeline.getSummary(results);
+// Returns: { total, successful, failed, skipped, successRate, totalDuration }
+```
+
+#### `printSummary(results)`
+Print formatted execution summary to console.
+
+```javascript
+pipeline.printSummary(results);
+```
+
+### Step Options
+
+Configure individual steps with advanced options:
+
+```javascript
+new StepDefinition(
+  5,
+  'Flaky API Call',
+  'Call external API with retries',
+  handler,
+  {
+    retries: 3,              // Retry 3 times on failure
+    retryDelay: 1000,        // Wait 1s between retries
+    timeout: 30000,          // Timeout after 30s
+    skip: false,             // Skip this step
+    condition: (context) => context.shouldRun  // Conditional execution
+  }
+)
+```
+
+### Event System
+
+Hook into pipeline lifecycle events:
+
+```javascript
+pipeline
+  .on('stepStart', (stepId, stepName, context) => {
+    console.log(`Starting ${stepName}...`);
+  })
+  .on('stepComplete', (stepId, stepName, result, duration) => {
+    console.log(`Completed ${stepName} in ${duration}s`);
+  })
+  .on('stepError', (stepId, stepName, error, duration) => {
+    console.error(`Failed ${stepName}: ${error.message}`);
+  })
+  .on('stepSkipped', (stepId, stepName) => {
+    console.log(`Skipped ${stepName}`);
+  })
+  .on('sequenceStart', (startId, endId, context) => {
+    console.log(`Starting sequence ${startId} to ${endId}`);
+  })
+  .on('sequenceComplete', (results) => {
+    console.log(`Sequence completed with ${results.length} steps`);
+  });
+```
+
+## Usage Examples
+
+### Example 1: Basic Pipeline
+
+```javascript
+import { StepPipeline, StepDefinition } from '@entergreat/step-pipeline';
+
+class DataProcessor {
+  constructor() {
+    this.pipeline = new StepPipeline();
+    this.registerSteps();
+  }
+
+  registerSteps() {
+    const steps = [
+      new StepDefinition(0, 'Validate Input', 'Validate input data', this.validate.bind(this)),
+      new StepDefinition(1, 'Transform Data', 'Transform to required format', this.transform.bind(this)),
+      new StepDefinition(2, 'Save Results', 'Save to database', this.save.bind(this))
+    ];
+
+    this.pipeline.registerSteps(steps);
+  }
+
+  async validate(context) {
+    if (!context.data) throw new Error('No data provided');
+    return { valid: true };
+  }
+
+  async transform(context) {
+    context.transformed = context.data.toUpperCase();
+    return { transformed: true };
+  }
+
+  async save(context) {
+    // Save to database
+    return { saved: true };
+  }
+
+  async process(data) {
+    const context = { data, timestamp: Date.now() };
+    const results = await this.pipeline.executeAll(context);
+    return this.pipeline.getSummary(results);
+  }
+}
+
+// Usage
+const processor = new DataProcessor();
+const summary = await processor.process('hello world');
+```
+
+### Example 2: With Retries and Timeouts
+
+```javascript
+const pipeline = new StepPipeline();
+
+const steps = [
+  new StepDefinition(
+    0,
+    'Fetch Data',
+    'Fetch from external API',
+    async (context) => {
+      const response = await fetch(context.url);
+      return await response.json();
+    },
+    {
+      retries: 3,
+      retryDelay: 2000,
+      timeout: 10000
+    }
+  )
+];
+
+pipeline.registerSteps(steps);
+```
+
+### Example 3: Conditional Execution
+
+```javascript
+const steps = [
+  new StepDefinition(
+    0,
+    'Optional Enhancement',
+    'Run only if premium user',
+    async (context) => {
+      // Enhancement logic
+      return { enhanced: true };
+    },
+    {
+      condition: (context) => context.user.isPremium
+    }
+  )
+];
+```
+
+### Example 4: Resume from Checkpoint
+
+```javascript
+// First run - fails at step 5
+try {
+  await pipeline.executeAll(context);
+} catch (error) {
+  console.error('Pipeline failed at step 5');
+}
+
+// Resume from step 5 after fixing the issue
+const results = await pipeline.executeAll(context, 5);
+```
+
+### Example 5: With Event Tracking
+
+```javascript
+const pipeline = new StepPipeline();
+
+// Track metrics
+const metrics = {
+  stepsExecuted: 0,
+  totalDuration: 0,
+  errors: []
+};
+
+pipeline
+  .on('stepComplete', (stepId, stepName, result, duration) => {
+    metrics.stepsExecuted++;
+    metrics.totalDuration += parseFloat(duration);
+  })
+  .on('stepError', (stepId, stepName, error) => {
+    metrics.errors.push({ stepId, stepName, error: error.message });
+  });
+
+await pipeline.executeAll(context);
+console.log('Metrics:', metrics);
+```
+
+## Integration with EnterGreat Services
+
+### Before (without package)
+
+```javascript
+// Each service had duplicate code
+import { StepRegistry, StepDefinition } from './core/StepRegistry.js';
+import { StepExecutor } from './core/StepExecutor.js';
+
+export class StepService {
+  constructor() {
+    this.registry = new StepRegistry();
+    this.executor = new StepExecutor(this.registry);
+    this.registerSteps();
+  }
+
+  async executeAll(context, startStep = 0) {
+    const endStep = 8; // Hardcoded
+    return await this.executor.executeSequence(startStep, endStep, context);
+  }
+
+  // More duplicate code...
+}
+```
+
+### After (with package)
+
+```javascript
+import { StepPipeline, StepDefinition } from '@entergreat/step-pipeline';
+
+export class StepService {
+  constructor() {
+    // One line instead of multiple!
+    this.pipeline = new StepPipeline();
+    this.registerSteps();
+  }
+
+  async executeAll(context, startStep = 0) {
+    // Uses the package's built-in method
+    return await this.pipeline.executeAll(context, startStep);
+  }
+
+  listSteps() {
+    // Uses the package's built-in method
+    return this.pipeline.listSteps();
+  }
+}
+```
+
+## Advanced Features
+
+### Custom Logging
+
+```javascript
+const pipeline = new StepPipeline({
+  logLevel: 'debug'  // Show all logs including debug messages
+});
+```
+
+### Stop on Error
+
+```javascript
+const pipeline = new StepPipeline({
+  stopOnError: false  // Continue even if steps fail
+});
+```
+
+### Heartbeat Messages
+
+Useful for long-running steps:
+
+```javascript
+async longRunningStep(context) {
+  for (let i = 0; i < 100; i++) {
+    if (i % 10 === 0) {
+      this.pipeline.heartbeat(`Processing item ${i}/100`);
+    }
+    await processItem(i);
+  }
+}
+```
+
+## Testing
+
+```javascript
+import { StepPipeline, StepDefinition } from '@entergreat/step-pipeline';
+
+describe('My Pipeline', () => {
+  it('should execute all steps successfully', async () => {
+    const pipeline = new StepPipeline();
+    const steps = [
+      new StepDefinition(0, 'Test Step', 'Test', async () => ({ success: true }))
+    ];
+
+    pipeline.registerSteps(steps);
+    const results = await pipeline.executeAll({});
+
+    expect(results[0].success).toBe(true);
+  });
+});
+```
+
+## Best Practices
+
+1. **Use descriptive names** - Make step names and descriptions clear
+2. **Keep steps focused** - Each step should do one thing well
+3. **Handle errors gracefully** - Return meaningful error messages
+4. **Use context wisely** - Don't mutate context unnecessarily
+5. **Log important events** - Use heartbeat for long-running operations
+6. **Test steps independently** - Unit test each step handler
+7. **Use retries for flaky operations** - Network calls, external APIs
+8. **Set appropriate timeouts** - Prevent hanging operations
+
+## Migration Guide
+
+See [MIGRATION.md](./MIGRATION.md) for detailed migration instructions from local implementations.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+## Support
+
+- GitHub Issues: [Create an issue](https://github.com/entergreat/step-pipeline/issues)
+- Email: support@entergreat.com

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@entergreat/step-pipeline",
+  "version": "1.1.0",
+  "description": "Reusable step-based pipeline framework for EnterGreat services",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "pipeline",
+    "steps",
+    "workflow",
+    "orchestration",
+    "entergreat"
+  ],
+  "author": "EnterGreat",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/entergreat/step-pipeline.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/core/StepDefinition.js

@@ -0,0 +1,158 @@
+/**
+ * Represents a single step in the pipeline
+ * Supports both numeric IDs (legacy) and string IDs (recommended)
+ */
+export class StepDefinition {
+  constructor(id, name, description, handler, options = {}) {
+    this.id = id;
+    this.name = name;
+    this.description = description;
+    this.handler = handler;
+    this.options = {
+      // Execution options
+      skip: options.skip || false,
+      retries: options.retries || 0,
+      retryDelay: options.retryDelay || 1000,
+      timeout: options.timeout || null,
+      condition: options.condition || null,
+
+      // Message options
+      startMessage: options.startMessage || `Starting ${name}...`,
+      successMessage: options.successMessage || `${name} completed successfully`,
+      errorMessage: options.errorMessage || `${name} failed`,
+
+      // Organization options
+      phase: options.phase || null,
+      tags: options.tags || [],
+
+      // Dependencies
+      dependsOn: options.dependsOn || [],
+
+      ...options
+    };
+  }
+
+  /**
+   * Check if this step should be executed based on condition
+   */
+  shouldExecute(context) {
+    if (typeof this.options.condition === 'function') {
+      return this.options.condition(context);
+    }
+    return !this.options.skip;
+  }
+
+  /**
+   * Get formatted start message with context interpolation
+   */
+  getStartMessage(context = {}) {
+    return this._interpolate(this.options.startMessage, context);
+  }
+
+  /**
+   * Get formatted success message with context interpolation
+   */
+  getSuccessMessage(context = {}, result = {}) {
+    return this._interpolate(this.options.successMessage, { ...context, ...result });
+  }
+
+  /**
+   * Get formatted error message with context interpolation
+   */
+  getErrorMessage(context = {}, error = {}) {
+    return this._interpolate(this.options.errorMessage, { ...context, error: error.message });
+  }
+
+  /**
+   * Interpolate variables in message templates
+   * Example: "Processing {count} items" -> "Processing 5 items"
+   */
+  _interpolate(template, data) {
+    if (!template) return '';
+    return template.replace(/\{(\w+)\}/g, (match, key) => {
+      return data[key] !== undefined ? data[key] : match;
+    });
+  }
+}
+
+/**
+ * Builder class for creating step definitions with a fluent API
+ */
+export class StepBuilder {
+  constructor(id, name) {
+    this.id = id;
+    this.name = name;
+    this._description = '';
+    this._handler = null;
+    this._options = {};
+  }
+
+  description(desc) {
+    this._description = desc;
+    return this;
+  }
+
+  handler(fn) {
+    this._handler = fn;
+    return this;
+  }
+
+  startMessage(msg) {
+    this._options.startMessage = msg;
+    return this;
+  }
+
+  successMessage(msg) {
+    this._options.successMessage = msg;
+    return this;
+  }
+
+  errorMessage(msg) {
+    this._options.errorMessage = msg;
+    return this;
+  }
+
+  retries(count, delay = 1000) {
+    this._options.retries = count;
+    this._options.retryDelay = delay;
+    return this;
+  }
+
+  timeout(ms) {
+    this._options.timeout = ms;
+    return this;
+  }
+
+  condition(fn) {
+    this._options.condition = fn;
+    return this;
+  }
+
+  phase(phaseName) {
+    this._options.phase = phaseName;
+    return this;
+  }
+
+  tags(...tags) {
+    this._options.tags = tags;
+    return this;
+  }
+
+  dependsOn(...stepIds) {
+    this._options.dependsOn = stepIds;
+    return this;
+  }
+
+  build() {
+    if (!this._handler) {
+      throw new Error(`Step ${this.id}: handler is required`);
+    }
+    return new StepDefinition(
+      this.id,
+      this.name,
+      this._description,
+      this._handler,
+      this._options
+    );
+  }
+}

package/src/core/StepExecutor.js

@@ -0,0 +1,237 @@
+/**
+ * Executes pipeline steps with logging, error handling, and retries
+ */
+export class StepExecutor {
+  constructor(registry, options = {}) {
+    this.registry = registry;
+    this.options = {
+      logLevel: options.logLevel || 'info',
+      stopOnError: options.stopOnError !== false,
+      enableMetrics: options.enableMetrics || false,
+      ...options
+    };
+    this.eventHandlers = new Map();
+  }
+
+  /**
+   * Register an event handler
+   */
+  on(event, handler) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, []);
+    }
+    this.eventHandlers.get(event).push(handler);
+    return this;
+  }
+
+  /**
+   * Emit an event
+   */
+  emit(event, ...args) {
+    const handlers = this.eventHandlers.get(event) || [];
+    handlers.forEach(handler => {
+      try {
+        handler(...args);
+      } catch (error) {
+        console.error(`Error in event handler for ${event}:`, error);
+      }
+    });
+  }
+
+  /**
+   * Execute a single step
+   */
+  async execute(stepId, context, skip = false) {
+    const step = this.registry.get(stepId);
+
+    this.log('info', `\n${'='.repeat(60)}`);
+    this.log('info', `Step ${stepId}: ${step.name}`);
+    this.log('info', `Description: ${step.description}`);
+    this.log('info', '='.repeat(60));
+
+    // Check if step should be skipped
+    if (skip || !step.shouldExecute(context)) {
+      this.log('info', `⏭️  Skipping step ${stepId}...`);
+      this.emit('stepSkipped', stepId, step.name);
+      return { skipped: true, stepId, stepName: step.name };
+    }
+
+    const startTime = Date.now();
+    let lastError = null;
+    const maxAttempts = step.options.retries + 1;
+
+    // Emit step start event
+    this.emit('stepStart', stepId, step.name, context);
+
+    // Retry logic
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        if (attempt > 1) {
+          this.log('warn', `🔄 Retry attempt ${attempt}/${maxAttempts} for step ${stepId}`);
+          await this.sleep(step.options.retryDelay);
+        }
+
+        // Use custom start message from step definition
+        const startMessage = step.getStartMessage(context);
+        this.log('info', `🚀 ${startMessage}`);
+
+        // Execute with timeout if specified
+        const result = step.options.timeout
+          ? await this.executeWithTimeout(step.handler, context, step.options.timeout)
+          : await step.handler(context);
+
+        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+
+        // Use custom success message from step definition
+        const successMessage = step.getSuccessMessage(context, result);
+        this.log('info', `✅ ${successMessage} (${duration}s)`);
+
+        // Emit step complete event
+        this.emit('stepComplete', stepId, step.name, result, duration);
+
+        return {
+          success: true,
+          stepId,
+          stepName: step.name,
+          duration,
+          result,
+          attempts: attempt
+        };
+      } catch (error) {
+        lastError = error;
+        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+
+        if (attempt < maxAttempts) {
+          this.log('warn', `⚠️  Step ${stepId} failed (attempt ${attempt}/${maxAttempts})`);
+          this.log('warn', `Error: ${error.message}`);
+        } else {
+          // Use custom error message from step definition
+          const errorMessage = step.getErrorMessage(context, error);
+          this.log('error', `❌ ${errorMessage} after ${duration}s and ${attempt} attempt(s)`);
+
+          // Emit step error event
+          this.emit('stepError', stepId, step.name, error, duration);
+
+          return {
+            success: false,
+            stepId,
+            stepName: step.name,
+            duration,
+            error: error.message,
+            stack: error.stack,
+            attempts: attempt
+          };
+        }
+      }
+    }
+
+    // This should never be reached, but just in case
+    const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+    return {
+      success: false,
+      stepId,
+      stepName: step.name,
+      duration,
+      error: lastError?.message || 'Unknown error',
+      attempts: maxAttempts
+    };
+  }
+
+  /**
+   * Execute a sequence of steps
+   * Supports both numeric sequences (0, 1, 2) and string ID ranges
+   */
+  async executeSequence(startStepId, endStepId, context) {
+    const results = [];
+
+    this.log('info', `\n${'*'.repeat(60)}`);
+    this.log('info', `Starting execution from step ${startStepId} to ${endStepId}`);
+    this.log('info', `${'*'.repeat(60)}\n`);
+
+    // Emit sequence start event
+    this.emit('sequenceStart', startStepId, endStepId, context);
+
+    // Get all step IDs in order
+    const allStepIds = this.registry.getStepIds();
+
+    // Find the start and end indices
+    const startIndex = allStepIds.indexOf(startStepId);
+    const endIndex = endStepId ? allStepIds.indexOf(endStepId) : allStepIds.length - 1;
+
+    if (startIndex === -1) {
+      throw new Error(`Start step ${startStepId} not found in registry`);
+    }
+
+    if (endIndex === -1 && endStepId) {
+      throw new Error(`End step ${endStepId} not found in registry`);
+    }
+
+    // Execute steps in range
+    for (let i = startIndex; i <= endIndex; i++) {
+      const stepId = allStepIds[i];
+
+      const result = await this.execute(stepId, context);
+      results.push(result);
+
+      // Stop execution if step failed and stopOnError is true
+      if (!result.success && !result.skipped && this.options.stopOnError) {
+        this.log('error', `\n❌ Execution stopped at step ${stepId} due to error`);
+        break;
+      }
+    }
+
+    this.log('info', `\n${'*'.repeat(60)}`);
+    this.log('info', `Execution completed`);
+    this.log('info', `${'*'.repeat(60)}\n`);
+
+    // Emit sequence complete event
+    this.emit('sequenceComplete', results);
+
+    return results;
+  }
+
+  /**
+   * Execute handler with timeout
+   */
+  async executeWithTimeout(handler, context, timeout) {
+    return Promise.race([
+      handler(context),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(`Step timeout after ${timeout}ms`)), timeout)
+      )
+    ]);
+  }
+
+  /**
+   * Sleep utility for retry delays
+   */
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Print a heartbeat message
+   */
+  printHeartbeat(message) {
+    this.log('info', `💓 ${message}`);
+  }
+
+  /**
+   * Log a message based on log level
+   */
+  log(level, message) {
+    const levels = { error: 0, warn: 1, info: 2, debug: 3 };
+    const currentLevel = levels[this.options.logLevel] || 2;
+    const messageLevel = levels[level] || 2;
+
+    if (messageLevel <= currentLevel) {
+      if (level === 'error') {
+        console.error(message);
+      } else if (level === 'warn') {
+        console.warn(message);
+      } else {
+        console.log(message);
+      }
+    }
+  }
+}

package/src/core/StepPipeline.js

@@ -0,0 +1,178 @@
+import { StepRegistry } from './StepRegistry.js';
+import { StepExecutor } from './StepExecutor.js';
+
+/**
+ * High-level API for managing and executing step-based pipelines
+ * This is the main class that services will use
+ */
+export class StepPipeline {
+  constructor(options = {}) {
+    this.registry = new StepRegistry();
+    this.executor = new StepExecutor(this.registry, options);
+    this.options = options;
+  }
+
+  /**
+   * Register steps (convenience method)
+   */
+  registerSteps(stepDefinitions) {
+    this.registry.registerMany(stepDefinitions);
+    return this;
+  }
+
+  /**
+   * Execute a single step by ID
+   */
+  async executeStep(stepId, context, skip = false) {
+    return await this.executor.execute(stepId, context, skip);
+  }
+
+  /**
+   * Execute all registered steps
+   */
+  async executeAll(context, startStep = null) {
+    const firstStep = startStep !== null ? startStep : this.registry.getFirstStepId();
+    const lastStep = this.registry.getLastStepId();
+
+    if (firstStep === -1 || lastStep === -1) {
+      throw new Error('No steps registered in pipeline');
+    }
+
+    return await this.executor.executeSequence(firstStep, lastStep, context);
+  }
+
+  /**
+   * Execute a range of steps
+   */
+  async executeRange(startStep, endStep, context) {
+    return await this.executor.executeSequence(startStep, endStep, context);
+  }
+
+  /**
+   * Execute only specific steps by IDs
+   */
+  async executeSteps(stepIds, context) {
+    const results = [];
+
+    for (const stepId of stepIds) {
+      if (!this.registry.has(stepId)) {
+        console.warn(`⚠️  Step ${stepId} not found, skipping...`);
+        continue;
+      }
+
+      const result = await this.executor.execute(stepId, context);
+      results.push(result);
+
+      // Stop if step failed and stopOnError is enabled
+      if (!result.success && !result.skipped && this.executor.options.stopOnError) {
+        break;
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * List all registered steps
+   */
+  listSteps() {
+    return this.registry.getAll().map(step => ({
+      id: step.id,
+      name: step.name,
+      description: step.description,
+      options: step.options
+    }));
+  }
+
+  /**
+   * Get a specific step definition
+   */
+  getStep(stepId) {
+    return this.registry.get(stepId);
+  }
+
+  /**
+   * Check if a step exists
+   */
+  hasStep(stepId) {
+    return this.registry.has(stepId);
+  }
+
+  /**
+   * Get total number of steps
+   */
+  getStepCount() {
+    return this.registry.count();
+  }
+
+  /**
+   * Get the first step ID
+   */
+  getFirstStepId() {
+    return this.registry.getFirstStepId();
+  }
+
+  /**
+   * Get the last step ID
+   */
+  getLastStepId() {
+    return this.registry.getLastStepId();
+  }
+
+  /**
+   * Register event handlers
+   */
+  on(event, handler) {
+    this.executor.on(event, handler);
+    return this;
+  }
+
+  /**
+   * Print a heartbeat message (useful for long-running steps)
+   */
+  heartbeat(message) {
+    this.executor.printHeartbeat(message);
+  }
+
+  /**
+   * Get execution summary from results
+   */
+  getSummary(results) {
+    const successful = results.filter(r => r.success).length;
+    const failed = results.filter(r => !r.success && !r.skipped).length;
+    const skipped = results.filter(r => r.skipped).length;
+    const totalDuration = results.reduce((sum, r) => {
+      return sum + (parseFloat(r.duration) || 0);
+    }, 0);
+
+    return {
+      total: results.length,
+      successful,
+      failed,
+      skipped,
+      successRate: results.length > 0 ? (successful / results.length * 100).toFixed(2) : 0,
+      totalDuration: totalDuration.toFixed(2),
+      results
+    };
+  }
+
+  /**
+   * Print execution summary
+   */
+  printSummary(results) {
+    const summary = this.getSummary(results);
+
+    console.log('\n' + '='.repeat(60));
+    console.log('📊 Execution Summary');
+    console.log('='.repeat(60));
+    console.log(`Total Steps: ${summary.total}`);
+    console.log(`✅ Successful: ${summary.successful}`);
+    console.log(`❌ Failed: ${summary.failed}`);
+    console.log(`⏭️  Skipped: ${summary.skipped}`);
+    console.log(`Success Rate: ${summary.successRate}%`);
+    console.log(`Total Duration: ${summary.totalDuration}s`);
+    console.log('='.repeat(60) + '\n');
+
+    return summary;
+  }
+}

package/src/core/StepRegistry.js

@@ -0,0 +1,124 @@
+import { StepDefinition } from './StepDefinition.js';
+
+/**
+ * Registry for managing step definitions
+ */
+export class StepRegistry {
+  constructor() {
+    this.steps = new Map();
+  }
+
+  /**
+   * Register a new step
+   */
+  register(stepDefinition) {
+    if (!(stepDefinition instanceof StepDefinition)) {
+      throw new Error('Invalid step definition');
+    }
+    this.steps.set(stepDefinition.id, stepDefinition);
+    return this;
+  }
+
+  /**
+   * Register multiple steps at once
+   */
+  registerMany(stepDefinitions) {
+    stepDefinitions.forEach(step => this.register(step));
+    return this;
+  }
+
+  /**
+   * Get a step by ID
+   */
+  get(stepId) {
+    const step = this.steps.get(stepId);
+    if (!step) {
+      throw new Error(`Step ${stepId} not found in registry`);
+    }
+    return step;
+  }
+
+  /**
+   * Get all registered steps
+   * Sorts by numeric ID if all IDs are numbers, otherwise maintains insertion order
+   */
+  getAll() {
+    const steps = Array.from(this.steps.values());
+
+    // Check if all IDs are numeric
+    const allNumeric = steps.every(step => typeof step.id === 'number');
+
+    if (allNumeric) {
+      return steps.sort((a, b) => a.id - b.id);
+    }
+
+    // For string IDs, maintain insertion order (Map preserves insertion order)
+    return steps;
+  }
+
+  /**
+   * Check if a step exists
+   */
+  has(stepId) {
+    return this.steps.has(stepId);
+  }
+
+  /**
+   * Get total number of steps
+   */
+  count() {
+    return this.steps.size;
+  }
+
+  /**
+   * Get the last step ID
+   */
+  getLastStepId() {
+    const steps = this.getAll();
+    return steps.length > 0 ? steps[steps.length - 1].id : null;
+  }
+
+  /**
+   * Get the first step ID
+   */
+  getFirstStepId() {
+    const steps = this.getAll();
+    return steps.length > 0 ? steps[0].id : null;
+  }
+
+  /**
+   * Get steps by phase
+   */
+  getByPhase(phase) {
+    return this.getAll().filter(step => step.options.phase === phase);
+  }
+
+  /**
+   * Get steps by tag
+   */
+  getByTag(tag) {
+    return this.getAll().filter(step => step.options.tags.includes(tag));
+  }
+
+  /**
+   * Get step IDs in order
+   */
+  getStepIds() {
+    return this.getAll().map(step => step.id);
+  }
+
+  /**
+   * Clear all steps
+   */
+  clear() {
+    this.steps.clear();
+    return this;
+  }
+
+  /**
+   * Remove a specific step
+   */
+  remove(stepId) {
+    return this.steps.delete(stepId);
+  }
+}

package/src/index.js

@@ -0,0 +1,31 @@
+/**
+ * @entergreat/step-pipeline
+ *
+ * Reusable step-based pipeline framework for EnterGreat services
+ */
+
+import { StepDefinition, StepBuilder } from './core/StepDefinition.js';
+import { StepRegistry } from './core/StepRegistry.js';
+import { StepExecutor } from './core/StepExecutor.js';
+import { StepPipeline } from './core/StepPipeline.js';
+import { createStepsFromConfig } from './utils/helpers.js';
+
+// Named exports
+export {
+  StepDefinition,
+  StepBuilder,
+  StepRegistry,
+  StepExecutor,
+  StepPipeline,
+  createStepsFromConfig
+};
+
+// Default export
+export default {
+  StepDefinition,
+  StepBuilder,
+  StepRegistry,
+  StepExecutor,
+  StepPipeline,
+  createStepsFromConfig
+};

package/src/utils/helpers.js

@@ -0,0 +1,79 @@
+import { StepDefinition, StepBuilder } from '../core/StepDefinition.js';
+
+/**
+ * Create step definitions from a configuration array
+ *
+ * @param {Array} config - Array of step configurations
+ * @param {Object} handlers - Object containing handler functions
+ * @returns {Array<StepDefinition>} Array of step definitions
+ *
+ * @example
+ * const steps = createStepsFromConfig([
+ *   {
+ *     id: 'loadData',
+ *     name: 'Load Data',
+ *     startMessage: 'start loading data from source',
+ *     successMessage: 'done loading data successfully'
+ *   }
+ * ], handlers);
+ */
+export function createStepsFromConfig(config, handlers) {
+  if (!Array.isArray(config)) {
+    throw new Error('Config must be an array');
+  }
+
+  if (!handlers || typeof handlers !== 'object') {
+    throw new Error('Handlers must be an object');
+  }
+
+  return config.map((stepConfig, index) => {
+    const {
+      id,
+      name,
+      description,
+      startMessage,
+      successMessage,
+      errorMessage,
+      ...options
+    } = stepConfig;
+
+    // Validate required fields
+    if (!id) {
+      throw new Error(`Step at index ${index}: 'id' is required`);
+    }
+
+    if (!name) {
+      throw new Error(`Step ${id}: 'name' is required`);
+    }
+
+    // Get handler function
+    const handler = handlers[id];
+    if (typeof handler !== 'function') {
+      throw new Error(
+        `Step ${id}: handler function not found in handlers object. ` +
+        `Expected handlers['${id}'] to be a function.`
+      );
+    }
+
+    // Create step definition
+    return new StepDefinition(
+      id,
+      name,
+      description || startMessage || '',
+      handler,
+      {
+        startMessage,
+        successMessage,
+        errorMessage,
+        ...options
+      }
+    );
+  });
+}
+
+/**
+ * Create a fluent step builder
+ */
+export function step(id, name) {
+  return new StepBuilder(id, name);
+}