cmdx 1.20.0 → 1.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34ebd45d6a27296d5960995fc1b313b808f1d3835df82ce688ae1a6dc4faa313
-  data.tar.gz: 01ccc099ffd40950e4085c850ba3959db59bddbb5df39e8b540a6310607f7a59
+  metadata.gz: 1acff12a85519d3546d8c2c6b8d9a8fc6330e731826a9a4a359907631e7afa82
+  data.tar.gz: 69c814dc115c70dc36ab02e7462d00a5b802490d39b7f4bc1fb2c9e5c666c55e
 SHA512:
-  metadata.gz: 9cadc2e6c98e819512a62eb484c7ffb5ed2ea29bf135851441cb78fa4bb64421b844337d489976c4148c0e471144159640257dc20d574a802e90619d833c2316
-  data.tar.gz: 3edd420426ccc2ed48b1bc3f972984111eb10ec1f41bd835de478318cb5dba169cb440c5ff24b202533a942040a62aaf9897d88f03229cc97285ea69af11a377
+  metadata.gz: f2bc1eb34789f888bffc84b9ebb65252fc23ea8d598465c9ff853670ab44c9e640988b2a528ed97ff53cc1774a26e35a87706a9056aa7fc55f6604e73540cb29
+  data.tar.gz: 5c7af44bda7a2d7371c8f62183dde2195bf9b27382c65c379bc8bfd94321d7b3ab61ad41888a9a1dad57c4e606de843f4d479581cc2cea20aeb3fb8996afcd52

data/CHANGELOG.md

@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [UNRELEASED]
 
+## [1.21.0] - 2026-04-09
+
+### Added
+- Add `strict` option to `Result#skip!` and `Result#fail!` to bypass breakpoint halting in `execute!`
+- Add `dump_context` global/local setting to include `context` in `Task#to_h`
+- Add `Result#success!` for annotating successful results
+- Add `started_at` and `ended_at` to runtime middleware payload
+- Add `keys`, `values`, `each`, `each_key`, `each_value` methods to context
+- Add `subtasks` to returns tasks defined in a workflow
+
+### Changed
+- Move `faults.unspecified` locale key to `reasons.unspecified`
+
 ## [1.20.0] - 2026-03-12
 
 ### Added

data/lib/cmdx/chain.rb

@@ -32,7 +32,7 @@ module CMDx
     attr_reader :results
 
     def_delegators :results, :first, :last, :size
-    def_delegators :first, :state, :status, :outcome, :runtime
+    def_delegators :first, :state, :status, :outcome
 
     # Creates a new chain with a unique identifier and empty results collection.
     #

data/lib/cmdx/configuration.rb

@@ -123,6 +123,16 @@ module CMDx
     # @rbs @rollback_on: Array[String]
     attr_accessor :rollback_on
 
+    # Returns whether to include context data in hash representation output.
+    #
+    # @return [Boolean] true if context should be included (default: false)
+    #
+    # @example
+    #   config.dump_context = true
+    #
+    # @rbs @dump_context: bool
+    attr_accessor :dump_context
+
     # Returns whether to freeze task results after execution.
     # Set to false in test environments to allow stubbing on result objects.
     #
@@ -167,6 +177,7 @@ module CMDx
       @task_breakpoints = DEFAULT_BREAKPOINTS
       @workflow_breakpoints = DEFAULT_BREAKPOINTS
       @rollback_on = DEFAULT_ROLLPOINTS
+      @dump_context = false
       @freeze_results = true
       @default_locale = "en"
 
@@ -206,6 +217,7 @@ module CMDx
         backtrace: @backtrace,
         backtrace_cleaner: @backtrace_cleaner,
         exception_handler: @exception_handler,
+        dump_context: @dump_context,
         logger: @logger
       }
     end

data/lib/cmdx/context.rb

@@ -22,7 +22,7 @@ module CMDx
     attr_reader :table
     alias to_h table
 
