cmdx 1.12.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dffef0df3a8abb190fc0ca6a194383614fdd81f3eebf22ecab59d8ec047d1d7
-  data.tar.gz: 0f38ccaa12a07c41b64fb4fd3f0685bafb45b7de0b3830243f85a53de4d331c4
+  metadata.gz: 0b1cd7841d40aeac40b6eb36a7ff87a5ace03deae3496e1aef5cb10e34f8f42d
+  data.tar.gz: 303333d4635690575ceda40a2564be417b47f5ec4c2992af542c509710289ae3
 SHA512:
-  metadata.gz: 8649dadb0908d88f7441b80d6e3dce03e7f0d20095216d8ac24cc0bf8b1446f57b4552f021a324f47d860112e431b531695a5cd78e84a4b2cf0c3be0dff1224e
-  data.tar.gz: 5e88be6d5a3070d75abbbcb20e25d900db3a44f011f71ed55c61f748cda77e9be4297f12829ab9f28daac66a4b2c511725318ae4e1455793eef8b8f806c3864c
+  metadata.gz: 18cde5cf4b6c7fa974ffb7a3827e09d0a5c2ac5f3c2c01427abbc94de71ef1bc03aee78e25032900761f09c8d39e89e52a4ea1d5fa33e07c86f060b483fe839f
+  data.tar.gz: 5ed05ecdb682ae160be47cf6399c76081486011b6143f95f9884a06b588474ba64e3e000efd72ba2dcd6abb343e3e12985d2691ca15ee7575873f90daff6e70f

data/CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [UNRELEASED]
 
+## [1.13.0] - 2025-12-23
+
+### Added
+
+- Added task execution rollback tracking and logging
+- Added `dry_run` option to task execution with inheritance support for nested tasks
+- Added context `delete` alias for `delete!`
+- Added context `merge` alias for `merge!`
+
 ## [1.12.0] - 2025-12-18
 
 ### Added

data/docs/basics/execution.md

@@ -11,6 +11,33 @@ Both methods return results, but handle failures differently:
 | `execute` | Always returns `CMDx::Result` | Never raises | Predictable result handling |
 | `execute!` | Returns `CMDx::Result` on success | Raises `CMDx::Fault` when skipped or failed | Exception-based control flow |
 
+```mermaid
+flowchart LR
+    subgraph Methods
+        E[execute]
+        EB[execute!]
+    end
+
+    subgraph Returns [Returns CMDx::Result]
+        Success
+        Failed
+        Skipped
+    end
+
+    subgraph Raises [Raises CMDx::Fault]
+        FailFault
+        SkipFault
+    end
+
+    E --> Success
+    E --> Failed
+    E --> Skipped
+
+    EB --> Success
+    EB --> FailFault
+    EB --> SkipFault
+```
+
 ## Non-bang Execution
 
 Always returns a `CMDx::Result`, never raises exceptions. Perfect for most use cases.
@@ -94,3 +121,32 @@ result.chain        #=> Task execution chain
 result.context      #=> Context with all task data
 result.metadata     #=> Hash with execution metadata
 ```
+
+## Dry Run
+
+Execute tasks in dry-run mode to simulate execution without performing side effects. Pass `dry_run: true` in the context when initializing or executing the task.
+
+Inside your task, use the `dry_run?` method to conditionally skip side effects.
+
+```ruby
+class CloseStripeCard < CMDx::Task
+  def work
+    context.stripe_result =
+      if dry_run?
+        FactoryBot.build(:stripe_closed_card)
+      else
+        StripeApi.close_card(context.card_id)
+      end
+  end
+end
+
+# Execute in dry-run mode
+result = CloseStripeCard.execute(card_id: "card_abc123", dry_run: true)
+result.success? # => true
+
+# FactoryBot object
+result.context.stripe_result = {
+  card_id: "card_abc123",
+  status: "closed"
+}
+```

data/docs/basics/setup.md

@@ -29,13 +29,14 @@ IncompleteTask.execute #=> raises CMDx::UndefinedMethodError
 Undo any operations linked to the given status, helping to restore a pristine state.
 
 ```ruby
