cmdx 0.5.0 → 1.0.0

data/lib/cmdx/validators/presence.rb

@@ -2,18 +2,104 @@
 
 module CMDx
   module Validators
+    # Presence validator for parameter validation ensuring values are not empty.
+    #
+    # The Presence validator checks that parameter values are not nil, not empty
+    # strings (including whitespace-only strings), and not empty collections.
+    # It provides intelligent presence checking for different value types with
+    # appropriate logic for strings, arrays, hashes, and other objects.
+    #
+    # @example Basic presence validation
+    #   class ProcessUserTask < CMDx::Task
+    #     required :name, presence: true
+    #     required :email, presence: true
+    #     optional :bio, presence: true  # Only validated if provided
+    #   end
+    #
+    # @example Custom presence message
+    #   class ProcessUserTask < CMDx::Task
+    #     required :name, presence: { message: "is required for processing" }
+    #     required :email, presence: { message: "must be provided" }
+    #   end
+    #
+    # @example Boolean field presence validation
+    #   class ProcessUserTask < CMDx::Task
+    #     # For boolean fields, use inclusion instead of presence
+    #     required :active, inclusion: { in: [true, false] }
+    #     # presence: true would fail for false values
+    #   end
+    #
+    # @example Presence validation behavior
+    #   # String presence checking
+    #   Presence.call("hello", presence: true)     # passes
+    #   Presence.call("", presence: true)          # raises ValidationError
+    #   Presence.call("   ", presence: true)       # raises ValidationError (whitespace only)
+    #   Presence.call("\n\t", presence: true)      # raises ValidationError (whitespace only)
+    #
+    #   # Collection presence checking
+    #   Presence.call([1, 2], presence: true)      # passes
+    #   Presence.call([], presence: true)          # raises ValidationError
+    #   Presence.call({a: 1}, presence: true)      # passes
+    #   Presence.call({}, presence: true)          # raises ValidationError
+    #
+    #   # General object presence checking
+    #   Presence.call(42, presence: true)          # passes
+    #   Presence.call(0, presence: true)           # passes (zero is present)
+    #   Presence.call(false, presence: true)       # passes (false is present)
+    #   Presence.call(nil, presence: true)         # raises ValidationError
+    #
+    # @see CMDx::Validators::Inclusion For validating boolean fields
+    # @see CMDx::Parameter Parameter validation integration
+    # @see CMDx::ValidationError Raised when validation fails
     module Presence
 
       module_function
 
+      # Validates that a parameter value is present (not empty or nil).
+      #
+      # Performs intelligent presence checking based on the value type:
+      # - Strings: Must contain non-whitespace characters
+      # - Collections: Must not be empty (arrays, hashes, etc.)
+      # - Other objects: Must not be nil
+      #
+      # @param value [Object] The parameter value to validate
+      # @param options [Hash] Validation configuration options
+      # @option options [Boolean, Hash] :presence Presence validation configuration
+      # @option options [String] :presence.message Custom error message
+      #
+      # @return [void]
+      # @raise [ValidationError] If value is not present according to type-specific rules
+      #
+      # @example String presence validation
+      #   Presence.call("hello", presence: true)     # passes
+      #   Presence.call("", presence: true)          # raises ValidationError
+      #   Presence.call("   ", presence: true)       # raises ValidationError
+      #
+      # @example Collection presence validation
+      #   Presence.call([1, 2, 3], presence: true)   # passes
+      #   Presence.call([], presence: true)          # raises ValidationError
+      #   Presence.call({key: "value"}, presence: true) # passes
+      #   Presence.call({}, presence: true)          # raises ValidationError
+      #
+      # @example Object presence validation
+      #   Presence.call(42, presence: true)          # passes
+      #   Presence.call(false, presence: true)       # passes (false is present)
+      #   Presence.call(nil, presence: true)         # raises ValidationError
+      #
+      # @example Custom error message
+      #   Presence.call("", presence: { message: "is required" })
+      #   # => raises ValidationError: "is required"
       def call(value, options = {})
