cmdx 1.0.1 → 1.1.1

data/docs/configuration.md

@@ -10,28 +10,46 @@ CMDx provides a flexible configuration system that allows customization at both
   - [Configuration Options](#configuration-options)
   - [Global Middlewares](#global-middlewares)
   - [Global Callbacks](#global-callbacks)
+  - [Global Coercions](#global-coercions)
+  - [Global Validators](#global-validators)
 - [Task Settings](#task-settings)
   - [Available Task Settings](#available-task-settings)
   - [Workflow Configuration](#workflow-configuration)
 - [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 `task_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
 
 CMDx follows a three-tier configuration hierarchy:
 
 1. **Global Configuration**: Framework-wide defaults
-2. **Task Settings**: Class-level overrides via `task_settings!`
+2. **Task Settings**: Class-level overrides via `cmd_settings!`
 3. **Runtime Parameters**: Instance-specific overrides during execution
 
 > [!IMPORTANT]
@@ -45,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
 
@@ -56,65 +74,117 @@ This creates `config/initializers/cmdx.rb` with default settings.
 | `logger`      | Logger                | Line formatter | Logger instance for task execution logging |
 | `middlewares` | MiddlewareRegistry    | Empty registry | Global middleware registry applied to all tasks |
 | `callbacks`   | CallbackRegistry      | Empty registry | Global callback registry applied to all tasks |
+| `coercions`   | CoercionRegistry      | Built-in coercions | Global coercion registry for custom parameter types |
+| `validators`  | ValidatorRegistry     | Built-in validators | Global validator registry for parameter validation |
 
 ### 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|
+  # Method callbacks
+  config.callbacks.register :before_execution, :setup_request_context
+  config.callbacks.register :after_execution, :cleanup_temp_files
+
+  # Conditional callbacks
+  config.callbacks.register :on_failure, :notify_admin, if: :production?
+  config.callbacks.register :on_success, :update_metrics, unless: :test?
+
+  # Proc callbacks with context
+  config.callbacks.register :on_complete, proc { |task, type|
+    duration = task.metadata[:runtime]
+    StatsD.histogram("task.duration", duration, tags: ["class:#{task.class.name}"])
+  }
+end
+```
+
+### Global Coercions
+
+Configure custom coercions for domain-specific types:
 
 ```ruby
 CMDx.configure do |config|
-  # Add method callbacks
-  config.callbacks.register :before_execution, :log_task_start
-  config.callbacks.register :after_execution, :log_task_end
+  # Simple coercion classes
+  config.coercions.register :money, MoneyCoercion
+  config.coercions.register :email, EmailCoercion
+
+  # Complex coercions with options
+  config.coercions.register :csv_array, proc { |value, options|
+    separator = options[:separator] || ','
+    max_items = options[:max_items] || 100
+
+    items = value.to_s.split(separator).map(&:strip).reject(&:empty?)
+    items.first(max_items)
+  }
+end
+```
+
+### Global Validators
 
-  # Add callback instances
-  config.callbacks.register :on_success, NotificationCallback.new([:slack])
-  config.callbacks.register :on_failure, AlertCallback.new(severity: :critical)
+Configure custom validators for parameter validation:
 
-  # Add conditional callbacks
-  config.callbacks.register :on_failure, :page_admin, if: :production?
-  config.callbacks.register :before_validation, :skip_validation, unless: :validate_params?
+```ruby
+CMDx.configure do |config|
+  # Validator classes
+  config.validators.register :email, EmailValidator
+  config.validators.register :phone, PhoneValidator
+
+  # 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
 
-  # Add proc callbacks
-  config.callbacks.register :on_complete, proc { |task, callback_type|
-    Metrics.increment("task.#{task.class.name.underscore}.completed")
+    value.start_with?(required_prefix) && value.length >= min_length
   }
 end
 ```
 
 ## Task Settings
 
-Override global configuration for specific tasks or workflows using `task_settings!`:
+Override global configuration for specific tasks using `cmd_settings!`:
 
 ```ruby
 class ProcessPaymentTask < CMDx::Task
-  task_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
+  cmd_settings!(
+    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
 ```
@@ -130,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
-  task_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
 ```
 
@@ -150,32 +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>
+# 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
-  task_settings!(tags: ["analytics"])
+class DataProcessingTask < CMDx::Task
+  cmd_settings!(
+    tags: ["data", "analytics"],
+    task_halt: ["failed", "skipped"]
+  )
 
   def call
-    tags = task_setting(:tags)               # Gets ["analytics"]
-    halt_statuses = task_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)