-class ValidateDocument < CMDx::Task
+class ChargeCard < CMDx::Task
   def work
-    # Your logic here...
+    # Your logic here, ex: charge $100
   end
 
+  # Called automatically if a later step in the workflow fails
   def rollback
-    # Your undo logic...
+    # Your undo logic, ex: void $100 charge
   end
 end
 ```
@@ -70,6 +71,28 @@ end
 
 Tasks follow a predictable execution pattern:
 
+```mermaid
+stateDiagram-v2
+    Initialized: Instantiation
+    Initialized --> Validating: execute
+    Validating --> Executing: Valid?
+    Validating --> Failed: Invalid
+    Executing --> Success: Work done
+    Executing --> Skipped: skip!
+    Executing --> Failed: fail! / Exception
+    Executed
+
+    state Executed {
+        Success
+        Skipped
+        Failed
+        Rollback
+
+        Skipped --> Rollback
+        Failed --> Rollback
+    }
+```
+
 !!! danger "Caution"
 
     Tasks are single-use objects. Once executed, they're frozen and immutable.

data/docs/deprecation.md

@@ -32,8 +32,6 @@ Allow execution while tracking deprecation in logs. Ideal for gradual migrations
 ```ruby
 class ProcessLegacyFormat < CMDx::Task
   settings(deprecated: :log)
-
-  # Same
   settings(deprecated: true)
 
   def work

data/docs/getting_started.md

@@ -43,6 +43,13 @@ If not using Rails, manually copy the [configuration file](https://github.com/dr
 
 CMDx embraces the Compose, Execute, React, Observe (CERO, pronounced "zero") pattern—a simple yet powerful approach to building reliable business logic.
 
+```mermaid
+flowchart LR
+    Compose --> Execute
+    Execute --> React
+    Execute -.-> Observe
+```
+
 ### Compose
 
 Build reusable, single-responsibility tasks with typed attributes, validation, and callbacks. Tasks can be chained together in workflows to create complex business processes from simple building blocks.
@@ -93,6 +100,10 @@ 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}
 ```
 
+!!! note
+
+    This represents a log-only event-sourcing approach, enabling full traceability and a complete, time-ordered view of system behavior.
+
 ## Task Generator
 
 Generate new CMDx tasks quickly using the built-in generator:

data/docs/logging.md

@@ -18,20 +18,16 @@ 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}
+I, [2025-12-23T17:04:07.292614Z #20108] INFO -- cmdx: {index: 1, chain_id: "019b4c2b-087b-79be-8ef2-96c11b659df5", type: "Task", tags: [], class: "GenerateInvoice", dry_run: false, id: "019b4c2b-0878-704d-ba0b-daa5410123ec", state: "complete", status: "success", outcome: "success", metadata: {runtime: 187}}
 
-<!-- Skipped (WARN level) -->
-W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidateCustomer:
-index=1 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="ValidateCustomer" state="interrupted" status="skipped" reason="Customer already validated"
+<!-- Skipped (INFO level) -->
+I, [2025-12-23T17:04:11.496881Z #20139] INFO -- cmdx: {index: 2, chain_id: "019b4c2b-18e8-7af6-a38b-63b042c4fbed", type: "Task", tags: [], class: "ValidateCustomer", dry_run: false, id: "019b4c2b-18e5-7230-af7e-5b4a4bd7cda2", state: "interrupted", status: "skipped", outcome: "skipped", metadata: {}, reason: "Customer already validated", cause: #<CMDx::SkipFault: Customer already validated>, rolled_back: false}
 
-<!-- Failed (ERROR level) -->
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CalculateTax:
-index=2 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="CalculateTax"  state="interrupted" status="failed" metadata={error_code: "TAX_SERVICE_UNAVAILABLE"}
+<!-- Failed (INFO level) -->
+I, [2025-12-23T17:04:15.875306Z #20173] INFO -- cmdx: {index: 3, chain_id: "019b4c2b-2a02-7dbc-b713-b20a7379704f", type: "Task", tags: [], class: "CalculateTax", dry_run: false, id: "019b4c2b-2a00-70b7-9fab-2f14db9139ef", state: "interrupted", status: "failed", outcome: "failed", metadata: {error_code: "TAX_SERVICE_UNAVAILABLE"}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false}
 
 <!-- Failed Chain -->
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- BillingWorkflow:
-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"}
+I, [2025-12-23T17:04:20.972539Z #20209] INFO -- cmdx: {index: 0, chain_id: "019b4c2b-3de9-71f7-bcc3-2a98836bcfd7", type: "Workflow", tags: [], class: "BillingWorkflow", dry_run: false, id: "019b4c2b-3de6-70b9-9c16-5be13b1a463c", state: "interrupted", status: "failed", outcome: "interrupted", metadata: {}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false, threw_failure: {index: 3, chain_id: "019b4c2b-3de9-71f7-bcc3-2a98836bcfd7", type: "Task", tags: [], class: "CalculateTax", id: "019b4c2b-3dec-70b3-969b-c5b7896e3b27", state: "interrupted", status: "failed", outcome: "failed", metadata: {error_code: "TAX_SERVICE_UNAVAILABLE"}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false}, caused_failure: {index: 3, chain_id: "019b4c2b-3de9-71f7-bcc3-2a98836bcfd7", type: "Task", tags: [], class: "CalculateTax", id: "019b4c2b-3dec-70b3-969b-c5b7896e3b27", state: "interrupted", status: "failed", outcome: "failed", metadata: {error_code: "TAX_SERVICE_UNAVAILABLE"}, reason: "Validation failed", cause: #<CMDx::FailFault: Validation failed>, rolled_back: false}}
 ```
 
 !!! tip

