cmdx 1.0.1 → 1.1.1

data/docs/workflows.md

@@ -1,6 +1,6 @@
 # Workflow
 
-A CMDx::Workflow orchestrates sequential execution of multiple tasks in a linear pipeline. Workflows provide a declarative DSL for composing complex business workflows from individual task components, with support for conditional execution, context propagation, and configurable halt behavior.
+CMDx::Workflow orchestrates sequential execution of multiple tasks in a linear pipeline. Workflows provide a declarative DSL for composing complex business workflows from individual task components, with support for conditional execution, context propagation, and configurable halt behavior.
 
 Workflows inherit from Task, gaining all task capabilities including callbacks, parameter validation, result tracking, and configuration. The key difference is that workflows coordinate other tasks rather than implementing business logic directly.
 
@@ -17,55 +17,68 @@ Workflows inherit from Task, gaining all task capabilities including callbacks,
   - [Group-Level Configuration](#group-level-configuration)
   - [Available Result Statuses](#available-result-statuses)
 - [Process Method Options](#process-method-options)
-  - [Condition Callables](#condition-callables)
+- [Error Handling](#error-handling)
 - [Nested Workflows](#nested-workflows)
 - [Task Settings Integration](#task-settings-integration)
 - [Generator](#generator)
 
 ## TLDR
 
-- **Purpose** - Orchestrate sequential execution of multiple tasks in linear pipeline
-- **Declaration** - Use `process` method to declare tasks in execution order
-- **Context sharing** - Context object shared across all tasks for data pipeline
-- **Conditional execution** - Support `:if` and `:unless` options for conditional tasks
-- **Halt behavior** - Configurable stopping on failed/skipped results (default: halt on failed only)
-- **No call method** - Workflows automatically provide execution logic, don't define `call`
+```ruby
+# Basic workflow - sequential task execution
+class OrderWorkflow < CMDx::Workflow
+  process ValidateOrderTask      # Step 1
+  process CalculateTaxTask       # Step 2
+  process ChargePaymentTask      # Step 3
+end
+
+# Conditional execution
+process SendEmailTask, if: proc { context.notify_user? }
+process SkipableTask, unless: :should_skip?
+
+# Halt behavior control
+process CriticalTask, workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
+process OptionalTask, workflow_halt: []  # Never halt
+
+# Context flows through all tasks automatically
+result = OrderWorkflow.call(order: order)
+result.context.tax_amount    # Set by CalculateTaxTask
+result.context.payment_id    # Set by ChargePaymentTask
+```
 
 ## Basic Usage
 
 > [!WARNING]
-> Do **NOT** define a `call` method in workflow classes. The workflow class automatically provides the call logic.
+> Do **NOT** define a `call` method in workflow classes. The workflow automatically provides execution logic.
 
 ```ruby
 class OrderProcessingWorkflow < CMDx::Workflow
-  # Sequential task execution
   process ValidateOrderTask
   process CalculateTaxTask
   process ChargePaymentTask
   process FulfillOrderTask
 end
 
-# Execute the workflow
-result = WorkflowProcessOrders.call(order: order, user: current_user)
+# Execute workflow
+result = OrderProcessingWorkflow.call(order: order, user: current_user)
 
 if result.success?
-  redirect_to success_path
+  redirect_to order_path(result.context.order)
 elsif result.failed?
-  flash[:error] = "Order processing failed: #{result.metadata[:reason]}"
-  redirect_to cart_path
+  handle_error(result.metadata[:reason])
 end
 ```
 
 ## Task Declaration
 
-Tasks are declared using the `process` method and organized into groups with shared execution options:
+Tasks are declared using the `process` method in execution order:
 
 ```ruby
-class NotificationDeliveryWorkflow < CMDx::Workflow
-  # Single task declaration
+class NotificationWorkflow < CMDx::Workflow
+  # Single task
   process PrepareNotificationTask
 
-  # Multiple tasks in one declaration (grouped)
+  # Multiple tasks (grouped with same options)
   process SendEmailTask, SendSmsTask, SendPushTask
 
   # Tasks with conditions
@@ -81,34 +94,32 @@ end
 ```
 
 > [!IMPORTANT]
-> Process steps are executed in the order they are declared (FIFO: first in, first out).
+> Tasks execute in declaration order (FIFO). Use grouping to apply the same options to multiple tasks.
 
 ## Context Propagation
 
-The context object is shared across all tasks in the workflow, creating a data pipeline:
+The context object flows through all tasks, creating a data pipeline:
 
 ```ruby
-class EcommerceProcessingWorkflow < CMDx::Workflow
-  process ValidateOrderTask # Sets context.validation_result
-  process CalculateTaxTask  # Uses context.order, sets context.tax_amount
-  process ChargePaymentTask # Uses context.tax_amount, sets context.payment_id
-  process FulfillOrderTask  # Uses context.payment_id, sets context.tracking_number
+class PaymentWorkflow < CMDx::Workflow
+  process ValidateOrderTask  # Sets context.validation_errors
+  process CalculateTaxTask   # Uses context.order, sets context.tax_amount
+  process ChargePaymentTask  # Uses context.tax_amount, sets context.payment_id
 end
 
-result = WorkflowProcessEcommerce.call(order: order)
-# Final context contains data from all executed tasks
-result.context.validation_result # From ValidateOrderTask
-result.context.tax_amount        # From CalculateTaxTask
-result.context.payment_id        # From ChargePaymentTask
-result.context.tracking_number   # From FulfillOrderTask
+result = PaymentWorkflow.call(order: order)
+# Context contains cumulative data from all executed tasks
+result.context.validation_errors  # From ValidateOrderTask
+result.context.tax_amount         # From CalculateTaxTask
+result.context.payment_id         # From ChargePaymentTask
 ```
 
 ## Conditional Execution
 
-Tasks can be executed conditionally using `:if` and `:unless` options. Conditions can be procs, lambdas, or method names:
+Tasks can execute conditionally using `:if` and `:unless` options:
 
 ```ruby
-class UserProcessingWorkflow < CMDx::Workflow
+class UserWorkflow < CMDx::Workflow
   process ValidateUserTask
 
   # Proc condition
@@ -124,7 +135,7 @@ class UserProcessingWorkflow < CMDx::Workflow
   process SendSpecialOfferTask, if: proc {
     context.user.active? &&
     context.feature_enabled?(:offers) &&
-    Time.now.hour.between?(9, 17)
+    business_hours?
   }
 
   private
@@ -132,41 +143,48 @@ class UserProcessingWorkflow < CMDx::Workflow
   def debug_enabled?
     Rails.env.development?
   end
+
+  def business_hours?
+    Time.now.hour.between?(9, 17)
+  end
 end
 ```
 
+> [!NOTE]
+> Conditions are evaluated in the workflow instance context. Skipped tasks return `SKIPPED` status but don't halt execution by default.
+
 ## Halt Behavior
 
-Workflows control execution flow through halt behavior, which determines when to stop processing based on task results.
+Workflows control execution flow by halting on specific result statuses.
 
 ### Default Behavior
 
-By default, workflows halt on `FAILED` status but continue on `SKIPPED`. This reflects the philosophy that skipped tasks are bypass mechanisms, not execution blockers.
+By default, workflows halt on `FAILED` status but continue on `SKIPPED`:
 
 ```ruby
-class DataProcessingWorkflow < CMDx::Workflow
-  process LoadDataTask     # If this fails, workflow stops
-  process ValidateDataTask # If this is skipped, workflow continues
-  process SaveDataTask     # This only runs if LoadDataTask and ValidateDataTask don't fail
+class DataWorkflow < CMDx::Workflow
+  process LoadDataTask      # If fails → workflow stops
+  process ValidateDataTask  # If skipped → workflow continues
+  process SaveDataTask      # Only runs if no failures occurred
 end
 ```
 
 ### Class-Level Configuration
 
-Configure halt behavior for the entire workflow using `task_settings!`:
+Configure halt behavior for the entire workflow:
 
 ```ruby
-class CriticalDataProcessingWorkflow < CMDx::Workflow
+class CriticalWorkflow < CMDx::Workflow
   # Halt on both failed and skipped results
-  task_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
+  cmd_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
 
   process LoadCriticalDataTask
   process ValidateCriticalDataTask
 end
 
-class OptionalDataProcessingWorkflow < CMDx::Workflow
+class OptionalWorkflow < CMDx::Workflow
   # Never halt, always continue
-  task_settings!(workflow_halt: [])
+  cmd_settings!(workflow_halt: [])
 
   process TryLoadDataTask
   process TryValidateDataTask
@@ -176,73 +194,102 @@ end
 
 ### Group-Level Configuration
 
-Different groups can have different halt behavior:
+Different task groups can have different halt behavior:
 
 ```ruby
-class UserAccountProcessingWorkflow < CMDx::Workflow
+class AccountWorkflow < CMDx::Workflow
   # Critical tasks - halt on any failure or skip
   process CreateUserTask, ValidateUserTask,
     workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
 
-  # Optional tasks - never halt execution
-  process SendWelcomeEmailTask, CreateProfileTask, workflow_halt: []
+  # Optional tasks - never halt
+  process SendWelcomeEmailTask, CreateProfileTask,
+    workflow_halt: []
 
-  # Notification tasks - use default behavior (halt on failed only)
+  # Default behavior for remaining tasks
   process NotifyAdminTask, LogUserCreationTask
 end
 ```
 
 ### Available Result Statuses
 
-The following result statuses can be used in `workflow_halt` arrays:
+Use these statuses in `workflow_halt` arrays:
 
-- `CMDx::Result::SUCCESS` - Task completed successfully
-- `CMDx::Result::SKIPPED` - Task was skipped intentionally
-- `CMDx::Result::FAILED` - Task failed due to error or validation
+| Status | Description |
+|--------|-------------|
+| `CMDx::Result::SUCCESS` | Task completed successfully |
+| `CMDx::Result::SKIPPED` | Task was skipped intentionally |
+| `CMDx::Result::FAILED` | Task failed due to error or validation |
 
 ## Process Method Options
 
-The `process` method supports the following options:
+The `process` method supports these options:
 
-| Option        | Description |
-| ------------- | ----------- |
-| `:if`         | Specifies a callable method, proc or string to determine if processing steps should occur. |
-| `:unless`     | Specifies a callable method, proc, or string to determine if processing steps should not occur. |
-| `:workflow_halt` | Sets which result statuses processing of further steps should be prevented. (default: `CMDx::Result::FAILED`) |
+| Option | Description | Example |
+|--------|-------------|---------|
+| `:if` | Execute task if condition is true | `if: proc { context.enabled? }` |
+| `:unless` | Execute task if condition is false | `unless: :should_skip?` |
+| `:workflow_halt` | Which statuses should halt execution | `workflow_halt: [CMDx::Result::FAILED]` |
 
-### Condition Callables
+Conditions can be procs, lambdas, symbols, or strings referencing instance methods.
 
-Conditions can be provided in several formats:
+## Error Handling
 
-```ruby
-class AccountProcessingWorkflow < CMDx::Workflow
-  # Proc - executed in workflow instance context
-  process UpgradeAccountTask, if: proc { context.user.admin? }
+> [!WARNING]
+> Workflow failures provide detailed information about which task failed and why, enabling precise error handling and debugging.
 
-  # Lambda - executed in workflow instance context
-  process MaintenanceModeTask, unless: -> { context.maintenance_mode? }
+```ruby
+class OrderWorkflow < CMDx::Workflow
+  process ValidateOrderTask
+  process CalculateTaxTask
+  process ChargePaymentTask
+end
 
-  # Symbol - method name called on workflow instance
-  process AdvancedFeatureTask, if: :feature_enabled?
+result = OrderWorkflow.call(order: invalid_order)
+
+if result.failed?
+  result.metadata
+  # {
+  #   reason: "ValidateOrderTask failed: Order ID is required",
+  #   failed_task: "ValidateOrderTask",
+  #   task_index: 0,
+  #   executed_tasks: ["ValidateOrderTask"],
+  #   skipped_tasks: [],
+  #   context_at_failure: { order: {...} }
+  # }
+end
+```
 
-  # String - method name called on workflow instance
-  process OptionalTask, unless: "skip_task?"
+### Common Error Scenarios
 
-  private
+```ruby
+# Task raises exception
+class ProcessDataWorkflow < CMDx::Workflow
+  process ValidateDataTask  # Raises validation error
+  process TransformDataTask # Never executes
+end
 
-  def feature_enabled?
-    context.features.include?(:advanced)
-  end
+result = ProcessDataWorkflow.call(data: nil)
+result.failed?  # → true
+result.metadata[:reason]  # → "ValidateDataTask failed: Data cannot be nil"
 
-  def skip_task?
-    context.skip_optional_tasks?
-  end
+# Halt on skipped task
+class StrictWorkflow < CMDx::Workflow
+  process RequiredTask, workflow_halt: [CMDx::Result::SKIPPED]
+  process OptionalTask, if: proc { false }  # Always skipped
+  process FinalTask  # Never executes
 end
+
+result = StrictWorkflow.call
+result.failed?  # → true (halted on skipped task)
 ```
 
+> [!TIP]
+> Use specific halt configurations to implement different failure strategies: strict validation, best-effort processing, or fault-tolerant pipelines.
+
 ## Nested Workflows
 
-Workflows can process other workflows, creating hierarchical workflows:
+Workflows can process other workflows for hierarchical composition:
 
 ```ruby
 class DataPreProcessingWorkflow < CMDx::Workflow
@@ -255,35 +302,33 @@ class DataProcessingWorkflow < CMDx::Workflow
   process ApplyBusinessLogicTask
 end
 
-class DataPostProcessingWorkflow < CMDx::Workflow
-  process GenerateReportTask
-  process SendNotificationTask
-end
-
-class CompleteDataProcessingWorkflow < CMDx::Workflow
+class CompleteDataWorkflow < CMDx::Workflow
   process DataPreProcessingWorkflow
   process DataProcessingWorkflow, if: proc { context.pre_processing_successful? }
-  process DataPostProcessingWorkflow, unless: proc { context.skip_post_processing? }
+  process GenerateReportTask
 end
 ```
 
+> [!NOTE]
+> Nested workflows share the same context object, enabling seamless data flow across workflow boundaries.
+
 ## Task Settings Integration
 
-Workflows support all task settings and can be configured like regular tasks:
+Workflows support all task capabilities including parameters, callbacks, and configuration:
 
 ```ruby
-class PaymentProcessingWorkflow < CMDx::Workflow
-  # Configure workflow-specific settings
-  task_settings!(
+class PaymentWorkflow < CMDx::Workflow
+  # Parameter validation
+  required :order_id, type: :integer
+  optional :notify_user, type: :boolean, default: true
+
+  # Workflow settings
+  cmd_settings!(
     workflow_halt: [CMDx::Result::FAILED],
     log_level: :debug,
     tags: [:critical, :payment]
   )
 
-  # Parameter validation
-  required :order_id, type: :integer
-  optional :notify_user, type: :boolean, default: true
-
   # Callbacks
   before_execution :setup_context
   after_execution :cleanup_resources
@@ -306,22 +351,22 @@ end
 
 ## Generator
 
-Generate a new workflow using the Rails generator:
+Generate workflow scaffolding using the Rails generator:
 
 ```bash
 rails g cmdx:workflow ProcessOrder
 ```
 
-This creates a workflow template file under `app/cmds`:
+Creates `app/commands/process_order_workflow.rb`:
 
 ```ruby
-class OrderProcessingWorkflow < ApplicationWorkflow
-  process # TODO
+class ProcessOrderWorkflow < ApplicationWorkflow
+  process # TODO: Add your tasks here
 end
 ```
 
 > [!NOTE]
-> The generator creates workflow files in `app/commands/workflow_[name].rb`, inherits from `ApplicationWorkflow` if available (otherwise `CMDx::Workflow`) and handles proper naming conventions.
+> The generator creates workflow files in `app/commands/`, inherits from `ApplicationWorkflow` if available (otherwise `CMDx::Workflow`), and handles proper naming conventions.
 
 ---
 

data/lib/cmdx/callback.rb

@@ -1,67 +1,51 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Base class for CMDx callbacks that provides lifecycle execution points.
+  # Base class for implementing callback functionality in task processing.
   #
-  # Callback components can wrap or observe task execution at specific lifecycle
-  # points like before validation, on success, after execution, etc.
-  # Each callback must implement the `call` method which receives the
-  # task instance and callback context.
-  #
-  # @example Basic callback implementation
-  #   class LoggingCallback < CMDx::Callback
-  #     def call(task, callback_type)
-  #       puts "Executing #{callback_type} callback for #{task.class.name}"
-  #       task.logger.info("Callback executed: #{callback_type}")
-  #     end
-  #   end
-  #
-  # @example Callback with initialization parameters
-  #   class NotificationCallback < CMDx::Callback
-  #     def initialize(channels)
-  #       @channels = channels
-  #     end
-  #
-  #     def call(task, callback_type)
-  #       return unless callback_type == :on_success
-  #
-  #       @channels.each do |channel|
-  #         NotificationService.send(channel, "Task #{task.class.name} completed")
-  #       end
-  #     end
-  #   end
-  #
-  # @example Conditional callback execution
-  #   class ErrorReportingCallback < CMDx::Callback
-  #     def call(task, callback_type)
-  #       return unless callback_type == :on_failure
-  #       return unless task.result.failed?
-  #
-  #       ErrorReporter.notify(
-  #         task.errors.full_messages.join(", "),
-  #         context: task.context.to_h
-  #       )
-  #     end
-  #   end
-  #
-  # @see CallbackRegistry Callback management
-  # @see Task Callback integration
-  # @since 1.0.0
+  # Callbacks are executed at specific points in the task lifecycle, such as
+  # before execution, after success, or on failure. All callback implementations
+  # must inherit from this class and implement the abstract call method.
   class Callback
 
-    ##
-    # Executes the callback logic.
+    # Executes a callback by creating a new instance and calling it.
+    #
+    # @param task [CMDx::Task] the task instance triggering the callback
+    # @param type [Symbol] the callback type being executed (e.g., :before_execution, :on_success, :on_failure)
+    #
+    # @return [void]
+    #
+    # @raise [UndefinedCallError] when the callback subclass doesn't implement call
+    #
+    # @example Execute a callback for task success
+    #   LogSuccessCallback.call(task, :on_success)
+    #
+    # @example Execute a callback before task execution
+    #   SetupCallback.call(task, :before_execution)
+    def self.call(task, type)
+      new.call(task, type)
+    end
+
+    # Abstract method that must be implemented by callback subclasses.
+    #
+    # This method contains the actual callback logic to be executed at the
+    # specified point in the task lifecycle. Subclasses must override this method
+    # to provide their specific callback implementation.
     #
-    # This method must be implemented by subclasses to define the callback
-    # behavior. The method receives the task instance and the callback type
-    # being executed.
+    # @param task [CMDx::Task] the task instance triggering the callback
+    # @param type [Symbol] the callback type being executed
     #
-    # @param task [Task] the task instance being executed
-    # @param callback_type [Symbol] the type of callback being executed
     # @return [void]
-    # @abstract Subclasses must implement this method
-    def call(_task, _callback_type)
+    #
+    # @raise [UndefinedCallError] always raised in the base class
+    #
+    # @example Implement in a subclass
+    #   class NotificationCallback < CMDx::Callback
+    #     def call(task, type)
+    #       puts "Task #{task.class.name} triggered #{type} callback"
+    #     end
+    #   end
+    def call(task, type) # rubocop:disable Lint/UnusedMethodArgument
       raise UndefinedCallError, "call method not defined in #{self.class.name}"
     end