-    def_delegators :table, :each, :map
+    def_delegators :table, :keys, :values, :each, :each_key, :each_value, :map
 
     # Creates a new Context instance from the given arguments.
     #
@@ -214,7 +214,7 @@ module CMDx
     #
     # @rbs (untyped other) -> bool
     def eql?(other)
-      other.is_a?(self.class) && (to_h == other.to_h)
+      other.is_a?(self.class) && (table == other.to_h)
     end
     alias == eql?
 

data/lib/cmdx/executor.rb

@@ -135,6 +135,7 @@ module CMDx
     protected
 
     # Determines if execution should halt based on breakpoint configuration.
+    # Returns false when the result was created with +strict: false+.
     #
     # @param exception [Exception] The exception that occurred
     #
@@ -142,6 +143,8 @@ module CMDx
     #
     # @rbs (Exception exception) -> bool
     def halt_execution?(exception)
+      return false unless exception.result.strict?
+
       @halt_statuses ||= Utils::Normalize.statuses(
         task.class.settings.breakpoints ||
         task.class.settings.task_breakpoints
@@ -229,13 +232,14 @@ module CMDx
     end
 
     # Executes the main task logic.
+    # Wraps task.work in catch(:cmdx_halt) so that success! can halt early.
     #
     # @rbs () -> void
     def execution!
       invoke_callbacks(:before_execution)
 
       result.executing!
-      task.work
+      catch(:cmdx_halt) { task.work }
     end
 
     # Verifies that all declared returns are present in the context after execution.

data/lib/cmdx/middlewares/runtime.rb

@@ -11,7 +11,8 @@ module CMDx
 
       extend self
 
-      # Middleware entry point that measures task execution runtime.
+      # Middleware entry point that measures task execution runtime and
+      # task execution start and end times.
       #
       # Evaluates the condition from options and measures execution time
       # if enabled. Uses monotonic clock for precise timing measurements
@@ -35,11 +36,16 @@ module CMDx
       #
       # @rbs (Task task, **untyped options) { () -> untyped } -> untyped
       def call(task, **options)
+        unow = utc_time
+        mnow = monotonic_time
         return yield unless Utils::Condition.evaluate(task, options)
 
-        now = monotonic_time
         result = yield
-        task.result.metadata[:runtime] = monotonic_time - now
+        task.result.metadata.merge!(
+          runtime: monotonic_time - mnow,
+          ended_at: utc_time,
+          started_at: unow
+        )
         result
       end
 
@@ -57,6 +63,15 @@ module CMDx
         Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
       end
 
+      # Gets the current UTC time in ISO 8601 format.
+      #
+      # @return [String] Current UTC time in ISO 8601 format
+      #
+      # @rbs () -> String
+      def utc_time
+        Time.now.utc.iso8601
+      end
+
     end
   end
 end

data/lib/cmdx/pipeline.rb

@@ -159,7 +159,7 @@ module CMDx
 
       workflow.public_send(
         :"#{faulted.last.status}!",
-        Locale.t("cmdx.faults.unspecified"),
+        Locale.t("cmdx.reasons.unspecified"),
         source: :parallel,
         faults: faulted.map(&:to_h)
       )

data/lib/cmdx/result.rb

@@ -109,6 +109,18 @@ module CMDx
     # @rbs @retries: Integer
     attr_accessor :retries
 
+    # Returns whether this result is strict.
+    # When false, {CMDx::Executor#halt_execution?} returns false
+    # regardless of the task's breakpoint settings.
+    #
+    # @return [Boolean] Whether the result is strict
+    #
+    # @example
+    #   result.strict? # => true
+    #
+    # @rbs @strict: bool
+    attr_reader :strict
+
     # Returns whether the result has been rolled back.
     #
     # @return [Boolean] Whether the result has been rolled back
@@ -143,6 +155,7 @@ module CMDx
       @reason = nil
       @cause = nil
       @retries = 0
+      @strict = true
       @rolled_back = false
     end
 
@@ -269,9 +282,36 @@ module CMDx
       self
     end
 
+    # Sets a reason and optional metadata on a successful result without
+    # changing its state or status. Useful for annotating why a task succeeded.
+    # When halt is true, uses throw/catch to exit the work method early.
+    #
+    # @param reason [String, nil] Reason or note for the success
+    # @param halt [Boolean] Whether to halt execution after success
+    # @param metadata [Hash] Additional metadata about the success
+    # @option metadata [Object] :* Any key-value pairs for additional metadata
+    #
+    # @raise [RuntimeError] When status is not success
+    #
+    # @example
+    #   result.success!("Created 42 records")
+    #   result.success!("Imported", halt: false, rows: 100)
+    #
+    # @rbs (?String? reason, halt: bool, **untyped metadata) -> void
+    def success!(reason = nil, halt: true, **metadata)
+      raise "can only be used while #{SUCCESS}" unless success?
+
+      @reason = reason
+      @metadata = metadata
+
+      throw(:cmdx_halt) if halt
+    end
+
     # @param reason [String, nil] Reason for skipping the task
     # @param halt [Boolean] Whether to halt execution after skipping
     # @param cause [Exception, nil] Exception that caused the skip
+    # @param strict [Boolean] Whether this skip is strict (default: true).
+    #   When false, {CMDx::Executor#halt_execution?} returns false regardless of task settings.
     # @param metadata [Hash] Additional metadata about the skip
     # @option metadata [Object] :* Any key-value pairs for additional metadata
     #
@@ -280,17 +320,19 @@ module CMDx
     # @example
     #   result.skip!("Dependencies not met", cause: dependency_error)
     #   result.skip!("Already processed", halt: false)
+    #   result.skip!("Optional step", strict: false)
     #
-    # @rbs (?String? reason, halt: bool, cause: Exception?, **untyped metadata) -> void
-    def skip!(reason = nil, halt: true, cause: nil, **metadata)
+    # @rbs (?String? reason, halt: bool, cause: Exception?, strict: bool, **untyped metadata) -> void
+    def skip!(reason = nil, halt: true, cause: nil, strict: true, **metadata)
       return if skipped?
 
       raise "can only transition to #{SKIPPED} from #{SUCCESS}" unless success?
 
       @state = INTERRUPTED
       @status = SKIPPED
-      @reason = reason || Locale.t("cmdx.faults.unspecified")
+      @reason = reason || Locale.t("cmdx.reasons.unspecified")
       @cause = cause
+      @strict = strict
       @metadata = metadata
 
       halt! if halt
@@ -299,6 +341,8 @@ module CMDx
     # @param reason [String, nil] Reason for task failure
     # @param halt [Boolean] Whether to halt execution after failure
     # @param cause [Exception, nil] Exception that caused the failure
+    # @param strict [Boolean] Whether this failure is strict (default: true).
+    #   When false, {CMDx::Executor#halt_execution?} returns false regardless of task settings.
     # @param metadata [Hash] Additional metadata about the failure
     # @option metadata [Object] :* Any key-value pairs for additional metadata
     #
@@ -307,17 +351,19 @@ module CMDx
     # @example
     #   result.fail!("Validation failed", cause: validation_error)
     #   result.fail!("Network timeout", halt: false, timeout: 30)
+    #   result.fail!("Soft failure", strict: false)
     #
-    # @rbs (?String? reason, halt: bool, cause: Exception?, **untyped metadata) -> void
-    def fail!(reason = nil, halt: true, cause: nil, **metadata)
+    # @rbs (?String? reason, halt: bool, cause: Exception?, strict: bool, **untyped metadata) -> void
+    def fail!(reason = nil, halt: true, cause: nil, strict: true, **metadata)
       return if failed?
 
       raise "can only transition to #{FAILED} from #{SUCCESS}" unless success?
 
       @state = INTERRUPTED
       @status = FAILED
-      @reason = reason || Locale.t("cmdx.faults.unspecified")
+      @reason = reason || Locale.t("cmdx.reasons.unspecified")
       @cause = cause
+      @strict = strict
       @metadata = metadata
 
       halt! if halt
@@ -464,6 +510,16 @@ module CMDx
       retries.positive?
     end
 
+    # @return [Boolean] Whether the result is strict
+    #
+    # @example
+    #   result.strict? # => true
+    #
+    # @rbs () -> bool
+    def strict?
+      !!@strict
+    end
+
     # @return [Boolean] Whether the result has been rolled back
     #
     # @example
@@ -499,7 +555,7 @@ module CMDx
     #
     # @example
     #   result.to_h
-    #   # => {state: "complete", status: "success", outcome: "success", metadata: {}}
+    #   # => {state: "complete", status: "success", outcome: "success", reason: "Unspecified", metadata: {}}
     #
     # @rbs () -> Hash[Symbol, untyped]
     def to_h
@@ -507,10 +563,10 @@ module CMDx
         state:,
         status:,
         outcome:,
+        reason:,
         metadata:
       ).tap do |hash|
         if interrupted?