data/docs/outcomes/result.md

@@ -30,7 +30,7 @@ result.metadata #=> { error_code: "BUILD_TOOL.NOT_FOUND" }
 
 ## Lifecycle Information
 
-Check execution state and status with predicate methods:
+Check execution state, status, and rollback with predicate methods:
 
 ```ruby
 result = BuildApplication.execute(version: "1.2.3")
@@ -48,6 +48,9 @@ result.skipped?     #=> false (not skipped)
 # Outcome categorization
 result.good?        #=> true (success or skipped)
 result.bad?         #=> false (skipped or failed)
+
+# Rollback Status
+result.rolled_back? #=> true (execution was rolled back)
 ```
 
 ## Outcome Analysis

data/lib/cmdx/chain.rb

@@ -39,9 +39,10 @@ module CMDx
     # @return [Chain] A new chain instance
     #
     # @rbs () -> void
-    def initialize
+    def initialize(dry_run: false)
       @id = Identifier.generate
       @results = []
+      @dry_run = !!dry_run
     end
 
     class << self
@@ -102,16 +103,28 @@ module CMDx
       #   puts "Chain size: #{chain.size}"
       #
       # @rbs (Result result) -> Chain
-      def build(result)
+      def build(result, dry_run: false)
         raise TypeError, "must be a CMDx::Result" unless result.is_a?(Result)
 
-        self.current ||= new
+        self.current ||= new(dry_run:)
         current.results << result
         current
       end
 
     end
 
+    # Returns whether the chain is running in dry-run mode.
+    #
+    # @return [Boolean] Whether the chain is running in dry-run mode
+    #
+    # @example
+    #   chain.dry_run? # => true
+    #
+    # @rbs () -> bool
+    def dry_run?
+      !!@dry_run
+    end
+
     # Converts the chain to a hash representation.
     #
     # @option return [String] :id The chain identifier
@@ -127,7 +140,8 @@ module CMDx
     # @rbs () -> Hash[Symbol, untyped]
     def to_h
       {
-        id: id,
+        id:,
+        dry_run: dry_run?,
         results: results.map(&:to_h)
       }
     end

data/lib/cmdx/context.rb

@@ -164,6 +164,7 @@ module CMDx
       args.to_h.each { |key, value| self[key.to_sym] = value }
       self
     end
+    alias merge merge!
 
     # Deletes a key-value pair from the context.
     #
@@ -182,6 +183,7 @@ module CMDx
     def delete!(key, &)
       table.delete(key.to_sym, &)
     end
