cmdx 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03bacf5f39e3f6588988b533606f53a90cdba94beef7bc2c9303e1e00c53a989
-  data.tar.gz: 02f9e8a212ace89b6d9e7b134a9b92b469ce049b553876506e5d6786bede830e
+  metadata.gz: f8adbc69a3e91974b801b1f11c404a12b12bdcfcfd3f3d947a8cb3c730b7a934
+  data.tar.gz: e0daecd4316350294630dc58f1a05bf1c0fde6203360981b156e468504108a29
 SHA512:
-  metadata.gz: 4d76b548878d4b78ed131a18804c4810d928fa99dfa66cf31723a475e89034ccac16451ed62e1be7880be491911eaef31b215c9540d2a7e4b864b716ac5a8cf7
-  data.tar.gz: 107083dfef5796ed6f628b662d1920bb0e7028e0ea9a56ecaf63d979f261c248d6ab113c3881079522352abe97fdde451d8e741403a77f1b38ea2b082d003179
+  metadata.gz: 93022dbeef63aab15d43cc0902d97dc0e0e41aa72edfc2ecc00d57b7d103e0a2518271b4fa5f0cd0f4e037d39d9bda5a2c07210c24a76996bfbc830785f521fb
+  data.tar.gz: 57a130066332c5bc60645c3dff28eb5909711c18eeb54d304961ba4787543d270773e52161f5a95dca988a971972d80de18547c1f2d59a5e6cd7f39342f28c69

data/CHANGELOG.md

@@ -4,12 +4,21 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.x.x] - UNRELEASED
+## UNRELEASED
+
+## [2.2.0] - UNRELEASED
+
+### Added
+- Post-work lifecycle callbacks (`after_execution`, every `on_*` hook) receive the finalized `Signal` as their second argument — `reason`, `cause`, `metadata`, `origin`, and `backtrace` are available before `Result` construction. Pre-work hooks and `around_execution` keep the single-`task` arity
+- `Input#allow_nil` — permit `nil` after defaults without coercion, transform, or validation
+- `Fault#detailed_message` — appends validation errors and propagation `origin` to the stdlib detailed message for IRB and debug formatters without changing `message`
+- `Fault#inspect` — compact task/reason/errors summary for console debugging
 
 ## [2.1.1] - 2026-07-26
 
 ### Added
 - `Result#to_h` includes `:errors` (`Errors#to_h`) for structured validation messages in logs, telemetry, and JSON serialization
+- Add `:decimal` coercion alias for `BigDecimal`
 
 ### Fixed
 - `Input` resolution continues coerce → transform → validate when the key is present (including explicit `nil`) instead of stopping after defaults; omitted keys still stop when the value is `nil` after defaults

data/lib/cmdx/callbacks.rb

@@ -25,6 +25,20 @@ module CMDx
       :on_ko
     ].freeze
 
+    # Events fired after `around_execution` (work, rollback) finishes. Runtime
+    # passes the finalized {Signal} as the second callback argument so hooks can
+    # read `reason`, `cause`, `metadata`, `origin`, and `backtrace`.
+    POST_WORK_EVENTS = Set[
+      :after_execution,
+      :on_complete,
+      :on_interrupted,
+      :on_success,
+      :on_skipped,
+      :on_failed,
+      :on_ok,
+      :on_ko
+    ].freeze
+
     attr_reader :registry
 
     def initialize
@@ -122,20 +136,26 @@ module CMDx
     # Fires each callback registered for `event` against `task`. Skips any
     # callback whose `:if`/`:unless` gates fail.
     #
+    # Post-work events ({POST_WORK_EVENTS}) receive the finalized `signal` as
+    # their second argument (Symbol method, Proc, or `#call`). Pre-work events
+    # and `around_execution` omit it.
+    #
     # @param event [Symbol]
     # @param task [Task]
+    # @param signal [Signal, nil] finalized halt token for post-work events
     # @return [void]
     # @raise [ArgumentError] when a callback is neither a Symbol nor responds to `#call`
-    def process(event, task)
+    def process(event, task, signal = nil)
       return if empty?
 
       callbacks = registry[event]
       return if callbacks.nil? || callbacks.empty?
 
+      post_work = POST_WORK_EVENTS.include?(event)
       callbacks.each do |callable, options|
         next unless Util.satisfied?(options[:if], options[:unless], task)
 
-        invoke(callable, task)
+        invoke(callable, task, signal: post_work ? signal : nil)
       end
     end
 
