cmdx 1.7.1 → 1.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bbf1d8db7665b82da9af2dd5e017977945bbd550700177368b1363a8e63275e
-  data.tar.gz: 0f1720432a999ff31399d67c602e5277ee8cb1a8062117165c425a39233eb81c
+  metadata.gz: 528f3b3b1d4f23045a295cc15c05106c3bd0f9efde6400bb88c01bb2a6455637
+  data.tar.gz: 473ca317fd214b48e4e4988ba4358bdcff4a3fc9f9805300dba292f4401e51c1
 SHA512:
-  metadata.gz: 144c01abf663258e34b40eaa9e1deba09b59347b97773237f9bd84f5d82474825aca38f21b6ad0c052f1b058f6a5550e24ef8f3598da4cdecad94da1689bea5c
-  data.tar.gz: 25220966f85607b73740107b5af5da7889e75592055ad17156bc48f157550e2d030f542b7f279ec731cbb78ef732be1c6507b8e448a97a8324749d4746549d95
+  metadata.gz: 5b48be81fa184343f76c1891a3b87c25853e0dc859764dbf92946c7b31d69fd4af85b75eee7720470e29949edb395bce668343dbc6b17916079ba9befd1fbc80
+  data.tar.gz: b95fe96f12cf2aeb724782808d80b4ee36e083d0f6c60876edac45a6046c7925437f329dc2f98a42432b4794996c3269f71ba7f93452f161a38f365c6d40afa6

data/CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [TODO]
 
+## [1.7.2] - 2025-09-03
+
+### Changes
+- Correlation ID is set before continuing to further steps
+
 ## [1.7.1] - 2025-08-26
 
 ### Added

data/LLM.md

@@ -11,6 +11,31 @@ url: https://github.com/drexed/cmdx/blob/main/docs/getting_started.md
 
 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
+
+## 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.
+
 ## Installation
 
 Add CMDx to your Gemfile:
@@ -2743,21 +2768,19 @@ Sample output:
 ```log
 <!-- Success (INFO level) -->
 I, [2022-07-17T18:43:15.000000 #3784] INFO -- GenerateInvoice:
-index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task"
-class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
+index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
 
 <!-- Skipped (WARN level) -->
 W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidateCustomer:
-index=1 state="interrupted" status="skipped" reason="Customer already validated"
+index=1 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="ValidateCustomer" state="interrupted" status="skipped" reason="Customer already validated"
 
 <!-- Failed (ERROR level) -->
 E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CalculateTax:
-index=2 state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
+index=2 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="CalculateTax"  state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
 
 <!-- Failed Chain -->
 E, [2022-07-17T18:43:15.000000 #3784] ERROR -- BillingWorkflow:
-caused_failure={index: 2, class: "CalculateTax", status: "failed"}
-threw_failure={index: 1, class: "ValidateCustomer", status: "failed"}
+index=3 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="BillingWorkflow"  state="interrupted" status="failed" caused_failure={index: 2, class: "CalculateTax", status: "failed"} threw_failure={index: 1, class: "ValidateCustomer", status: "failed"}
 ```
 
 > [!TIP]

data/README.md

@@ -8,16 +8,24 @@
   <img alt="License" src="https://img.shields.io/github/license/drexed/cmdx">
 </p>
 
-# CMDx
+# 🚀 CMDx — Business logic without the chaos
 
-CMDx is a framework for building maintainable business processes. It simplifies building task objects by offering integrated:
+Stop wrestling with messy service objects. CMDx gives you a clean, consistent way to design business processes:
 
-- Flow controls
-- Composable workflows
-- Comprehensive logging
-- Attribute definition
-- Validations and coercions
-- And much more...
+- Start small with a single `work` method
+- Scale to complex tasks and multi-step workflows
+- Get built-in flow control, logging, validations, and more...
+
+*Build faster. Debug easier. Stay sane.*
+
+## 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.
 
 ## Installation
 
@@ -37,11 +45,24 @@ Or install it yourself as:
 
 ## Quick Example
 
