cmdx 1.1.0 → 1.1.1

data/docs/configuration.md

@@ -18,15 +18,31 @@ CMDx provides a flexible configuration system that allows customization at both
 - [Configuration Management](#configuration-management)
   - [Accessing Configuration](#accessing-configuration)
   - [Resetting Configuration](#resetting-configuration)
+- [Error Handling](#error-handling)
 
 ## TLDR
 
-- **Hierarchy** - Global → Task Settings → Runtime (each level overrides previous)
-- **Global config** - Framework-wide defaults via `CMDx.configure`
-- **Task settings** - Class-level overrides using `cmd_settings!`
-- **Key options** - `task_halt`, `workflow_halt`, `logger`, `middlewares`, `callbacks`
-- **Generator** - Use `rails g cmdx:install` to create configuration file
-- **Inheritance** - Settings are inherited from parent classes
+```ruby
+# Generate configuration file
+rails g cmdx:install
+
+# Global configuration
+CMDx.configure do |config|
+  config.task_halt = ["failed", "skipped"]     # Multiple halt statuses
+  config.logger = Rails.logger                 # Custom logger
+  config.middlewares.use TimeoutMiddleware     # Global middleware
+  config.callbacks.register :on_failure, :log # Global callback
+end
+
+# Task-level overrides
+class PaymentTask < CMDx::Task
+  cmd_settings!(task_halt: "failed", tags: ["payments"])
+
+  def call
+    halt_on = cmd_setting(:task_halt)  # Access settings
+  end
+end
+```
 
 ## Configuration Hierarchy
 
@@ -47,7 +63,7 @@ Generate a configuration file using the Rails generator:
 rails g cmdx:install
 ```
 
-This creates `config/initializers/cmdx.rb` with default settings.
+This creates `config/initializers/cmdx.rb` with sensible defaults.
 
 ### Configuration Options
 
@@ -63,102 +79,112 @@ This creates `config/initializers/cmdx.rb` with default settings.
 
 ### Global Middlewares
 
-Configure middlewares that automatically apply to all tasks in your application:
+Configure middlewares that automatically apply to all tasks:
 
 ```ruby
 CMDx.configure do |config|
-  # Add middlewares without arguments
+  # Simple middleware registration
   config.middlewares.use CMDx::Middlewares::Timeout
 
-  # Add middlewares with arguments
+  # Middleware with configuration
   config.middlewares.use CMDx::Middlewares::Timeout, seconds: 30
 
-  # Add middleware instances
-  config.middlewares.use CMDx::Middlewares::Timeout.new(seconds: 30)
+  # Multiple middlewares
+  config.middlewares.use AuthenticationMiddleware
+  config.middlewares.use LoggingMiddleware, level: :debug
+  config.middlewares.use MetricsMiddleware, namespace: "app.tasks"
 end
 ```
 
+> [!NOTE]
+> Middlewares are executed in registration order. Each middleware wraps the next, creating an execution chain around task logic.
+
 ### Global Callbacks
 
-Configure callbacks that automatically apply to all tasks in your application:
+Configure callbacks that automatically apply to all tasks:
 
 ```ruby
 CMDx.configure do |config|
-  # Add method callbacks
-  config.callbacks.register :before_execution, :log_task_start
-
-  # Add callback instances
-  config.callbacks.register :on_success, NotificationCallback.new([:slack])
+  # Method callbacks
+  config.callbacks.register :before_execution, :setup_request_context
+  config.callbacks.register :after_execution, :cleanup_temp_files
 
-  # Add conditional callbacks
-  config.callbacks.register :on_failure, :page_admin, if: :production?
+  # Conditional callbacks
+  config.callbacks.register :on_failure, :notify_admin, if: :production?
+  config.callbacks.register :on_success, :update_metrics, unless: :test?
 
-  # Add proc callbacks
+  # Proc callbacks with context
   config.callbacks.register :on_complete, proc { |task, type|
-    Metrics.increment("task.#{task.class.name.underscore}.completed")
+    duration = task.metadata[:runtime]
+    StatsD.histogram("task.duration", duration, tags: ["class:#{task.class.name}"])
   }
 end
 ```
 
 ### Global Coercions
 
-Configure custom coercions that automatically apply to all tasks in your application:
+Configure custom coercions for domain-specific types:
 
 ```ruby
 CMDx.configure do |config|
-  # Add custom coercion classes
+  # Simple coercion classes
   config.coercions.register :money, MoneyCoercion
+  config.coercions.register :email, EmailCoercion
 
-  # Add complex coercions with options support
-  config.coercions.register :tags, proc { |value, options|
+  # Complex coercions with options
+  config.coercions.register :csv_array, proc { |value, options|
     separator = options[:separator] || ','
-    max_tags = options[:max_tags] || 10
+    max_items = options[:max_items] || 100
 
-    tags = value.to_s.split(separator).map(&:strip).reject(&:empty?)
-    tags = tags.first(max_tags) if max_tags
-    tags.uniq
+    items = value.to_s.split(separator).map(&:strip).reject(&:empty?)
+    items.first(max_items)
   }
 end
 ```
 
 ### Global Validators
 
-Configure validators that automatically apply to all tasks in your application:
+Configure custom validators for parameter validation:
 
 ```ruby
 CMDx.configure do |config|
-  # Add validator classes
+  # Validator classes
   config.validators.register :email, EmailValidator
+  config.validators.register :phone, PhoneValidator
 
-  # Add complex validators with options support
-  config.validators.register :phone, proc { |value, options|
-    country = options.dig(:phone, :country) || "US"
-    case country
-    when "US"
-      value.match?(/\A\d{3}-\d{3}-\d{4}\z/)
-    else
-      value.match?(/\A\+?\d{10,15}\z/)
-    end
+  # Proc validators with options
+  config.validators.register :api_key, proc { |value, options|
+    required_prefix = options.dig(:api_key, :prefix) || "sk_"
+    min_length = options.dig(:api_key, :min_length) || 32
+
+    value.start_with?(required_prefix) && value.length >= min_length
   }
 end
 ```
 
 ## Task Settings
 
-Override global configuration for specific tasks or workflows using `cmd_settings!`:
+Override global configuration for specific tasks using `cmd_settings!`:
 
 ```ruby
 class ProcessPaymentTask < CMDx::Task
   cmd_settings!(
-    task_halt: ["failed"],                       # Only halt on failures
-    tags: ["payments", "critical"],              # Add logging tags
-    logger: Rails.logger,                        # Use Rails logger
-    log_level: :info,                            # Set log level
-    log_formatter: CMDx::LogFormatters::Json.new # JSON formatter
+    task_halt: ["failed"],                          # Only halt on failures
+    tags: ["payments", "critical"],                 # Logging tags
+    logger: PaymentLogger.new,                      # Custom logger
+    log_level: :info,                               # Log level override
+    log_formatter: CMDx::LogFormatters::Json.new    # JSON formatting
   )
 
   def call
-    # Process payment logic
+    # Payment processing logic
+    charge_customer(amount, payment_method)
+  end
+
+  private
+
+  def charge_customer(amount, method)
+    # Implementation details
   end
 end
 ```
@@ -174,18 +200,39 @@ end
 | `log_level`     | Symbol                | Log level (`:debug`, `:info`, `:warn`, `:error`, `:fatal`) |
 | `log_formatter` | LogFormatter          | Custom log formatter |
 
+> [!TIP]
+> Use task-level settings for tasks that require special handling, such as payment processing, external API calls, or critical system operations.
+
 ### Workflow Configuration
 
-Configure halt behavior for workflows:
+Configure halt behavior and logging for workflows:
 
 ```ruby
 class OrderProcessingWorkflow < CMDx::Workflow
-  # Strict workflow - halt on any failure
-  cmd_settings!(workflow_halt: ["failed", "skipped"])
+  # Halt on any non-success status
+  cmd_settings!(
+    workflow_halt: ["failed", "skipped"],
+    tags: ["orders", "e-commerce"],
+    log_level: :info
+  )
 
   process ValidateOrderTask
   process ChargePaymentTask
-  process FulfillOrderTask
+  process UpdateInventoryTask
+  process SendConfirmationTask
+end
+
+class DataMigrationWorkflow < CMDx::Workflow
+  # Continue on skipped tasks, halt only on failures
+  cmd_settings!(
+    workflow_halt: "failed",
+    tags: ["migration", "maintenance"]
+  )
+
+  process BackupDataTask
+  process MigrateUsersTask
+  process MigrateOrdersTask
+  process ValidateDataTask
 end
 ```
 
@@ -194,34 +241,103 @@ end
 ### Accessing Configuration
 
 ```ruby
-# Global configuration
-CMDx.configuration.logger      #=> <Logger instance>
-CMDx.configuration.task_halt   #=> "failed"
-CMDx.configuration.middlewares #=> <MiddlewareRegistry instance>
-CMDx.configuration.callbacks   #=> <CallbackRegistry instance>
-CMDx.configuration.coercions   #=> <CoercionRegistry instance>
-CMDx.configuration.validators  #=> <ValidatorRegistry instance>
+# Global configuration access
+CMDx.configuration.logger                    #=> <Logger instance>
+CMDx.configuration.task_halt                 #=> "failed"
+CMDx.configuration.middlewares.middlewares   #=> [<Middleware>, ...]
+CMDx.configuration.callbacks.callbacks       #=> {before_execution: [...], ...}
 
 # Task-specific settings
-class AnalyzeDataTask < CMDx::Task
-  cmd_settings!(tags: ["analytics"])
+class DataProcessingTask < CMDx::Task
+  cmd_settings!(
+    tags: ["data", "analytics"],
+    task_halt: ["failed", "skipped"]
+  )
 
   def call
-    tags = cmd_setting(:tags)               # Gets ["analytics"]
-    halt_statuses = cmd_setting(:task_halt) # Gets global default
+    # Access current task settings
+    log_tags = cmd_setting(:tags)               #=> ["data", "analytics"]
+    halt_on = cmd_setting(:task_halt)           #=> ["failed", "skipped"]
+    logger_instance = cmd_setting(:logger)      #=> Inherited from global
   end
 end
 ```
 
 ### Resetting Configuration
 
-Reset configuration to defaults (useful for testing):
+> [!WARNING]
+> Resetting configuration affects the entire application. Use primarily in test environments or during application initialization.
 
 ```ruby
+# Reset to framework defaults
 CMDx.reset_configuration!
-CMDx.configuration.task_halt #=> "failed" (default)
+
+# Verify reset
+CMDx.configuration.task_halt     #=> "failed" (default)
+CMDx.configuration.middlewares   #=> Empty registry
+CMDx.configuration.callbacks     #=> Empty registry
+
+# Commonly used in test setup
+RSpec.configure do |config|
+  config.before(:each) do
+    CMDx.reset_configuration!
+  end
+end
+```
+
+## Error Handling
+
+### Configuration Validation
+
+```ruby
+# Invalid configuration types
+CMDx.configure do |config|
+  config.task_halt = :invalid_type    # Error: must be String or Array
+  config.logger = "not_a_logger"      # Error: must respond to logging methods
+end
+```
+
+### Missing Settings Access
+
+```ruby
+class ExampleTask < CMDx::Task
+  def call
+    # Accessing non-existent setting
+    value = cmd_setting(:non_existent_setting)  #=> nil (returns nil for undefined)
+
+    # Check if setting exists
+    if cmd_setting(:custom_timeout)
+      timeout = cmd_setting(:custom_timeout)
+    else
+      timeout = 30  # fallback
+    end
+  end
+end
+```
+
+### Configuration Conflicts
+
+```ruby
+# Parent class configuration
+class BaseTask < CMDx::Task
+  cmd_settings!(task_halt: "failed", tags: ["base"])
+end
+
+# Child class inherits and overrides
+class SpecialTask < BaseTask
+  cmd_settings!(task_halt: ["failed", "skipped"])  # Overrides parent
+  # tags: ["base"] inherited from parent
+
+  def call
+    halt_statuses = cmd_setting(:task_halt)  #=> ["failed", "skipped"]
+    inherited_tags = cmd_setting(:tags)      #=> ["base"]
+  end
+end
 ```
 
+> [!IMPORTANT]
+> Settings inheritance follows Ruby's method resolution order. Child class settings always override parent class settings for the same key.
+
 ---
 
 - **Prev:** [Getting Started](getting_started.md)

data/docs/deprecation.md

@@ -0,0 +1,245 @@
+# Task Deprecation
+
+Task deprecation provides a systematic approach to managing legacy tasks in CMDx applications. The deprecation system enables controlled migration paths by issuing warnings, logging messages, or preventing execution of deprecated tasks entirely, helping teams maintain code quality while providing clear upgrade paths.
+
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Deprecation Fundamentals](#deprecation-fundamentals)
+- [Deprecation Modes](#deprecation-modes)
+- [Configuration Examples](#configuration-examples)
+- [Migration Strategies](#migration-strategies)
+- [Error Handling](#error-handling)
+- [Best Practices](#best-practices)
+
+## TLDR
+
+```ruby
+# Prevent task execution completely
+class LegacyTask < CMDx::Task
+  cmd_setting!(deprecated: :error)
+end
+
+# Log deprecation warnings
+class OldTask < CMDx::Task
+  cmd_setting!(deprecated: :log)
+end
+
+# Issue Ruby warnings
+class ObsoleteTask < CMDx::Task
+  cmd_setting!(deprecated: :warning)
+end
+
+# Usage triggers appropriate deprecation handling
+LegacyTask.call   # → raises DeprecationError
+OldTask.call      # → logs warning via task.logger
+ObsoleteTask.call # → issues Ruby warning
+```
+
+## Deprecation Fundamentals
+
+> [!NOTE]
+> Task deprecation is configured using the `cmd_setting!` declaration and processed automatically by CMDx before task execution. The deprecation system integrates seamlessly with existing logging and error handling infrastructure.
+
+### How It Works
+
+1. **Configuration**: Tasks declare deprecation mode using `cmd_setting!(deprecated: mode)`
+2. **Processing**: CMDx automatically calls `TaskDeprecator.call(task)` during task lifecycle
+3. **Action**: Appropriate deprecation handling occurs based on configured mode
+4. **Execution**: Task proceeds normally (unless `:error` mode prevents it)
+
+### Available Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `:error` | Raises `DeprecationError` | Hard deprecation, prevent execution |
+| `:log` | Logs warning via `task.logger.warn` | Soft deprecation, track usage |
+| `:warning` | Issues Ruby warning | Development alerts |
+| `true` | Same as `:log` | Legacy boolean support |
+| `nil/false` | No deprecation handling | Default behavior |
+
+## Deprecation Modes
+
+### Error Mode (Hard Deprecation)
+
+> [!WARNING]
+> Error mode prevents task execution entirely. Use this for tasks that should no longer be used under any circumstances.
+
+```ruby
+class ProcessLegacyPaymentTask < CMDx::Task
+  cmd_setting!(deprecated: :error)
+
+  def call
+    # This code will never execute
+    charge_customer(amount)
+  end
+end
+
+# Attempting to use deprecated task
+result = ProcessLegacyPaymentTask.call(amount: 100)
+# → raises CMDx::DeprecationError: "ProcessLegacyPaymentTask usage prohibited"
+```
+
+### Log Mode (Soft Deprecation)
+
+> [!TIP]
+> Log mode allows continued usage while tracking deprecation warnings. Perfect for gradual migration scenarios where immediate replacement isn't feasible.
+
+```ruby
+class ProcessOldPaymentTask < CMDx::Task
+  cmd_setting!(deprecated: :log)
+
+  def call
+    # Task executes normally but logs deprecation warning
+    charge_customer(amount)
+  end
+end
+
+# Task executes with logged warning
+result = ProcessOldPaymentTask.call(amount: 100)
+result.successful? # → true
+
+# Check logs for deprecation warning:
+# WARN -- : DEPRECATED: migrate to replacement or discontinue use
+```
+
+### Warning Mode (Development Alerts)
+
+> [!NOTE]
+> Warning mode issues Ruby warnings visible in development and testing environments. Useful for alerting developers without affecting production logging.
+
+```ruby
+class ProcessObsoletePaymentTask < CMDx::Task
+  cmd_setting!(deprecated: :warning)
+
+  def call
+    # Task executes with Ruby warning
+    charge_customer(amount)
+  end
+end
+
+# Task executes with Ruby warning
+result = ProcessObsoletePaymentTask.call(amount: 100)
+# stderr: [ProcessObsoletePaymentTask] DEPRECATED: migrate to replacement or discontinue use
+
+result.successful? # → true
+```
+
+## Configuration Examples
+
+### Environment-Specific Deprecation
+
+```ruby
+class ExperimentalFeatureTask < CMDx::Task
+  # Different deprecation behavior per environment
+  cmd_setting!(
+    deprecated: Rails.env.production? ? :error : :warning
+  )
+
+  def call
+    enable_experimental_feature
+  end
+end
+```
+
+### Conditional Deprecation
+
+```ruby
+class LegacyIntegrationTask < CMDx::Task
+  # Deprecate only for specific conditions
+  cmd_setting!(
+    deprecated: -> { ENV['NEW_API_ENABLED'] == 'true' ? :log : nil }
+  )
+
+  def call
+    call_legacy_api
+  end
+end
+```
+
+## Migration Strategies
+
+> [!IMPORTANT]
+> When deprecating tasks, always provide clear migration paths and replacement implementations to minimize disruption.
+
+### Graceful Fallback
+
+```ruby
+class NotificationTask < CMDx::Task
+  cmd_setting!(deprecated: :log)
+
+  def call
+    # Provide fallback while encouraging migration
+    logger.warn "Consider migrating to NotificationServiceV2"
+
+    # Delegate to new service but maintain compatibility
+    NotificationServiceV2.send_notification(
+      recipient: recipient,
+      message: message,
+      delivery_method: :legacy
+    )
+  end
+end
+```
+
+## Error Handling
+
+### Catching Deprecation Errors
+
+```ruby
+begin
+  result = LegacyTask.call(params)
+rescue CMDx::DeprecationError => e
+  # Handle deprecation gracefully
+  Rails.logger.error "Attempted to use deprecated task: #{e.message}"
+
+  # Use replacement task instead
+  result = ReplacementTask.call(params)
+end
+
+if result.successful?
+  # Process successful result
+else
+  # Handle task failure
+end
+```
+
+## Best Practices
+
+### Documentation and Communication
+
+> [!TIP]
+> Always document deprecation reasons, timelines, and migration paths. Clear communication prevents confusion and reduces support burden.
+
+```ruby
+class LegacyReportTask < CMDx::Task
+  # Document deprecation clearly
+  cmd_setting!(deprecated: :log)
+
+  # Class-level documentation
+  # @deprecated Use ReportGeneratorV2Task instead
+  # @see ReportGeneratorV2Task
+  # @note This task will be removed in v2.0.0
+  # @since 1.5.0 marked as deprecated
+
+  def call
+    # Add inline documentation
+    logger.warn <<~DEPRECATION
+      LegacyReportTask is deprecated and will be removed in v2.0.0.
+      Please migrate to ReportGeneratorV2Task which provides:
+      - Better performance
+      - Enhanced error handling
+      - More flexible output formats
+
+      Migration guide: https://docs.example.com/migration/reports
+    DEPRECATION
+
+    generate_legacy_report
+  end
+end
+```
+
+---
+
+- **Prev:** [Testing](testing.md)
+- **Next:** [AI Prompts](ai_prompts.md)