@@ -167,7 +187,7 @@ module CMDx
             succ.call
           end
 
-          invoke(callable, task, cont, &cont)
+          invoke(callable, task, continuation: cont, &cont)
 
           called || raise(CallbackError, <<~MSG.chomp)
             #{event} callback did not invoke its continuation.
@@ -179,14 +199,25 @@ module CMDx
 
     private
 
-    def invoke(callable, task, *extras, &)
+    def invoke(callable, task, continuation: nil, signal: nil, &block)
       case callable
       when Symbol
-        task.send(callable, &)
+        if signal
+          task.send(callable, signal, &block)
+        else
+          task.send(callable, &block)
+        end
       when Proc
-        task.instance_exec(task, *extras, &callable)
+        extras = continuation ? [continuation] : []
+        if signal
+          task.instance_exec(task, signal, *extras, &callable)
+        else
+          task.instance_exec(task, *extras, &callable)
+        end
       else
-        return callable.call(task, *extras) if callable.respond_to?(:call)
+        args = signal ? [task, signal] : [task]
+        args << continuation if continuation
+        return callable.call(*args) if callable.respond_to?(:call)
 
         raise ArgumentError, <<~MSG.chomp
           callback must be a Symbol, Proc, or respond to #call (got #{callable.class}).

data/lib/cmdx/coercions.rb

@@ -22,6 +22,7 @@ module CMDx
         complex: Coercions::Complex,
         date: Coercions::Date,
         date_time: Coercions::DateTime,
+        decimal: Coercions::BigDecimal,
         float: Coercions::Float,
         hash: Coercions::Hash,
         integer: Coercions::Integer,

data/lib/cmdx/fault.rb

@@ -124,5 +124,43 @@ module CMDx
       @result.chain
     end
 
+    # Enriches the stdlib detailed message with validation errors and
+    # propagation context for IRB and other debug formatters. {#message} is
+    # unchanged.
+    #
+    # @param highlight [Boolean] forwarded to `Exception#detailed_message`
+    # @param order [Symbol] forwarded to `Exception#detailed_message`
+    # @return [String]
+    def detailed_message(highlight: true, order: :top)
+      lines = [super]
+      append_errors_lines(lines)
+      append_origin_line(lines)
+      lines.join("\n")
+    end
+
+    # @return [String] human-readable representation
+    def inspect
+      "#<#{self.class} task=#{task.name} tid=#{result.tid} cid=#{result.cid} xid=#{result.xid} reason=#{result.reason.inspect} errors=#{result.errors.to_h}>"
+    end
+
+    private
+
+    def append_errors_lines(lines)
+      return if result.errors.empty?
+
+      lines << "  errors:"
+      result.errors.each do |key, messages|
+        messages.each { |message| lines << "    #{key}: #{message}" }
+      end
+    end
+
+    def append_origin_line(lines)
+      origin = result.origin
+      return unless origin
+
+      reason = origin.reason || "no reason"
+      lines << "  origin: #{origin.task.name} (#{reason})"
+    end
+
   end
 end

data/lib/cmdx/input.rb

@@ -22,6 +22,7 @@ module CMDx
     # @option options [Symbol, Proc, #call] :if
     # @option options [Symbol, Proc, #call] :unless
     # @option options [Boolean] :required
+    # @option options [Boolean] :allow_nil (see {#allow_nil})
     def initialize(name, children: EMPTY_ARRAY, **options)
       @name     = name.to_sym
       @children = children.freeze
@@ -78,6 +79,14 @@ module CMDx
       @options.fetch(:required, false)
     end
 
+    # When `true`, a `nil` value after defaults skips coercion, transform, and
+    # validation. Per-validator `:allow_nil` only skips individual rules.
+    #
+    # @return [Boolean]
+    def allow_nil
+      @options.fetch(:allow_nil, false)
+    end
+
     # Computed accessor/reader method name. Uses `:as` when provided,
     # otherwise combines `:prefix`, `name`, and `:suffix` around the source.
     #
@@ -131,7 +140,8 @@ module CMDx
     # @note "Required" here means "the key is present in the source"; an
     #   explicit `nil` under an existing key satisfies the required check
     #   and is then routed through `:default`. Combine with `:presence` /
-    #   `:validate` to reject explicit `nil` values.
+    #   `:validate` to reject explicit `nil` values, or `:allow_nil` (see
+    #   {#allow_nil}) to leave `nil` unresolved.
     #
     # @param task [Task]
     # @return [Object, nil] the resolved value (`nil` on failure)
