cmdx 0.5.0 → 1.0.1

data/docs/configuration.md

@@ -1,57 +1,182 @@
 # Configuration
 
-Configuration of tasks can be done at global and task levels.
+CMDx provides a flexible configuration system that allows customization at both global and task levels. Configuration follows a hierarchy where global settings serve as defaults that can be overridden at the task level.
 
-## Global settings
+## Table of Contents
 
-Run `rails g cmdx:install` to generate a configuration file within the
-`config/initializers` directory. These settings will be preloaded into all tasks.
+- [TLDR](#tldr)
+- [Configuration Hierarchy](#configuration-hierarchy)
+- [Global Configuration](#global-configuration)
+  - [Configuration Options](#configuration-options)
+  - [Global Middlewares](#global-middlewares)
+  - [Global Callbacks](#global-callbacks)
+- [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)
+
+## 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
+
+## Configuration Hierarchy
+
+CMDx follows a three-tier configuration hierarchy:
+
+1. **Global Configuration**: Framework-wide defaults
+2. **Task Settings**: Class-level overrides via `task_settings!`
+3. **Runtime Parameters**: Instance-specific overrides during execution
+
+> [!IMPORTANT]
+> Task-level settings take precedence over global configuration. Settings are inherited from superclasses and can be overridden in subclasses.
+
+## Global Configuration
+
+Generate a configuration file using the Rails generator:
+
+```bash
+rails g cmdx:install
+```
+
+This creates `config/initializers/cmdx.rb` with default settings.
+
+### Configuration Options
+
+| Option        | Type                  | Default        | Description |
+|---------------|-----------------------|----------------|-------------|
+| `task_halt`   | String, Array<String> | `"failed"`     | Result statuses that cause `call!` to raise faults |
+| `workflow_halt`  | String, Array<String> | `"failed"`     | Result statuses that halt workflow execution |
+| `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 |
+
+### Global Middlewares
+
+Configure middlewares that automatically apply to all tasks in your application:
 
 ```ruby
 CMDx.configure do |config|
-  # Define which statuses a bang `call!` will halt and raise a fault.
-  # This option can accept an array of statuses.
-  config.task_halt = CMDx::Result::FAILED
+  # Add middlewares without arguments
+  config.middlewares.use CMDx::Middlewares::Timeout
 
-  # Enable task timeouts to prevent call execution beyond a defined threshold.
-  config.task_timeout = nil
+  # Add middlewares with arguments
+  config.middlewares.use CMDx::Middlewares::Timeout, seconds: 30
 
-  # Define which statuses a batch task will halt execution from proceeding to the next step.
-  # By default skipped tasks are treated as a NOOP so processing is continued.
-  # This option can accept an array of statuses.
-  config.batch_halt = CMDx::Result::FAILED
+  # Add middleware instances
+  config.middlewares.use CMDx::Middlewares::Timeout.new(seconds: 30)
+end
+```
 
-  # Enable batch timeouts to prevent call execution beyond a defined threshold.
-  # TIP: remember to account for all defined tasks when setting this value
-  config.batch_timeout = nil
+### Global Callbacks
 
-  # A list of available log formatter can be found at:
-  # https://github.com/drexed/cmdx/tree/main/lib/cmdx/log_formatters
-  config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
+Configure callbacks that automatically apply to all tasks in your application:
+
+```ruby
+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|
+    Metrics.increment("task.#{task.class.name.underscore}.completed")
+  }
 end
 ```
 
-## Task settings
+## Task Settings
 
-Finely tune tasks via class level settings.
+Override global configuration for specific tasks or workflows using `task_settings!`:
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
-
-  # Task level settings:
-  task_settings!(task_timeout: 1, tags: ["v1", "DEPRECATED"])
+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
+  )
 
   def call
-    # Do work...
+    # Process payment logic
   end
+end
+```
+
+### Available Task Settings
+
+| Setting         | Type                  | Description |
+|-----------------|-----------------------|-------------|
+| `task_halt`     | String, Array<String> | Result statuses that cause `call!` to raise faults |
+| `workflow_halt`    | String, Array<String> | Result statuses that halt workflow execution |
+| `tags`          | Array<String>         | Tags automatically appended to logs |
+| `logger`        | Logger                | Custom logger instance |
+| `log_level`     | Symbol                | Log level (`:debug`, `:info`, `:warn`, `:error`, `:fatal`) |
+| `log_formatter` | LogFormatter          | Custom log formatter |
 
+### Workflow Configuration
+
+Configure halt behavior for workflows:
+
+```ruby
+class OrderProcessingWorkflow < CMDx::Workflow
+  # Strict workflow - halt on any failure
+  task_settings!(workflow_halt: ["failed", "skipped"])
+
+  process ValidateOrderTask
+  process ChargePaymentTask
+  process FulfillOrderTask
 end
 ```
 
-> [!NOTE]
-> `tags` is a task level setting only. Tags will automatically be appended to logs.
+## Configuration Management
+
+### 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>
+
+# Task-specific settings
+class AnalyzeDataTask < CMDx::Task
+  task_settings!(tags: ["analytics"])
+
+  def call
+    tags = task_setting(:tags)               # Gets ["analytics"]
+    halt_statuses = task_setting(:task_halt) # Gets global default
+  end
+end
+```
+
+### Resetting Configuration
+
+Reset configuration to defaults (useful for testing):
+
+```ruby
+CMDx.reset_configuration!
+CMDx.configuration.task_halt #=> "failed" (default)
+```
 
 ---
 
-- **Prev:** [Configuration](https://github.com/drexed/cmdx/blob/main/docs/configuration.md)
-- **Next:** [Basics - Setup](https://github.com/drexed/cmdx/blob/main/docs/basics/setup.md)
+- **Prev:** [Getting Started](getting_started.md)
+- **Next:** [Basics - Setup](basics/setup.md)

data/docs/getting_started.md

@@ -1,47 +1,170 @@
-# Getting Start
+# Getting Started
 
-`CMDx` is a framework for expressive processing of business logic.
+CMDx is a Ruby framework for building maintainable, observable business logic through composable
+command objects. Design robust workflows with automatic parameter validation, structured error
+handling, comprehensive logging, and intelligent execution flow control that scales from simple
+tasks to complex multi-step processes.
 
-Goals:
-- Provide easy branching, nesting, and composition of complex tasks
-- Supply intent, severity, and reasoning to halting execution of tasks
-- Demystify root causes of complex multi-level tasks with exhaustive tracing
+## Table of Contents
 
-## Setup
+- [TLDR](#tldr)
+- [Installation](#installation)
+- [Quick Setup](#quick-setup)
+- [Execution](#execution)
+- [Result Handling](#result-handling)
+- [Exception Handling](#exception-handling)
+- [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:
+
+```ruby
+gem 'cmdx'
+```
+
+For Rails applications, generate the configuration:
+
+```bash
+rails generate cmdx:install
+```
+
+> [!NOTE]
+> This creates `config/initializers/cmdx.rb` with default settings.
+
+## Quick Setup
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
+  required :order_id, type: :integer
+  optional :send_email, type: :boolean, default: true
 
   def call
-    fail!(reason: "Order was canceled") if context.order.canceled?
-    skip!(reason: "Order is processing") if context.order.processing?
+    context.order = Order.find(order_id)
 
-    inform_partner_warehouses
-    send_confirmation_email
+    if context.order.canceled?
+      fail!(reason: "Order canceled", canceled_at: context.order.canceled_at)
+    elsif context.order.completed?
+      skip!(reason: "Already processed")
+    else
+      context.order.update!(status: 'completed', completed_at: Time.now)
+      EmailService.send_confirmation(context.order) if send_email
+    end
   end
-
 end
 ```
 
+> [!TIP]
+> Use **present tense verbs** for clarity: `ProcessOrderTask`, `SendEmailTask`, `ValidatePaymentTask`
+
 ## Execution
 
+Execute tasks using class methods:
+
+```ruby
+# Returns Result object
+result = ProcessOrderTask.call(order_id: 123)
+
+# Raises exceptions on failure/skip, else returns Result object
+result = ProcessOrderTask.call!(order_id: 123, send_email: false)
+```
+
+## Result Handling
+
+Check execution outcomes:
+
+```ruby
+result = ProcessOrderTask.call(order_id: 123)
+
+case result.status
+when 'success'
+  redirect_to order_path(result.context.order), notice: "Order processed!"
+when 'skipped'
+  redirect_to order_path(result.context.order), notice: result.metadata[:reason]
+when 'failed'
+  redirect_to orders_path, alert: "Error: #{result.metadata[:reason]}"
+end
+
+# Access execution metadata
+puts "Runtime: #{result.runtime}s, Task ID: #{result.id}"
+```
+
+## Exception Handling
+
+Use `call!` for exception-based control flow:
+
 ```ruby
-result = ProcessOrderTask.call(order: order)
+begin
+  result = ProcessOrderTask.call!(order_id: 123)
+  redirect_to order_path(result.context.order), notice: "Success!"
+rescue CMDx::Skipped => e
+  redirect_to orders_path, notice: e.result.metadata[:reason]
+rescue CMDx::Failed => e
+  redirect_to order_path(123), alert: e.result.metadata[:reason]
+end
 ```
 
-## Result
+## Building Workflows
+
+Combine tasks using workflows:
 
 ```ruby
-if result.failed?
-  flash[:error] = "Failed! #{result.metadata[:reason]}"
-elsif result.skipped?
-  flash[:notice] = "FYI: #{result.metadata[:reason]}"
-else
-  flash[:success] = "Order successfully processed"
+class OrderProcessingWorkflow < CMDx::Workflow
+  required :order_id, type: :integer
+
+  before_execution :log_workflow_start
+  on_failed :notify_support
+
+  process ValidateOrderTask
+  process ChargePaymentTask
+  process UpdateInventoryTask
+  process SendConfirmationTask, if: proc { context.payment_successful? }
+
+  # NO call method
+
+  private
+
+  def log_workflow_start
+    Rails.logger.info "Starting order workflow for order #{order_id}"
+  end
+
+  def notify_support
+    SupportNotifier.alert("Order workflow failed", context: context.to_h)
+  end
 end
+
+result = ProcessOrderWorkflow.call(order_id: 123)
 ```
 
+## Code Generation
+
+Generate tasks and workflows with proper structure:
+
+```bash
+# Generate individual task
+rails generate cmdx:task ProcessOrder
+# Creates: app/cmds/process_order_task.rb
+
+# Generate task workflow
+rails generate cmdx:workflow OrderDeliveryWorkflow
+# Creates: app/cmds/order_delivery_workflow.rb
+```
+
+> [!NOTE]
+> Generators automatically handle naming conventions and inherit from `ApplicationTask`/`ApplicationWorkflow` when available.
+
 ---
 
-- **Prev:** [Example](https://github.com/drexed/cmdx/blob/main/docs/example.md)
-- **Next:** [Configuration](https://github.com/drexed/cmdx/blob/main/docs/configuration.md)
+- **Prev:** [Tips and Tricks](tips_and_tricks.md)
+- **Next:** [Configuration](configuration.md)

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)