-          hash[:reason] = reason
           hash[:cause] = cause
           hash[:rolled_back] = rolled_back?
         end

data/lib/cmdx/settings.rb

@@ -113,6 +113,10 @@ module CMDx
     #   @return [Boolean] true if backtraces should be logged
     delegate_to_configuration :backtrace
 
+    # @!attribute [rw] dump_context
+    #   @return [Boolean] true if context should be included in Task#to_h
+    delegate_to_configuration :dump_context
+
     # @!attribute [rw] rollback_on
     #   @return [Array<String>] Statuses that trigger rollback
     delegate_to_configuration :rollback_on

data/lib/cmdx/task.rb

@@ -70,7 +70,7 @@ module CMDx
     # @rbs @chain: Chain
     attr_reader :chain
 
-    def_delegators :result, :skip!, :fail!, :throw!
+    def_delegators :result, :success!, :skip!, :fail!, :throw!
     def_delegators :chain, :dry_run?
 
     # @param context [Hash, Context, nil] The initial context for the task
@@ -376,6 +376,7 @@ module CMDx
     # @option return [Array<Symbol>] :tags The task tags
     # @option return [String] :class The task class name
     # @option return [String] :id The task identifier
+    # @option return [Hash] :context The task context (when dump_context is true)
     #
     # @return [Hash] A hash representation of the task
     #