@@ -189,7 +199,7 @@ module CMDx
       end
 
       value = apply_default(task) if value.nil?
-      return if value.nil? && !key_provided
+      return if value.nil? && (!key_provided || allow_nil)
 
       @coercions ||= task.class.coercions.extract(@options)
       value = task.class.coercions.coerce(task, accessor_name, value, @coercions)

data/lib/cmdx/inputs.rb

@@ -35,6 +35,7 @@ module CMDx
     # @option options [Symbol, Proc, #call] :if
     # @option options [Symbol, Proc, #call] :unless
     # @option options [Boolean] :required
+    # @option options [Boolean] :allow_nil (see {Input#allow_nil})
     # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
     # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
     # @return [Inputs] self for chaining
@@ -138,6 +139,7 @@ module CMDx
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
       # @option options [Boolean] :required
+      # @option options [Boolean] :allow_nil (see {Input#allow_nil})
       # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
       # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
       # @yield nested child input DSL
@@ -162,6 +164,7 @@ module CMDx
       # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
+      # @option options [Boolean] :allow_nil (see {Input#allow_nil})
       # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
       # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
       # @yield nested child input DSL
@@ -185,6 +188,7 @@ module CMDx
       # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
+      # @option options [Boolean] :allow_nil (see {Input#allow_nil})
       # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
       # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
       # @yield nested child input DSL

data/lib/cmdx/runtime.rb

@@ -156,7 +156,8 @@ module CMDx
       callbacks = @task.class.callbacks
       return if callbacks.empty?
 
-      callbacks.process(event, @task)
+      signal = Callbacks::POST_WORK_EVENTS.include?(event) ? @signal : nil
+      callbacks.process(event, @task, signal)
     end
 
     def run_around(event, &)

data/lib/cmdx/task.rb

@@ -274,6 +274,7 @@ module CMDx
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
       # @option options [Boolean] :required
+      # @option options [Boolean] :allow_nil (see {Input#allow_nil})
       # @option options [Object] :coerce (see {Coercions#extract})
       # @option options [Object] :validate (see {Validators#extract})
       # @yield nested-input DSL block (see {Inputs::ChildBuilder})
@@ -307,6 +308,7 @@ module CMDx
       # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
+      # @option options [Boolean] :allow_nil (see {Input#allow_nil})
       # @option options [Object] :coerce (see {Coercions#extract})
       # @option options [Object] :validate (see {Validators#extract})
       # @yield nested-input DSL block (see {Inputs::ChildBuilder})
@@ -329,6 +331,7 @@ module CMDx
       # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
+      # @option options [Boolean] :allow_nil (see {Input#allow_nil})
       # @option options [Object] :coerce (see {Coercions#extract})
       # @option options [Object] :validate (see {Validators#extract})
       # @yield nested-input DSL block (see {Inputs::ChildBuilder})

data/lib/cmdx/version.rb

@@ -3,6 +3,6 @@
 module CMDx
 
   # Gem version. Bumped on release; mirrored in the gemspec.
-  VERSION = "2.1.1"
+  VERSION = "2.2.0"
 
 end

data/lib/generators/cmdx/templates/install.rb

@@ -79,7 +79,8 @@ CMDx.configure do |config|
   # Callbacks
   # https://drexed.github.io/cmdx/configuration/#callbacks
   # ===========================================================================
-  # Hook into a task's lifecycle. Each callback receives the task instance.
+  # Hook into a task's lifecycle. Pre-work hooks receive the task; post-work
+  # hooks (`after_execution`, every `on_*`) also receive the finalized Signal.
   #
   # Available events:
   #   :before_execution, :before_validation,
@@ -88,8 +89,8 @@ CMDx.configure do |config|
   #   :on_success, :on_skipped, :on_failed,
   #   :on_ok, :on_ko
   #
-  # config.callbacks.register(:on_failed, proc do |task|
-  #   Rails.logger.error("[cmdx] #{task.class.name} failed: #{task.metadata[:reason]}")
+  # config.callbacks.register(:on_failed, proc do |task, signal|
+  #   Rails.logger.error("[cmdx] #{task.class.name} failed: #{signal.reason}")
   # end)
 
   # ===========================================================================

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -312,7 +312,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.13
+rubygems_version: 4.0.17
 specification_version: 4
 summary: CMDx is a framework for building maintainable business processes.
 test_files: []