+    alias delete delete!
 
     # Compares this context with another object for equality.
     #

data/lib/cmdx/executor.rb

@@ -8,6 +8,8 @@ module CMDx
   # and proper error handling for different types of failures.
   class Executor
 
+    extend Forwardable
+
     # Returns the task being executed.
     #
     # @return [Task] The task instance
@@ -18,6 +20,8 @@ module CMDx
     # @rbs @task: Task
     attr_reader :task
 
+    def_delegators :task, :result
+
     # @param task [CMDx::Task] The task to execute
     #
     # @return [CMDx::Executor] A new executor instance
@@ -65,13 +69,13 @@ module CMDx
       rescue UndefinedMethodError => e
         raise(e) # No need to clear the Chain since exception is not being re-raised
       rescue Fault => e
-        task.result.throw!(e.result, halt: false, cause: e)
+        result.throw!(e.result, halt: false, cause: e)
       rescue StandardError => e
         retry if retry_execution?(e)
-        task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
         task.class.settings[:exception_handler]&.call(task, e)
       ensure
-        task.result.executed!
+        result.executed!
         post_execution!
       end
 
@@ -96,14 +100,14 @@ module CMDx
       rescue UndefinedMethodError => e
         raise_exception(e)
       rescue Fault => e
-        task.result.throw!(e.result, halt: false, cause: e)
+        result.throw!(e.result, halt: false, cause: e)
         halt_execution?(e) ? raise_exception(e) : post_execution!
       rescue StandardError => e
         retry if retry_execution?(e)
-        task.result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
+        result.fail!("[#{e.class}] #{e.message}", halt: false, cause: e)
         raise_exception(e)
       else
-        task.result.executed!
+        result.executed!
         post_execution!
       end
 
@@ -137,14 +141,14 @@ module CMDx
       available_retries = (task.class.settings[:retries] || 0).to_i
       return false unless available_retries.positive?
 
-      current_retries = (task.result.metadata[:retries] ||= 0).to_i
+      current_retries = (result.metadata[:retries] ||= 0).to_i
       remaining_retries = available_retries - current_retries
       return false unless remaining_retries.positive?
 
       exceptions = Array(task.class.settings[:retry_on] || StandardError)
       return false unless exceptions.any? { |e| exception.class <= e }
 
-      task.result.metadata[:retries] += 1
+      result.metadata[:retries] += 1
 
       task.logger.warn do
         reason = "[#{exception.class}] #{exception.message}"
@@ -208,7 +212,7 @@ module CMDx
       task.class.settings[:attributes].define_and_verify(task)
       return if task.errors.empty?
 