@@ -394,7 +395,13 @@ module CMDx
         id:,
         dry_run: dry_run?,
         tags: self.class.settings.tags
-      }
+      }.tap do |hash|
+        if self.class.settings.dump_context
+          # Large context can make dumps and logs very noisy,
+          # so only include it if explicitly enabled
+          hash[:context] = context.to_h
+        end
+      end
     end
 
     # @return [String] A string representation of the task

data/lib/cmdx/version.rb

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

data/lib/cmdx/workflow.rb

@@ -73,6 +73,23 @@ module CMDx
       end
       alias task tasks
 
+      # Returns all tasks in the pipeline.
+      #
+      # @return [Array<Class>] Array of task classes
+      #
+      # @example
+      #   class MyWorkflow
+      #     include CMDx::Workflow
+      #     task Task1
+      #     task Task2
+      #     puts subtasks.size # => 2
+      #   end
+      #
+      # @rbs () -> Array[Class]
+      def subtasks
+        pipeline.flat_map(&:tasks)
+      end
+
     end
 
     # Represents a group of tasks with shared execution options.

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

@@ -10,7 +10,7 @@ CMDx.configure do |config|
 
   # Workflow breakpoint configuration - controls when workflows stop execution
   # When a task returns these statuses, subsequent workflow tasks won't execute
-  # See https://github.com/drexed/cmdx/blob/main/docs/workflow.md for more details
+  # See https://github.com/drexed/cmdx/blob/main/docs/workflows.md for more details
   #
   # Available statuses: "success", "skipped", "failed"
   # If set to an empty array, workflow will never halt