-Here's how a quick 3 step process can open up a world of possibilities:
+Here's how a quick 4 step process can open up a world of possibilities:
+
+### 1. Compose
+
+#### Minimum Viable Task
+
+```ruby
+class SendAnalyzedEmail < CMDx::Task
+  def work
+    user = User.find(context.user_id)
+    MetricsMailer.analyzed(user).deliver_now
+  end
+end
+```
+
+#### Fully Featured Task
 
 ```ruby
-# 1. Setup task
-# ---------------------------------
 class AnalyzeMetrics < CMDx::Task
   register :middleware, CMDx::Middlewares::Correlate, id: -> { Current.request_id }
 
@@ -56,8 +77,10 @@ class AnalyzeMetrics < CMDx::Task
     elsif dataset.unprocessed?
       skip!("Dataset not ready for analysis")
     else
-      context.result = PValueAnalyzer.analyze(dataset, analysis_type)
+      context.result = PValueAnalyzer.execute(dataset:, analysis_type:)
       context.analyzed_at = Time.now
+
+      SendAnalyzedEmail.execute(user_id: Current.account.manager_id)
     end
   end
 
@@ -71,16 +94,20 @@ class AnalyzeMetrics < CMDx::Task
     dataset.update!(analysis_result_id: context.result.id)
   end
 end
+```
 
-# 2. Execute task
-# ---------------------------------
+### 2. Execute
+
+```ruby
 result = AnalyzeMetrics.execute(
   dataset_id: 123,
   "analysis_type" => "advanced"
 )
+```
 
-# 3. Handle result
-# ---------------------------------
+### 3. React
+
+```ruby
 if result.success?
   puts "Metrics analyzed at #{result.context.analyzed_at}"
 elsif result.skipped?
@@ -90,6 +117,16 @@ elsif result.failed?
 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}
+```
+
 ## Table of contents
 
 - [Getting Started](docs/getting_started.md)
@@ -122,12 +159,12 @@ end
 
 ## Ecosystem
 
-- [cmdx-i18n](https://github.com/drexed/cmdx-i18n) - 85+ translations
-- [cmdx-parallel](https://github.com/drexed/cmdx-parallel) - Parallel workflow tasks
+- [cmdx-rspec](https://github.com/drexed/cmdx-rspec) - RSpec test matchers
 
-The following gems are currently under development:
+For backwards compatibility of certain functionality:
 
-- `cmdx-testing` - RSpec and Minitest matchers
+- [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`
 
 ## Development
 

data/docs/getting_started.md

@@ -2,8 +2,25 @@
 
 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)
@@ -21,6 +38,15 @@ CMDx is a Ruby framework for building maintainable, observable business logic th
   - [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.
+
 ## Installation
 
 Add CMDx to your Gemfile:

data/docs/logging.md

@@ -25,21 +25,19 @@ Sample output:
 ```log
 <!-- Success (INFO level) -->
 I, [2022-07-17T18:43:15.000000 #3784] INFO -- GenerateInvoice:
-index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task"
-class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
+index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="GenerateInvoice" state="complete" status="success" metadata={runtime: 187}
 
 <!-- Skipped (WARN level) -->
 W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidateCustomer:
-index=1 state="interrupted" status="skipped" reason="Customer already validated"
+index=1 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="ValidateCustomer" state="interrupted" status="skipped" reason="Customer already validated"
 
 <!-- Failed (ERROR level) -->
 E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CalculateTax:
-index=2 state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
+index=2 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="CalculateTax"  state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
 
 <!-- Failed Chain -->
 E, [2022-07-17T18:43:15.000000 #3784] ERROR -- BillingWorkflow:
-caused_failure={index: 2, class: "CalculateTax", status: "failed"}
-threw_failure={index: 1, class: "ValidateCustomer", status: "failed"}
+index=3 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="BillingWorkflow"  state="interrupted" status="failed" caused_failure={index: 2, class: "CalculateTax", status: "failed"} threw_failure={index: 1, class: "ValidateCustomer", status: "failed"}
 ```
 
 > [!TIP]

data/lib/cmdx/middlewares/correlate.rb

@@ -95,7 +95,8 @@ module CMDx
       def call(task, **options, &)
         return yield unless Utils::Condition.evaluate(task, options)
 
-        correlation_id =
+        correlation_id = task.result.metadata[:correlation_id] ||=
+          id ||
           case callable = options[:id]
           when Symbol then task.send(callable)
           when Proc then task.instance_eval(&callable)
@@ -107,9 +108,7 @@ module CMDx
             end
           end
 
-        result = use(correlation_id, &)
-        task.result.metadata[:correlation_id] = correlation_id
-        result
+        use(correlation_id, &)
       end
 
     end

data/lib/cmdx/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "1.7.1"
+  VERSION = "1.7.2"
 
 end

data/lib/generators/cmdx/locale_generator.rb

@@ -10,7 +10,7 @@ module Cmdx
 
     source_root File.expand_path("../../locales", __dir__)
 
-    desc "Copies the locale with the given alpha-2 code"
+    desc "Copies the locale with the given ISO 639 code"
 
     argument :locale, type: :string, default: "en", banner: "locale: en, es, fr, etc"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.7.1
+  version: 1.7.2
 platform: ruby
 authors:
 - Juan Gomez