-        return if if value.is_a?(String)
-                    /\S/.match?(value)
-                  elsif value.respond_to?(:empty?)
-                    !value.empty?
-                  else
-                    !value.nil?
-                  end
+        present =
+          if value.is_a?(String)
+            /\S/.match?(value)
+          elsif value.respond_to?(:empty?)
+            !value.empty?
+          else
+            !value.nil?
+          end
+
+        return if present
 
         message = options.dig(:presence, :message) if options[:presence].is_a?(Hash)
         raise ValidationError, message || I18n.t(

data/lib/cmdx/version.rb

@@ -2,6 +2,12 @@
 
 module CMDx
 
-  VERSION = "0.5.0"
+  # Current version of the CMDx gem.
+  #
+  # This constant contains the version string following semantic versioning
+  # conventions (major.minor.patch).
+  #
+  # @return [String] the current version
+  VERSION = "1.0.0"
 
 end

data/lib/cmdx/workflow.rb

@@ -0,0 +1,394 @@
+# frozen_string_literal: true
+
+module CMDx
+  ##
+  # Orchestrates sequential execution of multiple tasks in a linear pipeline.
+  # Workflow provides a declarative DSL for composing complex business workflows
+  # from individual task components, with support for conditional execution,
+  # context passing, 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.
+  #
+  #
+  # ## Execution Flow
+  #
+  # 1. **Group Evaluation**: Check if group conditions (`:if`/`:unless`) are met
+  # 2. **Task Execution**: Run each task in the group sequentially
+  # 3. **Result Checking**: Evaluate task result against halt conditions
+  # 4. **Halt Decision**: Stop execution if halt conditions are met, otherwise continue
+  # 5. **Context Propagation**: Pass updated context to next task/group
+  #
+  # ## Halt 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. Halt behavior can be customized at class or group level.
+  #
+  # @example Basic workflow definition
+  #   class ProcessOrderWorkflow < CMDx::Workflow
+  #     process ValidateOrderTask
+  #     process CalculateTaxTask
+  #     process ChargePaymentTask
+  #     process FulfillOrderTask
+  #   end
+  #
+  # @example Multiple task declarations
+  #   class NotificationWorkflow < CMDx::Workflow
+  #     # Single task
+  #     process PrepareNotificationTask
+  #
+  #     # Multiple tasks in one declaration
+  #     process SendEmailTask, SendSmsTask, SendPushTask
+  #   end
+  #
+  # @example Conditional execution
+  #   class ConditionalWorkflow < CMDx::Workflow
+  #     process AlwaysRunTask
+  #
+  #     # Conditional execution with proc
+  #     process PremiumFeatureTask, if: proc { context.user.premium? }
+  #
+  #     # Conditional execution with lambda
+  #     process InternationalTask, unless: -> { context.order.domestic? }
+  #
+  #     # Conditional execution with method
+  #     process DebugTask, if: :debug_mode?
+  #
+  #     private
+  #
+  #     def debug_mode?
+  #       Rails.env.development?
+  #     end
+  #   end
+  #
+  # @example Custom halt behavior
+  #   class StrictWorkflow < CMDx::Workflow
+  #     # Class-level halt configuration
+  #     task_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
+  #
+  #     process CriticalTask
+  #     process AnotherCriticalTask
+  #   end
+  #
+  # @example Group-level halt behavior
+  #   class FlexibleWorkflow < CMDx::Workflow
+  #     # Critical tasks - halt on any failure
+  #     process CoreTask1, CoreTask2, workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
+  #
+  #     # Optional tasks - continue even if they fail
+  #     process OptionalTask1, OptionalTask2, workflow_halt: []
+  #
+  #     # Notification tasks - halt only on failures, allow skips
+  #     process NotifyTask1, NotifyTask2  # Uses default halt behavior
+  #   end
+  #
+  # @example Complex workflow
+  #   class EcommerceCheckoutWorkflow < CMDx::Workflow
+  #     # Pre-processing
+  #     process ValidateCartTask
+  #     process CalculateShippingTask
+  #
+  #     # Payment processing (critical)
+  #     process AuthorizePaymentTask, CapturePaymentTask,
+  #       workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
+  #
+  #     # Fulfillment (conditional)
+  #     process CreateShipmentTask, unless: :digital_only?
+  #     process SendDigitalDeliveryTask, if: :has_digital_items?
+  #
+  #     # Post-processing notifications
+  #     process SendConfirmationEmailTask
+  #     process SendConfirmationSmsTask, if: proc { context.user.sms_enabled? }
+  #
+  #     private
+  #
+  #     def digital_only?
+  #       context.order.items.all?(&:digital?)
+  #     end
+  #
+  #     def has_digital_items?
+  #       context.order.items.any?(&:digital?)
+  #     end
+  #   end
+  #
+  # @example Workflow execution and result handling
+  #   # Execute workflow
+  #   result = ProcessOrderWorkflow.call(order: order, user: current_user)
+  #
+  #   # Check results
+  #   if result.success?
+  #     redirect_to success_path
+  #   elsif result.failed?
+  #     # Handle failure - context contains data from all executed tasks
+  #     flash[:error] = "Order processing failed: #{result.context.error_message}"
+  #     redirect_to cart_path
+  #   end
+  #
+  # @example Nested workflows
+  #   class MasterWorkflow < CMDx::Workflow
+  #     process PreProcessingWorkflow
+  #     process CoreProcessingWorkflow
+  #     process PostProcessingWorkflow
+  #   end
+  #
+  # @see Task Base class providing callbacks, parameters, and result tracking
+  # @see Context Shared data object passed between tasks
+  # @see Result Task execution results and status tracking
+  # @since 1.0.0
+  class Workflow < Task
+
+    ##
+    # Represents a logical group of tasks with shared execution options.
+    # Groups allow organizing related tasks and applying common configuration
+    # such as conditional execution and halt behavior.
+    #
+    # @!attribute [r] tasks
+    #   @return [Array<Class>] array of task classes to execute
+    # @!attribute [r] options
+    #   @return [Hash] execution options including conditions and halt behavior
+    #
+    # @example Group creation
+    #   group = CMDx::Workflow::Group.new(
+    #     [TaskA, TaskB, TaskC],
+    #     { if: proc { condition }, workflow_halt: ["failed"] }
+    #   )
+    Group = Struct.new(:tasks, :options)
+
+    class << self
+
+      ##
+      # Returns the collection of task groups defined for this workflow.
+      # Groups are created through `process` declarations and store
+      # both the tasks to execute and their execution options.
+      #
+      # @return [Array<Group>] array of task groups in declaration order
+      #
+      # @example Accessing workflow groups
+      #   class MyWorkflow < CMDx::Workflow
+      #     process TaskA, TaskB
+      #     process TaskC, if: proc { condition }
+      #   end
+      #
+      #   MyWorkflow.workflow_groups.size  #=> 2
+      #   MyWorkflow.workflow_groups.first.tasks  #=> [TaskA, TaskB]
+      #   MyWorkflow.workflow_groups.last.options  #=> { if: proc { condition } }
+      #
+      # @example Inspecting group configuration
+      #   workflow_class.workflow_groups.each_with_index do |group, index|
+      #     puts "Group #{index}: #{group.tasks.map(&:name).join(', ')}"
+      #     puts "Options: #{group.options}" if group.options.any?
+      #   end
+      def workflow_groups
+        @workflow_groups ||= []
+      end
+
+      ##
+      # Declares tasks to be executed as part of this workflow.
+      # Tasks are organized into groups with shared execution options.
+      # Multiple calls to `process` create separate groups that can have
+      # different conditional logic and halt behavior.
+      #
+      # ## Supported Options
+      #
+      # - **`:if`** - Callable that must return truthy for group to execute
+      # - **`:unless`** - Callable that must return falsy for group to execute
+      # - **`:workflow_halt`** - Array of result statuses that stop execution
+      #
+      # ## Conditional Callables
+      #
+      # Conditions can be:
+      # - **Proc/Lambda**: Executed in workflow instance context
+      # - **Symbol**: Method name called on workflow instance
+      # - **String**: Method name called on workflow instance
+      #
+      # @param tasks [Array<Class>] task classes that inherit from Task or Workflow
+      # @param options [Hash] execution options for this group
+      #
+      # @option options [Proc, Symbol, String] :if condition that must be truthy
+      # @option options [Proc, Symbol, String] :unless condition that must be falsy
+      # @option options [Array<Symbol>] :workflow_halt result statuses that halt execution
+      #
+      # @raise [TypeError] if any task doesn't inherit from Task
+      #
+      # @example Basic task declaration
+      #   class SimpleWorkflow < CMDx::Workflow
+      #     process TaskA
+      #     process TaskB, TaskC
+      #   end
+      #
+      # @example Conditional execution
+      #   class ConditionalWorkflow < CMDx::Workflow
+      #     process AlwaysTask
+      #
+      #     # Proc condition
+      #     process PremiumTask, if: proc { context.user.premium? }
+      #
+      #     # Lambda condition
+      #     process InternationalTask, unless: -> { context.domestic_only? }
+      #
+      #     # Method condition
+      #     process DebugTask, if: :debug_enabled?
+      #
+      #     private
+      #
+      #     def debug_enabled?
+      #       Rails.env.development?
+      #     end
+      #   end
+      #
+      # @example Custom halt behavior
+      #   class HaltBehaviorWorkflow < CMDx::Workflow
+      #     # Critical tasks - halt on any non-success
+      #     process CriticalTaskA, CriticalTaskB,
+      #       workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
+      #
+      #     # Optional tasks - never halt
+      #     process OptionalTaskA, OptionalTaskB, workflow_halt: []
+      #
+      #     # Default behavior tasks
+      #     process NormalTaskA, NormalTaskB  # Halts on FAILED only
+      #   end
+      #
+      # @example Complex conditions
+      #   class ComplexWorkflow < CMDx::Workflow
+      #     process BaseTask
+      #
+      #     # Multiple conditions can be combined in proc
+      #     process ConditionalTask, if: proc {
+      #       context.user.active? &&
+      #       context.feature_enabled?(:new_feature) &&
+      #       Time.now.hour.between?(9, 17)
+      #     }
+      #
+      #     # Conditional with custom halt behavior
+      #     process RiskyTask,
+      #       unless: :safe_mode?,
+      #       workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
+      #   end
+      #
+      # @example Nested workflow processing
+      #   class MasterWorkflow < CMDx::Workflow
+      #     process PreProcessingWorkflow
+      #     process CoreWorkflow, if: proc { context.pre_processing_successful? }
+      #     process PostProcessingWorkflow, unless: proc { context.skip_post_processing? }
+      #   end
+      def process(*tasks, **options)
+        workflow_groups << Group.new(
+          tasks.flatten.map do |task|
+            next task if task <= Task
+
+            raise TypeError, "must be a Task or Workflow"
+          end,
+          options
+        )
+      end
+
+    end
+
+    ##
+    # Executes all defined task groups in sequential order.
+    # This method is automatically defined and should not be overridden.
+    # The execution flow handles conditional evaluation, task execution,
+    # and halt behavior according to the workflow configuration.
+    #
+    # ## Execution Algorithm
+    #
+    # 1. **Group Iteration**: Process each group in declaration order
+    # 2. **Condition Evaluation**: Check `:if`/`:unless` conditions
+    # 3. **Task Execution**: Run each task in the group sequentially
+    # 4. **Result Evaluation**: Check task result against halt conditions
+    # 5. **Halt Decision**: Stop execution or continue to next task
+    # 6. **Context Propagation**: Pass updated context through pipeline
+    #
+    # ## Context Behavior
+    #
+    # The context object is shared across all tasks in the workflow:
+    # - Tasks can read data added by previous tasks
+    # - Tasks can modify context for subsequent tasks
+    # - Context persists throughout the entire workflow execution
+    # - Final context is available in the workflow result
+    #
+    # ## Error Handling
+    #
+    # Workflow execution follows the same error handling as individual tasks:
+    # - Exceptions become failed results
+    # - Faults are propagated through the result chain
+    # - Halt behavior determines whether execution continues
+    #
+    # @return [Result] workflow execution result with aggregated context
+    #
+    # @example Basic execution flow
+    #   # Given this workflow:
+    #   class ProcessOrderWorkflow < 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
+    #   end
+    #
+    #   # Execution creates a pipeline:
+    #   result = ProcessOrderWorkflow.call(order: order)
+    #   result.context.validation_result  # From ValidateOrderTask
+    #   result.context.tax_amount        # From CalculateTaxTask
+    #   result.context.payment_id        # From ChargePaymentTask
+    #   result.context.tracking_number   # From FulfillOrderTask
+    #
+    # @example Conditional execution
+    #   # Given this workflow:
+    #   class ConditionalWorkflow < CMDx::Workflow
+    #     process TaskA                           # Always runs
+    #     process TaskB, if: proc { context.run_b? }      # Conditional
+    #     process TaskC, unless: proc { context.skip_c? } # Conditional
+    #   end
+    #
+    #   # Execution evaluates conditions:
+    #   # 1. TaskA runs (always)
+    #   # 2. TaskB runs only if context.run_b? is truthy
+    #   # 3. TaskC runs only if context.skip_c? is falsy
+    #
+    # @example Halt behavior
+    #   # Given this workflow with custom halt:
+    #   class HaltWorkflow < CMDx::Workflow
+    #     process TaskA                    # Default halt (FAILED)
+    #     process TaskB, TaskC, workflow_halt: []  # Never halt
+    #     process TaskD                    # Default halt (FAILED)
+    #   end
+    #
+    #   # If TaskB fails:
+    #   # - TaskB execution completes with failed status
+    #   # - TaskC still executes (workflow_halt: [] means no halt)
+    #   # - TaskD still executes
+    #   # - Workflow continues to completion
+    #
+    #   # If TaskA fails:
+    #   # - TaskA execution completes with failed status
+    #   # - Workflow halts (default behavior)
+    #   # - TaskB, TaskC, TaskD never execute
+    #   # - Workflow result shows failed status
+    #
+    # @note Do not override this method. Workflow execution logic is automatically
+    #   provided and handles all the complexity of group processing, conditional
+    #   evaluation, and halt behavior.
+    #
+    # @see Task#call Base task execution method
+    # @see Context Shared data object
+    # @see Result Task execution results
+    def call
+      self.class.workflow_groups.each do |group|
+        next unless __cmdx_eval(group.options)
+
+        workflow_halt = group.options[:workflow_halt] || task_setting(:workflow_halt)
+
+        group.tasks.each do |task|
+          task_result = task.call(context)
+          next unless Array(workflow_halt).include?(task_result.status)
+
+          throw!(task_result)
+        end
+      end
+    end
+
+  end
+end

data/lib/cmdx.rb

@@ -9,79 +9,40 @@ require "pp"
 require "securerandom"
 require "time"
 require "timeout"
+require "zeitwerk"
 
-require_relative "cmdx/version"
+module CMDx; end
+
+# Set up Zeitwerk loader for the CMDx gem
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect("cmdx" => "CMDx")
+loader.ignore("#{__dir__}/cmdx/core_ext")
+loader.ignore("#{__dir__}/cmdx/configuration")
+loader.ignore("#{__dir__}/cmdx/faults")
+loader.ignore("#{__dir__}/cmdx/railtie")
+loader.ignore("#{__dir__}/cmdx/rspec")
+loader.ignore("#{__dir__}/generators")
+loader.ignore("#{__dir__}/locales")
+loader.setup
+
+# Pre-load core extensions to avoid circular dependencies
 require_relative "cmdx/core_ext/object"
 require_relative "cmdx/core_ext/hash"
 require_relative "cmdx/core_ext/module"
-require_relative "cmdx/log_formatters/json"
-require_relative "cmdx/log_formatters/key_value"
-require_relative "cmdx/log_formatters/line"
-require_relative "cmdx/log_formatters/logstash"
-require_relative "cmdx/log_formatters/raw"
-require_relative "cmdx/log_formatters/pretty_json"
-require_relative "cmdx/log_formatters/pretty_key_value"
-require_relative "cmdx/log_formatters/pretty_line"
-require_relative "cmdx/coercions/array"
-require_relative "cmdx/coercions/big_decimal"
-require_relative "cmdx/coercions/boolean"
-require_relative "cmdx/coercions/complex"
-require_relative "cmdx/coercions/date"
-require_relative "cmdx/coercions/date_time"
-require_relative "cmdx/coercions/float"
-require_relative "cmdx/coercions/hash"
-require_relative "cmdx/coercions/integer"
-require_relative "cmdx/coercions/rational"
-require_relative "cmdx/coercions/string"
-require_relative "cmdx/coercions/time"
-require_relative "cmdx/coercions/virtual"
-require_relative "cmdx/validators/custom"
-require_relative "cmdx/validators/exclusion"
-require_relative "cmdx/validators/format"
-require_relative "cmdx/validators/inclusion"
-require_relative "cmdx/validators/length"
-require_relative "cmdx/validators/numeric"
-require_relative "cmdx/validators/presence"
-require_relative "cmdx/utils/ansi_color"
-require_relative "cmdx/utils/log_timestamp"
-require_relative "cmdx/utils/name_affix"
-require_relative "cmdx/utils/monotonic_runtime"
-require_relative "cmdx/error"
-require_relative "cmdx/errors"
-require_relative "cmdx/fault"
-require_relative "cmdx/faults"
-require_relative "cmdx/logger_serializer"
-require_relative "cmdx/logger_ansi"
-require_relative "cmdx/logger"
-require_relative "cmdx/lazy_struct"
+
+# Pre-load configuration to make module methods available
+# This is acceptable since configuration is fundamental to the framework
 require_relative "cmdx/configuration"
-require_relative "cmdx/context"
-require_relative "cmdx/run"
-require_relative "cmdx/run_serializer"
-require_relative "cmdx/run_inspector"
-require_relative "cmdx/parameter"
-require_relative "cmdx/parameter_value"
-require_relative "cmdx/parameter_validator"
-require_relative "cmdx/parameter_serializer"
-require_relative "cmdx/parameter_inspector"
-require_relative "cmdx/parameters"
-require_relative "cmdx/parameters_serializer"
-require_relative "cmdx/parameters_inspector"
-require_relative "cmdx/result"
-require_relative "cmdx/result_serializer"
-require_relative "cmdx/result_inspector"
-require_relative "cmdx/result_ansi"
-require_relative "cmdx/result_logger"
-require_relative "cmdx/task"
-require_relative "cmdx/task_hook"
-require_relative "cmdx/task_serializer"
-require_relative "cmdx/batch"
-require_relative "cmdx/immutator"
 
+# Pre-load fault classes to make them available at the top level
+# This ensures CMDx::Failed and CMDx::Skipped are always available
+require_relative "cmdx/faults"
+
+# Conditionally load Rails components if Rails is available
 if defined?(Rails::Generators)
   require_relative "generators/cmdx/install_generator"
   require_relative "generators/cmdx/task_generator"
-  require_relative "generators/cmdx/batch_generator"
+  require_relative "generators/cmdx/workflow_generator"
 end
 
 # Load the Railtie last after everything else is required so we don't

data/lib/generators/cmdx/install_generator.rb

@@ -1,12 +1,48 @@
 # frozen_string_literal: true
 
 module Cmdx
+  ##
+  # Rails generator for creating CMDx initializer configuration.
+  #
+  # This generator creates a configuration initializer file that sets up
+  # global CMDx settings for task execution, workflow processing, logging,
+  # and error handling behaviors.
+  #
+  # The generated initializer provides sensible defaults that can be
+  # customized for specific application requirements.
+  #
+  # @example Generate CMDx initializer
+  #   rails generate cmdx:install
+  #
+  # @example Generated file location
+  #   config/initializers/cmdx.rb
+  #
+  # @since 1.0.0
   class InstallGenerator < Rails::Generators::Base
 
     source_root File.expand_path("templates", __dir__)
 
-    desc "Generates a CMDx configurations files for global settings."
+    desc "Creates CMDx initializer with global configuration settings"
 
+    ##
+    # Copies the CMDx configuration template to the Rails initializers directory.
+    #
+    # Creates a new initializer file at `config/initializers/cmdx.rb` with
+    # default configuration settings for:
+    # - Task halt behaviors
+    # - Timeout settings
+    # - Workflow execution controls
+    # - Logger configuration
+    #
+    # @return [void]
+    # @raise [Thor::Error] if the destination file cannot be created
+    #
+    # @example Generated initializer content
+    #   CMDx.configure do |config|
+    #     config.task_halt = CMDx::Result::FAILED
+
+    #     # ... additional settings
+    #   end
     def copy_initializer_file
       copy_file("install.rb", "config/initializers/cmdx.rb")
     end