@@ -44,18 +44,22 @@ CMDx.configure do |config|
   # config.default_locale = "en"
 
   # Backtrace configuration - controls whether to log backtraces on faults and exceptions
-  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#backtraces
+  # https://github.com/drexed/cmdx/blob/main/docs/configuration.md#backtraces
   # config.backtrace = false
   # config.backtrace_cleaner = nil
 
   # Exception handler configuration - called when non-fault exceptions are raised
-  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#exception-handler
+  # https://github.com/drexed/cmdx/blob/main/docs/configuration.md#exception-handlers
   # config.exception_handler = nil
 
+  # Dump context configuration - include context data in hash representation output
+  # https://github.com/drexed/cmdx/blob/main/docs/configuration.md#dump-context
+  # config.dump_context = false
+
   # Additional global configurations - automatically applied to all tasks
   #
   # Middlewares - https://github.com/drexed/cmdx/blob/main/docs/middlewares.md
   # Callbacks - https://github.com/drexed/cmdx/blob/main/docs/callbacks.md
-  # Coercions - https://github.com/drexed/cmdx/blob/main/docs/coercions.md
-  # Validations - https://github.com/drexed/cmdx/blob/main/docs/validations.md
+  # Coercions - https://github.com/drexed/cmdx/blob/main/docs/attributes/coercions.md
+  # Validations - https://github.com/drexed/cmdx/blob/main/docs/attributes/validations.md
 end

data/lib/locales/af.yml

@@ -13,6 +13,8 @@ af:
     faults:
       invalid: "Ongeldig"
       unspecified: "Ongespesifiseer"
+    reasons:
+      unspecified: "Ongespesifiseer"
     types:
       array: "skikking"
       big_decimal: "groot desimale"

data/lib/locales/ar.yml

@@ -13,6 +13,8 @@ ar:
     faults:
       invalid: "غير صالح"
       unspecified: "غير محدد"
+    reasons:
+      unspecified: "غير محدد"
     types:
       array: "مصفوفة"
       big_decimal: "عدد عشري كبير"

data/lib/locales/az.yml

@@ -13,6 +13,8 @@ az:
     faults:
       invalid: "Etibarsız"
       unspecified: "Göstərilməyib"
+    reasons:
+      unspecified: "Göstərilməyib"
     types:
       array: "massiv"
       big_decimal: "böyük onluq"

data/lib/locales/be.yml

@@ -13,6 +13,8 @@ be:
     faults:
       invalid: "Няправільныя"
       unspecified: "Не паказана"
+    reasons:
+      unspecified: "Не паказана"
     types:
       array: "масіў"
       big_decimal: "вялікае дзесятковае лік"

data/lib/locales/bg.yml

@@ -13,6 +13,8 @@ bg:
     faults:
       invalid: "Невалидни"
       unspecified: "Не е посочена"
+    reasons:
+      unspecified: "Не е посочена"
     types:
       array: "масив"
       big_decimal: "голямо десетично число"

data/lib/locales/bn.yml

@@ -13,6 +13,8 @@ bn:
     faults:
       invalid: "অবৈধ"
       unspecified: "অনির্দিষ্ট"
+    reasons:
+      unspecified: "অনির্দিষ্ট"
     types:
       array: "অ্যারে"
       big_decimal: "বড় দশমিক"

data/lib/locales/bs.yml

@@ -13,6 +13,8 @@ bs:
     faults:
       invalid: "Neispravni"
       unspecified: "Nije naveden"
+    reasons:
+      unspecified: "Nije naveden"
     types:
       array: "niz"
       big_decimal: "veliki decimalni broj"

data/lib/locales/ca.yml

@@ -13,6 +13,8 @@ ca:
     faults:
       invalid: "No vàlides"
       unspecified: "No especificat"
+    reasons:
+      unspecified: "No especificat"
     types:
       array: "array"
       big_decimal: "decimal gran"

data/lib/locales/cnr.yml

