cmdx 1.7.5 → 1.9.0

data/docs/getting_started.md

@@ -1,51 +1,33 @@
 # Getting Started
 
-CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. Design robust workflows with automatic attribute validation, structured error handling, comprehensive logging, and intelligent execution flow control.
-
-**Common Challenges:**
-
-- Inconsistent patterns across implementations
-- Minimal or no logging, making debugging painful
-- Fragile designs that erode developer confidence
-
-**CMDx Solutions:**
-
-- Establishes a consistent, standardized design
-- Provides flow control and error handling
-- Supports composable, reusable workflows
-- Includes detailed logging for observability
-- Defines input attributes with fallback defaults
-- Adds validations and type coercions
-- Plus many other developer-friendly tools
-
-## Table of Contents
-
-- [Compose, Execute, React, Observe pattern](#compose-execute-react-observe-pattern)
-- [Installation](#installation)
-- [Configuration Hierarchy](#configuration-hierarchy)
-- [Global Configuration](#global-configuration)
-  - [Breakpoints](#breakpoints)
-  - [Logging](#logging)
-  - [Middlewares](#middlewares)
-  - [Callbacks](#callbacks)
-  - [Coercions](#coercions)
-  - [Validators](#validators)
-- [Task Configuration](#task-configuration)
-  - [Settings](#settings)
-  - [Registrations](#registrations)
-- [Configuration Management](#configuration-management)
-  - [Access](#access)
-  - [Resetting](#resetting)
-- [Task Generator](#task-generator)
-
-## Compose, Execute, React, Observe pattern
-
-CMDx encourages breaking business logic into composable tasks. Each task can be combined into larger workflows, executed with standardized flow control, and fully observed through logging, validations, and context.
-
-- *Compose* → Define small, contract-driven tasks with typed attributes, validations, and natural workflow composition.
-- *Execute* → Run tasks with clear outcomes, intentional halts, and pluggable behaviors via middlewares and callbacks.
-- *React* → Adapt to outcomes by chaining follow-up tasks, handling faults, or shaping future flows.
-- *Observe* → Capture immutable results, structured logs, and full execution chains for reliable tracing and insight.
+CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. It brings structure, consistency, and powerful developer tools to your business processes.
+
+**Common challenges it solves:**
+
+- Inconsistent service object patterns across your codebase
+- Limited logging makes debugging a nightmare
+- Fragile error handling erodes confidence
+
+**What you get:**
+
+- Consistent, standardized architecture
+- Built-in flow control and error handling
+- Composable, reusable workflows
+- Comprehensive logging for observability
+- Attribute validation with type coercions
+- Sensible defaults and developer-friendly APIs
+
+## The CERO Pattern
+
+CMDx embraces the Compose, Execute, React, Observe (CERO) pattern—a simple yet powerful approach to building reliable business logic.
+
+🧩 **Compose** — Define small, focused tasks with typed attributes and validations
+
+⚡ **Execute** — Run tasks with clear outcomes and pluggable behaviors
+
+🔄 **React** — Adapt to outcomes by chaining follow-up tasks or handling faults
+
+🔍 **Observe** — Capture structured logs and execution chains for debugging
 
 ## Installation
 
@@ -65,39 +47,78 @@ This creates `config/initializers/cmdx.rb` file.
 
 ## Configuration Hierarchy
 
-CMDx follows a two-tier configuration hierarchy:
+CMDx uses a straightforward two-tier configuration system:
 
-1. **Global Configuration**: Framework-wide defaults
-2. **Task Settings**: Class-level overrides via `settings`
+1. **Global Configuration** — Framework-wide defaults
+2. **Task Settings** — Class-level overrides using `settings`
 
-> [!IMPORTANT]
-> Task-level settings take precedence over global configuration. Settings are inherited from superclasses and can be overridden in subclasses.
+!!! warning "Important"
+
+    Task settings take precedence over global config. Settings are inherited from parent classes and can be overridden in subclasses.
 
 ## Global Configuration
 
-Global configuration settings apply to all tasks inherited from `CMDx::Task`.
-Globally these settings are initialized with sensible defaults.
+Configure framework-wide defaults that apply to all tasks. These settings come with sensible defaults out of the box.
 
 ### Breakpoints
 
-Raise `CMDx::Fault` when a task called with `execute!` returns a matching status.
+Control when `execute!` raises a `CMDx::Fault` based on task status.
 
 ```ruby
 CMDx.configure do |config|
-  # String or Array[String]
-  config.task_breakpoints = "failed"
+  config.task_breakpoints = "failed" # String or Array[String]
 end
 ```
 
-Workflow breakpoints stops execution and of workflow pipeline on the first task that returns a matching status and throws its `CMDx::Fault`.
+For workflows, configure which statuses halt the execution pipeline:
 
 ```ruby
 CMDx.configure do |config|
-  # String or Array[String]
   config.workflow_breakpoints = ["skipped", "failed"]
 end
 ```
 
+### Backtraces
+
+Enable detailed backtraces for non-fault exceptions to improve debugging. Optionally clean up stack traces to remove framework noise.
+
+!!! note
+
+    In Rails environments, `backtrace_cleaner` defaults to `Rails.backtrace_cleaner.clean`.
+
+```ruby
+CMDx.configure do |config|
+  # Truthy
+  config.backtrace = true
+
+  # Via callable (must respond to `call(backtrace)`)
+  config.backtrace_cleaner = AdvanceCleaner.new
+
+  # Via proc or lambda
+  config.backtrace_cleaner = ->(backtrace) { backtrace[0..5] }
+end
+```
+
+### Exception Handlers
+
+Register handlers that run when non-fault exceptions occur.
+
+!!! tip
+
+    Use exception handlers to send errors to your APM of choice.
+
+```ruby
+CMDx.configure do |config|
+  # Via callable (must respond to `call(task, exception)`)
+  config.exception_handler = NewRelicReporter
+
+  # Via proc or lambda
+  config.exception_handler = proc do |task, exception|
+    APMService.report(exception, extra_data: { task: task.name, id: task.id })
+  end
+end
+```
+
 ### Logging
 
 ```ruby
@@ -108,7 +129,7 @@ end
 
 ### Middlewares
 
-See the [Middelwares](#https://github.com/drexed/cmdx/blob/main/docs/middlewares.md#declarations) docs for task level configurations.
+See the [Middlewares](middlewares.md#declarations) docs for task level configurations.
 
 ```ruby
 CMDx.configure do |config|
@@ -132,12 +153,13 @@ CMDx.configure do |config|
 end
 ```
 
-> [!NOTE]
-> Middlewares are executed in registration order. Each middleware wraps the next, creating an execution chain around task logic.
+!!! note
+
+    Middlewares are executed in registration order. Each middleware wraps the next, creating an execution chain around task logic.
 
 ### Callbacks
 
-See the [Callbacks](#https://github.com/drexed/cmdx/blob/main/docs/callbacks.md#declarations) docs for task level configurations.
+See the [Callbacks](callbacks.md#declarations) docs for task level configurations.
 
 ```ruby
 CMDx.configure do |config|
@@ -163,7 +185,7 @@ end
 
 ### Coercions
 
-See the [Attributes - Coercions](#https://github.com/drexed/cmdx/blob/main/docs/attributes/coercions.md#declarations) docs for task level configurations.
+See the [Attributes - Coercions](attributes/coercions.md#declarations) docs for task level configurations.
 
 ```ruby
 CMDx.configure do |config|
@@ -189,7 +211,7 @@ end
 
 ### Validators
 
-See the [Attributes - Validations](#https://github.com/drexed/cmdx/blob/main/docs/attributes/validations.md#declarations) docs for task level configurations.
+See the [Attributes - Validations](attributes/validations.md#declarations) docs for task level configurations.
 
 ```ruby
 CMDx.configure do |config|
@@ -224,6 +246,8 @@ class GenerateInvoice < CMDx::Task
     # Global configuration overrides
     task_breakpoints: ["failed"],                # Breakpoint override
     workflow_breakpoints: [],                    # Breakpoint override
+    backtrace: true,                             # Toggle backtrace
+    backtrace_cleaner: ->(bt) { bt[0..5] },      # Backtrace cleaner
     logger: CustomLogger.new($stdout),           # Custom logger
 
     # Task configuration settings
@@ -231,7 +255,10 @@ class GenerateInvoice < CMDx::Task
     log_level: :info,                            # Log level override
     log_formatter: CMDx::LogFormatters::Json.new # Log formatter override
     tags: ["billing", "financial"],              # Logging tags
-    deprecated: true                             # Task deprecations
+    deprecated: true,                            # Task deprecations
+    retries: 3,                                  # Non-fault exception retries
+    retry_on: [External::ApiError],              # List of exceptions to retry on
+    retry_jitter: 1                              # Space between retry iteration, eg: current retry num + 1
   )
 
   def work
@@ -240,13 +267,13 @@ class GenerateInvoice < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Use task-level settings for tasks that require special handling, such as financial reporting, external API integrations, or critical system operations.
+!!! warning "Important"
+
+    Retries reuse the same context. By default, all `StandardError` exceptions are retried unless you specify `retry_on`.
 
 ### Registrations
 
-Register middlewares, callbacks, coercions, and validators on a specific task.
-Deregister options that should not be available.
+Register or deregister middlewares, callbacks, coercions, and validators for specific tasks:
 
 ```ruby
 class SendCampaignEmail < CMDx::Task
@@ -298,8 +325,9 @@ end
 
 ### Resetting
 
-> [!WARNING]
-> Resetting configuration affects the entire application. Use primarily in test environments or during application initialization.
+!!! warning
+
+    Resetting affects your entire application. Use this primarily in test environments.
 
 ```ruby
 # Reset to framework defaults
@@ -336,10 +364,6 @@ class ModerateBlogPost < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Use **present tense verbs + noun** for task names, eg: `ModerateBlogPost`, `ScheduleAppointment`, `ValidateDocument`
-
----
+!!! tip
 
-- **Prev:** [Tips and Tricks](tips_and_tricks.md)
-- **Next:** [Basics - Setup](basics/setup.md)
+    Use **present tense verbs + noun** for task names, eg: `ModerateBlogPost`, `ScheduleAppointment`, `ValidateDocument`

data/docs/index.md

@@ -0,0 +1,120 @@
+# CMDx
+
+Build business logic that's powerful, predictable, and maintainable.
+
+[![Version](https://img.shields.io/gem/v/cmdx)](https://rubygems.org/gems/cmdx)
+[![Build](https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg)](https://github.com/drexed/cmdx/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/drexed/cmdx)](https://github.com/drexed/cmdx/blob/main/LICENSE.txt)
+
+Say goodbye to messy service objects. CMDx helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
+
+## Installation
+
+```sh
+gem install cmdx
+# - or -
+bundle add cmdx
+```
+
+## Quick Example
+
+Build powerful business logic in four simple steps:
+
+### 1. Compose
+
+=== "Full Featured Task"
+
+    ```ruby
+    class AnalyzeMetrics < CMDx::Task
+      register :middleware, CMDx::Middlewares::Correlate, id: -> { Current.request_id }
+
+      on_success :track_analysis_completion!
+
+      required :dataset_id, type: :integer, numeric: { min: 1 }
+      optional :analysis_type, default: "standard"
+
+      def work
+        if dataset.nil?
+          fail!("Dataset not found", code: 404)
+        elsif dataset.unprocessed?
+          skip!("Dataset not ready for analysis")
+        else
+          context.result = PValueAnalyzer.execute(dataset:, analysis_type:)
+          context.analyzed_at = Time.now
+
+          SendAnalyzedEmail.execute(user_id: Current.account.manager_id)
+        end
+      end
+
+      private
+
+      def dataset
+        @dataset ||= Dataset.find_by(id: dataset_id)
+      end
+
+      def track_analysis_completion!
+        dataset.update!(analysis_result_id: context.result.id)
+      end
+    end
+    ```
+
+=== "Minimum Viable Task"
+
+    ```ruby
+    class SendAnalyzedEmail < CMDx::Task
+      def work
+        user = User.find(context.user_id)
+        MetricsMailer.analyzed(user).deliver_now
+      end
+    end
+    ```
+
+### 2. Execute
+
+```ruby
+result = AnalyzeMetrics.execute(
+  dataset_id: 123,
+  "analysis_type" => "advanced"
+)
+```
+
+### 3. React
+
+```ruby
+if result.success?
+  puts "Metrics analyzed at #{result.context.analyzed_at}"
+elsif result.skipped?
+  puts "Skipping analyzation due to: #{result.reason}"
+elsif result.failed?
+  puts "Analyzation failed due to: #{result.reason} with code #{result.metadata[:code]}"
+end
+```
+
+### 4. Observe
+
+```log
+I, [2022-07-17T18:42:37.000000 #3784] INFO -- CMDx:
+index=1 chain_id="018c2b95-23j4-2kj3-32kj-3n4jk3n4jknf" type="Task" class="SendAnalyzedEmail" state="complete" status="success" metadata={runtime: 347}
+
+I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx:
+index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="AnalyzeMetrics" state="complete" status="success" metadata={runtime: 187}
+```
+
+Ready to dive in? Check out the [Getting Started](getting_started.md) guide to learn more.
+
+## Ecosystem
+
+- [cmdx-rspec](https://github.com/drexed/cmdx-rspec) - RSpec test matchers
+
+For backwards compatibility of certain functionality:
+
+- [cmdx-i18n](https://github.com/drexed/cmdx-i18n) - 85+ translations, `v1.5.0` - `v1.6.2`
+- [cmdx-parallel](https://github.com/drexed/cmdx-parallel) - Parallel workflow tasks, `v1.6.1` - `v1.6.2`
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/drexed/cmdx. We're committed to fostering a welcoming, collaborative community. Please follow our [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/docs/internationalization.md

@@ -1,17 +1,10 @@
 # Internationalization (i18n)
 
-CMDx provides comprehensive internationalization support for all error messages, attribute validation failures, coercion errors, and fault messages. All user-facing text is automatically localized based on the current `I18n.locale`, ensuring your applications can serve global audiences with native-language error reporting.
+CMDx supports 90+ languages out of the box for all error messages, validations, coercions, and faults. Error messages automatically adapt to the current `I18n.locale`, making it easy to build applications for global audiences.
 
-## Table of Contents
+## Usage
 
-- [Localization](#localization)
-- [Configuration](#configuration)
-  - [Local Copies](#local-copies)
-  - [Available Locales](#available-locales)
-
-## Localization
-
-CMDx automatically localizes all error messages based on the `I18n.locale` setting.
+All error messages are automatically localized based on your current locale:
 
 ```ruby
 class ProcessQuote < CMDx::Task
@@ -30,11 +23,11 @@ end
 
 ## Configuration
 
-Localization is handled by the `I18n` gem. In Rails applications, locales are loaded automatically and managed via the `I18n.available_locales` setting.
+CMDx uses the `I18n` gem for localization. In Rails, locales load automatically.
 
-### Local Copies
+### Copy Locale Files
 
-Execute the following command to copy any locale into the Rails applications `config/locales` directory:
+Copy locale files to your Rails application's `config/locales` directory:
 
 ```bash
 rails generate cmdx:locale [LOCALE]
@@ -131,8 +124,3 @@ rails generate cmdx:locale fr
 - zh-HK - Chinese (Hong Kong)
 - zh-TW - Chinese (Traditional)
 - zh-YUE - Chinese (Yue)
-
----
-
-- **Prev:** [Logging](logging.md)
-- **Next:** [Deprecation](deprecation.md)

data/docs/interruptions/exceptions.md

@@ -1,21 +1,16 @@
 # Interruptions - Exceptions
 
-CMDx provides robust exception handling that differs between the `execute` and `execute!` methods. Understanding how unhandled exceptions are processed is crucial for building reliable task execution flows and implementing proper error handling strategies.
-
-## Table of Contents
-
-- [Exception Handling](#exception-handling)
-  - [Non-bang execution](#non-bang-execution)
-  - [Bang execution](#bang-execution)
+Exception handling differs between `execute` and `execute!`. Choose the method that matches your error handling strategy.
 
 ## Exception Handling
 
-> [!IMPORTANT]
-> When designing tasks try not to `raise` your own exceptions directly, instead use `skip!` or `fail!` to signal intent clearly.
+!!! warning "Important"
+
+    Prefer `skip!` and `fail!` over raising exceptions—they signal intent more clearly.
 
 ### Non-bang execution
 
-The `execute` method captures **all** unhandled exceptions and converts them to failed results, ensuring predictable behavior and consistent result processing.
+Captures all exceptions and returns them as failed results:
 
 ```ruby
 class CompressDocument < CMDx::Task
@@ -33,9 +28,13 @@ result.reason   #=> "[ActiveRecord::NotFoundError] record not found"
 result.cause    #=> <ActiveRecord::NotFoundError>
 ```
 
+!!! note
+
+    Use `exception_handler` with `execute` to send exceptions to APM tools before they become failed results.
+
 ### Bang execution
 
-The `execute!` method allows unhandled exceptions to propagate, enabling standard Ruby exception handling while respecting CMDx fault configuration.
+Lets exceptions propagate naturally for standard Ruby error handling:
 
 ```ruby
 class CompressDocument < CMDx::Task
@@ -51,8 +50,3 @@ rescue ActiveRecord::NotFoundError => e
   puts "Handle exception: #{e.message}"
 end
 ```
-
----
-
-- **Prev:** [Interruptions - Faults](faults.md)
-- **Next:** [Outcomes - Result](../outcomes/result.md)

data/docs/interruptions/faults.md

@@ -1,19 +1,6 @@
 # Interruptions - Faults
 
-Faults are exception mechanisms that halt task execution via `skip!` and `fail!` methods. When tasks execute with the `execute!` method, fault exceptions matching the task's interruption status are raised, enabling sophisticated exception handling and control flow patterns.
-
-## Table of Contents
-
-- [Fault Types](#fault-types)
-- [Fault Handling](#fault-handling)
-- [Data Access](#data-access)
-- [Advanced Matching](#advanced-matching)
-  - [Task-Specific Matching](#task-specific-matching)
-  - [Custom Logic Matching](#custom-logic-matching)
-- [Fault Propagation](#fault-propagation)
-  - [Basic Propagation](#basic-propagation)
-  - [Additional Metadata](#additional-metadata)
-- [Chain Analysis](#chain-analysis)
+Faults are exceptions raised by `execute!` when tasks halt. They carry rich context about execution state, enabling sophisticated error handling patterns.
 
 ## Fault Types
 
@@ -23,8 +10,9 @@ Faults are exception mechanisms that halt task execution via `skip!` and `fail!`
 | `CMDx::SkipFault` | `skip!` method | Optional processing, early returns |
 | `CMDx::FailFault` | `fail!` method | Validation errors, processing failures |
 
-> [!IMPORTANT]
-> All fault exceptions inherit from `CMDx::Fault` and provide access to the complete task execution context including result, task, context, and chain information.
+!!! warning "Important"
+
+    All faults inherit from `CMDx::Fault` and expose result, task, context, and chain data.
 
 ## Fault Handling
 
@@ -45,7 +33,7 @@ end
 
 ## Data Access
 
-Faults provide comprehensive access to execution context, eg:
+Access rich execution data from fault exceptions:
 
 ```ruby
 begin
@@ -74,7 +62,7 @@ end
 
 ### Task-Specific Matching
 
-Use `for?` to handle faults only from specific task classes, enabling targeted exception handling in complex workflows.
+Handle faults only from specific tasks using `for?`:
 
 ```ruby
 begin
@@ -104,7 +92,7 @@ end
 
 ## Fault Propagation
 
-Use `throw!` to propagate failures while preserving fault context and maintaining the error chain for debugging.
+Propagate failures with `throw!` to preserve context and maintain the error chain:
 
 ### Basic Propagation
 
@@ -151,7 +139,7 @@ end
 
 ## Chain Analysis
 
-Results provide methods to analyze fault propagation and identify original failure sources in complex execution chains.
+Trace fault origins and propagation through the execution chain:
 
 ```ruby
 result = DocumentWorkflow.execute(invalid_data)
@@ -179,8 +167,3 @@ if result.failed?
   end
 end
 ```
-
----
-
-- **Prev:** [Interruptions - Halt](halt.md)
-- **Next:** [Interruptions - Exceptions](exceptions.md)

data/docs/interruptions/halt.md

@@ -1,24 +1,14 @@
 # Interruptions - Halt
 
-Halting stops task execution with explicit intent signaling. Tasks provide two primary halt methods that control execution flow and result in different outcomes.
-
-## Table of Contents
-
-- [Skipping](#skipping)
-- [Failing](#failing)
-- [Metadata Enrichment](#metadata-enrichment)
-- [State Transitions](#state-transitions)
-- [Execution Behavior](#execution-behavior)
-  - [Non-bang execution](#non-bang-execution)
-  - [Bang execution](#bang-execution)
-- [Best Practices](#best-practices)
+Stop task execution intentionally using `skip!` or `fail!`. Both methods signal clear intent about why execution stopped.
 
 ## Skipping
 
-`skip!` communicates that the task is to be intentionally bypassed. This represents a controlled, intentional interruption where the task determines that execution is not necessary or appropriate.
+Use `skip!` when the task doesn't need to run. It's a no-op, not an error.
 
-> [!IMPORTANT]
-> Skipping is a no-op, not a failure or error and are considered successful outcomes.
+!!! warning "Important"
+
+    Skipped tasks are considered "good" outcomes—they succeeded by doing nothing.
 
 ```ruby
 class ProcessInventory < CMDx::Task
@@ -45,7 +35,7 @@ result = ProcessInventory.execute(inventory_id: 456)
 result.status #=> "skipped"
 
 # Without a reason
-result.reason #=> "No reason given"
+result.reason #=> "Unspecified"
 
 # With a reason
 result.reason #=> "Warehouse closed"
@@ -53,7 +43,7 @@ result.reason #=> "Warehouse closed"
 
 ## Failing
 
-`fail!` communicates that the task encountered an impediment that prevents successful completion. This represents controlled failure where the task explicitly determines that execution cannot continue.
+Use `fail!` when the task can't complete successfully. It signals controlled, intentional failure:
 
 ```ruby
 class ProcessRefund < CMDx::Task
@@ -80,7 +70,7 @@ result = ProcessRefund.execute(refund_id: 789)
 result.status #=> "failed"
 
 # Without a reason
-result.reason #=> "No reason given"
+result.reason #=> "Unspecified"
 
 # With a reason
 result.reason #=> "Refund period has expired"
@@ -88,7 +78,7 @@ result.reason #=> "Refund period has expired"
 
 ## Metadata Enrichment
 
-Both halt methods accept metadata to provide additional context about the interruption. Metadata is stored as a hash and becomes available through the result object.
+Enrich halt calls with metadata for better debugging and error handling:
 
 ```ruby
 class ProcessRenewal < CMDx::Task
@@ -188,7 +178,7 @@ end
 
 ## Best Practices
 
-Always try to provide a `reason` when using halt methods. This provides clear context for debugging and creates meaningful exception messages.
+Always provide a reason for better debugging and clearer exception messages:
 
 ```ruby
 # Good: Clear, specific reason
@@ -200,11 +190,27 @@ skip!("Paused")
 fail!("Unsupported")
 
 # Bad: Default, cannot determine reason
-skip! #=> "No reason given"
-fail! #=> "No reason given"
+skip! #=> "Unspecified"
+fail! #=> "Unspecified"
 ```
 
----
+## Manual Errors
+
+For rare cases, manually add errors before halting:
 
-- **Prev:** [Basics - Chain](../basics/chain.md)
-- **Next:** [Interruptions - Faults](faults.md)
+!!! warning "Important"
+
+    Manual errors don't stop execution—you still need to call `fail!` or `skip!`.
+
+```ruby
+class ProcessRenewal < CMDx::Task
+  def work
+    if document.nonrenewable?
+      errors.add(:document, "not renewable")
+      fail!("document could not be renewed")
+    else
+      document.renew!
+    end
+  end
+end
+```