-      task.result.fail!(
+      result.fail!(
         Locale.t("cmdx.faults.invalid"),
         errors: {
           full_message: task.errors.to_s,
@@ -223,7 +227,7 @@ module CMDx
     def execution!
       invoke_callbacks(:before_execution)
 
-      task.result.executing!
+      result.executing!
       task.work
     end
 
@@ -231,12 +235,12 @@ module CMDx
     #
     # @rbs () -> void
     def post_execution!
-      invoke_callbacks(:"on_#{task.result.state}")
-      invoke_callbacks(:on_executed) if task.result.executed?
+      invoke_callbacks(:"on_#{result.state}")
+      invoke_callbacks(:on_executed) if result.executed?
 
-      invoke_callbacks(:"on_#{task.result.status}")
-      invoke_callbacks(:on_good) if task.result.good?
-      invoke_callbacks(:on_bad) if task.result.bad?
+      invoke_callbacks(:"on_#{result.status}")
+      invoke_callbacks(:on_good) if result.good?
+      invoke_callbacks(:on_bad) if result.bad?
     end
 
     # Finalizes execution by freezing the task, logging results, and rolling back work.
@@ -246,26 +250,25 @@ module CMDx
       log_execution!
       log_backtrace! if task.class.settings[:backtrace]
 
+      rollback_execution!
       freeze_execution!
       clear_chain!
-
-      rollback_execution!
     end
 
     # Logs the execution result at the configured log level.
     #
     # @rbs () -> void
     def log_execution!
-      task.logger.info { task.result.to_h }
+      task.logger.info { result.to_h }
     end
 
     # Logs the backtrace of the exception if the task failed.
     #
     # @rbs () -> void
     def log_backtrace!
-      return unless task.result.failed?
+      return unless result.failed?
 
-      exception = task.result.caused_failure.cause
+      exception = result.caused_failure.cause
       return if exception.is_a?(Fault)
 
       task.logger.error do
@@ -287,11 +290,11 @@ module CMDx
       return if Coercions::Boolean.call(skip_freezing)
 
       task.freeze
-      task.result.freeze
+      result.freeze
 
       # Freezing the context and chain can only be done
       # once the outer-most task has completed.
-      return unless task.result.index.zero?
+      return unless result.index.zero?
 
       task.context.freeze
       task.chain.freeze
@@ -301,7 +304,7 @@ module CMDx
     #
     # @rbs () -> void
     def clear_chain!
-      return unless task.result.index.zero?
+      return unless result.index.zero?
 
       Chain.clear
     end
@@ -310,12 +313,14 @@ module CMDx
     #
     # @rbs () -> void
     def rollback_execution!
+      return if result.rolled_back?
       return unless task.respond_to?(:rollback)
 
       statuses = task.class.settings[:rollback_on]
       statuses = Array(statuses).map(&:to_s).uniq
-      return unless statuses.include?(task.result.status)
+      return unless statuses.include?(result.status)
 
+      result.rolled_back!
       task.rollback
     end
 

data/lib/cmdx/result.rb

@@ -95,7 +95,7 @@ module CMDx
     # @rbs @cause: (Exception | nil)
     attr_reader :cause
 
-    def_delegators :task, :context, :chain, :errors
+    def_delegators :task, :context, :chain, :errors, :dry_run?
     alias ctx context
 
     # @param task [CMDx::Task] The task instance this result represents
@@ -118,6 +118,7 @@ module CMDx
       @metadata = {}
       @reason = nil
       @cause = nil
+      @rolled_back = false
     end
 
     STATES.each do |s|
@@ -419,6 +420,27 @@ module CMDx
       failed? && !caused_failure?
     end
 
+    # @return [void]
+    #
+    # @example
+    #   result.rolled_back!
+    #   result.rolled_back? # => true
+    #
+    # @rbs () -> void
+    def rolled_back!
+      @rolled_back = true
+    end
+
+    # @return [Boolean] Whether the result has been rolled back
+    #
+    # @example
+    #   result.rolled_back? # => true
+    #
+    # @rbs () -> bool
+    def rolled_back?
+      !!@rolled_back
+    end
+
     # @return [Integer] Index of this result in the chain
     #
     # @example
@@ -457,6 +479,7 @@ module CMDx
         if interrupted?
           hash[:reason] = reason
           hash[:cause] = cause
+          hash[:rolled_back] = rolled_back?
         end
 
         if failed?

data/lib/cmdx/task.rb

@@ -71,6 +71,7 @@ module CMDx
     attr_reader :chain
 
     def_delegators :result, :skip!, :fail!, :throw!
+    def_delegators :chain, :dry_run?
 
     # @param context [Hash, Context] The initial context for the task
     #
@@ -94,7 +95,7 @@ module CMDx
       @id = Identifier.generate
       @context = Context.build(context)
       @result = Result.new(self)
-      @chain = Chain.build(@result)
+      @chain = Chain.build(@result, dry_run: @context.delete(:dry_run))
     end
 
     class << self
@@ -341,6 +342,7 @@ module CMDx
         type: self.class.include?(Workflow) ? "Workflow" : "Task",
         tags: self.class.settings[:tags],
         class: self.class.name,
+        dry_run: dry_run?,
         id:
       }
     end

data/lib/cmdx/version.rb

@@ -5,6 +5,6 @@ module CMDx
   # @return [String] the version of the CMDx gem
   #
   # @rbs return: String
-  VERSION = "1.12.0"
+  VERSION = "1.13.0"
 
 end

data/mkdocs.yml

@@ -65,7 +65,11 @@ markdown_extensions:
   - attr_list
   - md_in_html
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span

metadata

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