cmdx 1.0.0 → 1.1.0

data/docs/configuration.md

@@ -4,11 +4,14 @@ CMDx provides a flexible configuration system that allows customization at both
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Configuration Hierarchy](#configuration-hierarchy)
 - [Global Configuration](#global-configuration)
   - [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)
@@ -16,12 +19,21 @@ CMDx provides a flexible configuration system that allows customization at both
   - [Accessing Configuration](#accessing-configuration)
   - [Resetting Configuration](#resetting-configuration)
 
+## 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
+
 ## 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]
@@ -35,22 +47,7 @@ Generate a configuration file using the Rails generator:
 rails g cmdx:install
 ```
 
-This creates `config/initializers/cmdx.rb` with default settings:
-
-```ruby
-CMDx.configure do |config|
-  # Halt execution and raise fault on these result statuses when using `call!`
-  config.task_halt = CMDx::Result::FAILED
-
-  # Stop workflow execution when tasks return these statuses
-  # Note: Skipped tasks continue processing by default
-  config.workflow_halt = CMDx::Result::FAILED
-
-  # Logger with formatter - see available formatters at:
-  # https://github.com/drexed/cmdx/tree/main/lib/cmdx/log_formatters
-  config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
-end
-```
+This creates `config/initializers/cmdx.rb` with default settings.
 
 ### Configuration Options
 
@@ -61,6 +58,8 @@ end
 | `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
 
@@ -87,30 +86,70 @@ Configure callbacks that automatically apply to all tasks in your application:
 CMDx.configure do |config|
   # Add method callbacks
   config.callbacks.register :before_execution, :log_task_start
-  config.callbacks.register :after_execution, :log_task_end
 
   # Add callback instances
   config.callbacks.register :on_success, NotificationCallback.new([:slack])
-  config.callbacks.register :on_failure, AlertCallback.new(severity: :critical)
 
   # Add conditional callbacks
   config.callbacks.register :on_failure, :page_admin, if: :production?
-  config.callbacks.register :before_validation, :skip_validation, unless: :validate_params?
 
   # Add proc callbacks
-  config.callbacks.register :on_complete, proc { |task, callback_type|
+  config.callbacks.register :on_complete, proc { |task, type|
     Metrics.increment("task.#{task.class.name.underscore}.completed")
   }
 end
 ```
 
+### Global Coercions
+
+Configure custom coercions that automatically apply to all tasks in your application:
+
+```ruby
+CMDx.configure do |config|
+  # Add custom coercion classes
+  config.coercions.register :money, MoneyCoercion
+
+  # Add complex coercions with options support
+  config.coercions.register :tags, proc { |value, options|
+    separator = options[:separator] || ','
+    max_tags = options[:max_tags] || 10
+
+    tags = value.to_s.split(separator).map(&:strip).reject(&:empty?)
+    tags = tags.first(max_tags) if max_tags
+    tags.uniq
+  }
+end
+```
+
+### Global Validators
+
+Configure validators that automatically apply to all tasks in your application:
+
+```ruby
+CMDx.configure do |config|
+  # Add validator classes
+  config.validators.register :email, EmailValidator
+
+  # 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
+  }
+end
+```
+
 ## Task Settings
 
-Override global configuration for specific tasks or workflows using `task_settings!`:
+Override global configuration for specific tasks or workflows using `cmd_settings!`:
 
 ```ruby
 class ProcessPaymentTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     task_halt: ["failed"],                       # Only halt on failures
     tags: ["payments", "critical"],              # Add logging tags
     logger: Rails.logger,                        # Use Rails logger
@@ -142,7 +181,7 @@ Configure halt behavior for workflows:
 ```ruby
 class OrderProcessingWorkflow < CMDx::Workflow
   # Strict workflow - halt on any failure
-  task_settings!(workflow_halt: ["failed", "skipped"])
+  cmd_settings!(workflow_halt: ["failed", "skipped"])
 
   process ValidateOrderTask
   process ChargePaymentTask
@@ -160,14 +199,16 @@ 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>
 
 # Task-specific settings
 class AnalyzeDataTask < CMDx::Task
-  task_settings!(tags: ["analytics"])
+  cmd_settings!(tags: ["analytics"])
 
   def call
-    tags = task_setting(:tags)               # Gets ["analytics"]
-    halt_statuses = task_setting(:task_halt) # Gets global default
+    tags = cmd_setting(:tags)               # Gets ["analytics"]
+    halt_statuses = cmd_setting(:task_halt) # Gets global default
   end
 end
 ```

data/docs/getting_started.md

@@ -7,6 +7,7 @@ tasks to complex multi-step processes.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Installation](#installation)
 - [Quick Setup](#quick-setup)
 - [Execution](#execution)
@@ -15,6 +16,16 @@ tasks to complex multi-step processes.
 - [Building Workflows](#building-workflows)
 - [Code Generation](#code-generation)
 
+## TLDR
+
+- **Installation** - Add `gem 'cmdx'` to Gemfile, run `rails g cmdx:install`
+- **Tasks** - Ruby classes inheriting from `CMDx::Task` with `call` method
+- **Execution** - Use `call` (returns result) or `call!` (raises on failure/skip)
+- **Parameters** - Define with `required`/`optional` with type coercion and validation
+- **Results** - Check `result.status` for success/skipped/failed outcomes
+- **Workflows** - Orchestrate multiple tasks with `CMDx::Workflow`
+- **Generators** - Use `rails g cmdx:task` and `rails g cmdx:workflow` for scaffolding
+
 ## Installation
 
 Add CMDx to your Gemfile:

data/docs/internationalization.md

@@ -0,0 +1,148 @@
+# Internationalization (i18n)
+
+CMDx provides comprehensive internationalization support for all error messages, including parameter coercion errors, validation failures, and fault messages. All error text is automatically localized based on the current `I18n.locale`.
+
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Available Locales](#available-locales)
+- [Fault Messages](#fault-messages)
+- [Parameter Messages](#parameter-messages)
+- [Coercion Messages](#coercion-messages)
+- [Validation Messages](#validation-messages)
+
+## TLDR
+
+- **24 languages** - Built-in translations for major world languages
+- **Automatic localization** - Based on `I18n.locale` setting
+- **Complete coverage** - Coercion errors, validation failures, and fault messages
+- **Custom overrides** - Parameter-specific messages override locale defaults
+
+## Available Locales
+
+CMDx includes built-in translations for 24 languages:
+
+| Language | Locale | Language | Locale |
+|----------|--------|----------|--------|
+| English | `:en` | Russian | `:ru` |
+| Spanish | `:es` | Arabic | `:ar` |
+| French | `:fr` | Korean | `:ko` |
+| German | `:de` | Dutch | `:nl` |
+| Portuguese | `:pt` | Swedish | `:sv` |
+| Italian | `:it` | Hindi | `:hi` |
+| Japanese | `:ja` | Polish | `:pl` |
+| Chinese | `:zh` | Turkish | `:tr` |
+| Norwegian | `:no` | Danish | `:da` |
+| Finnish | `:fi` | Greek | `:el` |
+| Hebrew | `:he` | Thai | `:th` |
+| Vietnamese | `:vi` | Czech | `:cs` |
+
+## Fault Messages
+
+Default fault messages from `skip!` and `fail!` methods are localized:
+
+```ruby
+class ProcessPaymentTask < CMDx::Task
+  def call
+    # When no reason is provided, uses localized default
+    fail! if payment_declined?
+  end
+end
+
+# English
+I18n.locale = :en
+result = ProcessPaymentTask.call(payment_id: 123)
+result.metadata[:reason] #=> "no reason given"
+
+# Chinese
+I18n.locale = :zh
+result = ProcessPaymentTask.call(payment_id: 123)
+result.metadata[:reason] #=> "未提供原因"
+```
+
+## Parameter Messages
+
+Parameter required or undefined source errors are automatically localized:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+  required :order_id, type: :integer
+  optional :user_name, source: :nonexistent_method
+
+  def call
+    # Task implementation
+  end
+end
+
+# English locale
+I18n.locale = :en
+result = ProcessOrderTask.call({}) # Missing required parameter
+result.metadata[:messages][:order_id] #=> ["is a required parameter"]
+
+result = ProcessOrderTask.call(order_id: 123) # Undefined source method
+result.metadata[:messages][:user_name] #=> ["delegates to undefined method nonexistent_method"]
+
+# Spanish locale
+I18n.locale = :es
+result = ProcessOrderTask.call({}) # Missing required parameter
+result.metadata[:messages][:order_id] #=> ["es un parámetro requerido"]
+
+result = ProcessOrderTask.call(order_id: 123) # Undefined source method
+result.metadata[:messages][:user_name] #=> ["delegado al método indefinido nonexistent_method"]
+```
+
+## Coercion Messages
+
+Type conversion errors are automatically localized:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+  required :order_id, type: :integer
+  required :amount, type: :float
+
+  def call
+    # Task implementation
+  end
+end
+
+# English
+I18n.locale = :en
+result = ProcessOrderTask.call(order_id: "invalid", amount: "bad")
+result.metadata[:messages][:order_id] #=> ["could not coerce into an integer"]
+
+# Spanish
+I18n.locale = :es
+result = ProcessOrderTask.call(order_id: "invalid", amount: "bad")
+result.metadata[:messages][:order_id] #=> ["no podía coacciona el valor a un integer"]
+```
+
+## Validation Messages
+
+All validator error messages support internationalization:
+
+```ruby
+class RegisterUserTask < CMDx::Task
+  required :email, format: { with: /@/ }
+  required :age, numeric: { min: 18 }
+  required :status, inclusion: { in: %w[active inactive] }
+
+  def call
+    # Task implementation
+  end
+end
+
+# English
+I18n.locale = :en
+result = RegisterUserTask.call(email: "invalid", age: 16, status: "unknown")
+result.metadata[:messages][:email] #=> ["is an invalid format"]
+
+# Japanese
+I18n.locale = :ja
+result = RegisterUserTask.call(email: "invalid", age: 16, status: "unknown")
+result.metadata[:messages][:email] #=> ["無効な形式です"]
+```
+
+---
+
+- **Prev:** [Logging](logging.md)
+- **Next:** [Testing](testing.md)

data/docs/interruptions/exceptions.md

@@ -6,10 +6,19 @@ building reliable task execution flows and implementing proper error handling st
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Exception Handling Behavior](#exception-handling-behavior)
 - [Bang Call (`call!`)](#bang-call-call)
 - [Exception Classification](#exception-classification)
 
+## TLDR
+
+- **`call`** - Captures ALL exceptions, converts to failed results with metadata
+- **`call!`** - Lets exceptions propagate (except CMDx faults based on task_halt config)
+- **Exception info** - Available in `result.metadata[:original_exception]` and `result.metadata[:reason]`
+- **Guaranteed results** - `call` always returns a result object, never raises
+- **Fault vs Exception** - CMDx faults have special handling, other exceptions propagate in `call!`
+
 ## Exception Handling Behavior
 
 ### Non-bang Call (`call`)
@@ -178,7 +187,7 @@ CMDx faults have special handling in both call methods:
 ```ruby
 class ProcessOrderWithHaltTask < CMDx::Task
   # Configure to halt on failures
-  task_settings!(task_halt: [CMDx::Result::FAILED])
+  cmd_settings!(task_halt: [CMDx::Result::FAILED])
 
   def call
     fail!(reason: "This is a controlled failure")

data/docs/interruptions/faults.md

@@ -7,6 +7,7 @@ sophisticated exception handling and control flow patterns.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Fault Types](#fault-types)
 - [Basic Exception Handling](#basic-exception-handling)
 - [Fault Context Access](#fault-context-access)
@@ -15,6 +16,14 @@ sophisticated exception handling and control flow patterns.
 - [Fault Chain Analysis](#fault-chain-analysis)
 - [Task Halt Configuration](#task-halt-configuration)
 
+## TLDR
+
+- **Fault types** - `CMDx::Skipped` (from `skip!`) and `CMDx::Failed` (from `fail!`)
+- **Exception handling** - Use `rescue CMDx::Fault` to catch both types
+- **Full context** - Faults provide access to `result`, `task`, `context`, and `chain`
+- **Advanced matching** - Use `for?(TaskClass)` and `matches? { |f| condition }` for specific fault handling
+- **Propagation** - Use `throw!(result)` to bubble up failures while preserving fault context
+
 ## Fault Types
 
 CMDx provides two primary fault types that inherit from the base `CMDx::Fault` class:
@@ -204,7 +213,7 @@ Control which statuses raise exceptions using the `task_halt` setting:
 ```ruby
 class ProcessUserOrderTask < CMDx::Task
   # Only failed tasks raise exceptions on call!
-  task_settings!(task_halt: [CMDx::Result::FAILED])
+  cmd_settings!(task_halt: [CMDx::Result::FAILED])
 
   def call
     skip!(reason: "Order already processed") if already_processed?
@@ -214,7 +223,7 @@ end
 
 class ValidateUserDataTask < CMDx::Task
   # Both failed and skipped tasks raise exceptions
-  task_settings!(task_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
+  cmd_settings!(task_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
 
   def call
     skip!(reason: "Validation not required") if skip_validation?

data/docs/interruptions/halt.md

@@ -6,6 +6,7 @@ outcomes, each serving specific use cases in business logic.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Skip (`skip!`)](#skip-skip)
 - [Fail (`fail!`)](#fail-fail)
 - [Metadata Enrichment](#metadata-enrichment)
@@ -13,6 +14,14 @@ outcomes, each serving specific use cases in business logic.
 - [Exception Behavior](#exception-behavior)
 - [The Reason Key](#the-reason-key)
 
+## TLDR
+
+- **`skip!`** - Controlled interruption when task shouldn't execute (not an error)
+- **`fail!`** - Controlled interruption when task encounters an error condition
+- **Metadata** - Both methods accept metadata hash: `skip!(reason: "...", error_code: "...")`
+- **State changes** - Both transition to `interrupted` state, `skipped` or `failed` status
+- **Exception behavior** - `call` returns results, `call!` raises `CMDx::Skipped/Failed` based on task_halt config
+
 ## Skip (`skip!`)
 
 The `skip!` method indicates that a task did not meet the criteria to continue

data/docs/logging.md

@@ -3,6 +3,7 @@
 CMDx provides comprehensive automatic logging for task execution with structured data, customizable formatters, and intelligent severity mapping. All task results are logged after completion with rich metadata for debugging and monitoring.
 
 ## Table of Contents
+- [TLDR](#tldr)
 - [Log Formatters](#log-formatters)
   - [Standard Formatters](#standard-formatters)
   - [Stylized Formatters (ANSI Colors)](#stylized-formatters-ansi-colors)
@@ -22,6 +23,15 @@ CMDx provides comprehensive automatic logging for task execution with structured
   - [Multi-Destination Logging](#multi-destination-logging)
 - [Log Data Structure](#log-data-structure)
 
+## TLDR
+
+- **Automatic logging** - All task results logged after completion with structured data
+- **8 formatters** - Standard (Line, Json, KeyValue, Logstash, Raw) and Stylized (Pretty variants)
+- **Configuration** - Global via `CMDx.configure` or task-specific via `cmd_settings!`
+- **Severity mapping** - Success=INFO, Skipped=WARN, Failed=ERROR
+- **Rich metadata** - Includes runtime, chain_id, status, context, and failure chains
+- **Manual logging** - Access `logger` within tasks for custom messages
+
 ## Log Formatters
 
 CMDx provides 8 built-in log formatters organized into standard and stylized categories:
@@ -83,7 +93,7 @@ Override logging settings for individual tasks:
 
 ```ruby
 class SendEmailTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     logger: Rails.logger,
     log_formatter: CMDx::LogFormatters::Json.new,
     log_level: Logger::WARN
@@ -96,7 +106,7 @@ end
 
 # Base class with shared logging configuration
 class ApplicationTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     logger: Logger.new("log/tasks.log"),
     log_formatter: CMDx::LogFormatters::Logstash.new,
     log_level: Logger::INFO
@@ -169,7 +179,7 @@ class SlackLogFormatter
 end
 
 class SendNotificationTask < CMDx::Task
-  task_settings!(
+  cmd_settings!(
     logger: Logger.new("log/notifications.log", formatter: SlackLogFormatter.new)
   )
 end
@@ -242,4 +252,4 @@ CMDx logs contain comprehensive execution metadata:
 ---
 
 - **Prev:** [Workflows](workflows.md)
-- **Next:** [Testing](testing.md)
+- **Next:** [Internationalization (i18n)](internationalization.md)