@@ -13,6 +13,8 @@ cnr:
     faults:
       invalid: "Neispravni"
       unspecified: "Nije dat"
+    reasons:
+      unspecified: "Nije dat"
     types:
       array: "niz"
       big_decimal: "veliki decimalni"

data/lib/locales/cs.yml

@@ -13,6 +13,8 @@ cs:
     faults:
       invalid: "Neplatné"
       unspecified: "Neurčeno"
+    reasons:
+      unspecified: "Neurčeno"
     types:
       array: "pole"
       big_decimal: "velké desetinné číslo"

data/lib/locales/cy.yml

@@ -13,6 +13,8 @@ cy:
     faults:
       invalid: "Annilys"
       unspecified: "Anhebgor"
+    reasons:
+      unspecified: "Anhebgor"
     types:
       array: "arae"
       big_decimal: "degol mawr"

data/lib/locales/da.yml

@@ -13,6 +13,8 @@ da:
     faults:
       invalid: "Ugyldige"
       unspecified: "Uspecificeret"
+    reasons:
+      unspecified: "Uspecificeret"
     types:
       array: "array"
       big_decimal: "stort decimaltal"

data/lib/locales/de.yml

@@ -13,6 +13,8 @@ de:
     faults:
       invalid: "Ungültig"
       unspecified: "Nicht angegeben"
+    reasons:
+      unspecified: "Nicht angegeben"
     types:
       array: "Array"
       big_decimal: "große Dezimalzahl"

data/lib/locales/dz.yml

@@ -13,6 +13,8 @@ dz:
     faults:
       invalid: "ཆ་རྐྱེན་མི་ཆོག"
       unspecified: "མ་བཟུང་།"
+    reasons:
+      unspecified: "མ་བཟུང་།"
     types:
       array: "ཐིག་ཕྲེང་།"
       big_decimal: "ཆེ་བའི་བཅུ་ཆ།"

data/lib/locales/el.yml

@@ -13,6 +13,8 @@ el:
     faults:
       invalid: "Μη έγκυρες"
       unspecified: "Απροσδιόριστο"
+    reasons:
+      unspecified: "Απροσδιόριστο"
     types:
       array: "πίνακας"
       big_decimal: "μεγάλος δεκαδικός"

data/lib/locales/en.yml

@@ -11,6 +11,8 @@ en:
     faults:
       invalid: "Invalid"
       unspecified: "Unspecified"
+    reasons:
+      unspecified: "Unspecified"
     returns:
       missing: "must be set in the context"
     types:

data/lib/locales/eo.yml

@@ -13,6 +13,8 @@ eo:
     faults:
       invalid: "Nevalidaj"
       unspecified: "Nespecifita"
+    reasons:
+      unspecified: "Nespecifita"
     types:
       array: "tabelo"
       big_decimal: "granda dekuma"

data/lib/locales/es.yml

@@ -13,6 +13,8 @@ es:
     faults:
       invalid: "Inválidas"
       unspecified: "No especificada"
+    reasons:
+      unspecified: "No especificada"
     types:
       array: "array"
       big_decimal: "decimal grande"

data/lib/locales/et.yml

@@ -13,6 +13,8 @@ et:
     faults:
       invalid: "Kehtetud"
       unspecified: "Määramata"
+    reasons:
+      unspecified: "Määramata"
     types:
       array: "massiiv"
       big_decimal: "suur kümnendmurd"

data/lib/locales/eu.yml

@@ -13,6 +13,8 @@ eu:
     faults:
       invalid: "Baliogabeak"
       unspecified: "Zehaztu gabe"
+    reasons:
+      unspecified: "Zehaztu gabe"
     types:
       array: "array"
       big_decimal: "hamartar handia"

data/lib/locales/fa.yml

@@ -13,6 +13,8 @@ fa:
     faults:
       invalid: "نامعتبر"
       unspecified: "نامشخص"
+    reasons:
+      unspecified: "نامشخص"
     types:
       array: "آرایه"
       big_decimal: "اعشاری بزرگ"