cmdx 1.8.0 → 1.9.1

data/docs/outcomes/states.md

@@ -1,16 +1,6 @@
 # Outcomes - States
 
-States represent the execution lifecycle condition of task execution, tracking
-the progress of tasks through their complete execution journey. States provide
-insight into where a task is in its lifecycle and enable lifecycle-based
-decision making and monitoring.
-
-## Table of Contents
-
-- [Definitions](#definitions)
-- [Transitions](#transitions)
-- [Predicates](#predicates)
-- [Handlers](#handlers)
+States track where a task is in its execution lifecycle—from creation through completion or interruption.
 
 ## Definitions
 
@@ -34,8 +24,9 @@ State-Status combinations:
 
 ## Transitions
 
-> [!CAUTION]
-> States are automatically managed during task execution and should **never** be modified manually. State transitions are handled internally by the CMDx framework.
+!!! danger "Caution"
+
+    States are managed automatically—never modify them manually.
 
 ```ruby
 # Valid state transition flow
@@ -62,19 +53,14 @@ result.executed?    #=> true (complete OR interrupted)
 
 ## Handlers
 
-Use state-based handlers for lifecycle event handling. The `on_executed` handler is particularly useful for cleanup operations that should run regardless of success, skipped, or failure.
+Handle lifecycle events with state-based handlers. Use `handle_executed` for cleanup that runs regardless of outcome:
 
 ```ruby
 result = ProcessVideoUpload.execute
 
 # Individual state handlers
 result
-  .on_complete { |result| send_upload_notification(result) }
-  .on_interrupted { |result| cleanup_temp_files(result) }
-  .on_executed { |result| log_upload_metrics(result) }
+  .handle_complete { |result| send_upload_notification(result) }
+  .handle_interrupted { |result| cleanup_temp_files(result) }
+  .handle_executed { |result| log_upload_metrics(result) }
 ```
-
----
-
-- **Prev:** [Outcomes - Result](result.md)
-- **Next:** [Outcomes - Statuses](statuses.md)

data/docs/outcomes/statuses.md

@@ -1,13 +1,6 @@
 # Outcomes - Statuses
 
-Statuses represent the business outcome of task execution logic, indicating how the task's business logic concluded. Statuses differ from execution states by focusing on the business outcome rather than the technical execution lifecycle. Understanding statuses is crucial for implementing proper business logic branching and error handling.
-
-## Table of Contents
-
-- [Definitions](#definitions)
-- [Transitions](#transitions)
-- [Predicates](#predicates)
-- [Handlers](#handlers)
+Statuses represent the business outcome—did the task succeed, skip, or fail? This differs from state, which tracks the execution lifecycle.
 
 ## Definitions
 
@@ -19,8 +12,9 @@ Statuses represent the business outcome of task execution logic, indicating how
 
 ## Transitions
 
-> [!IMPORTANT]
-> Status transitions are unidirectional and final. Once a task is marked as skipped or failed, it cannot return to success status. Design your business logic accordingly.
+!!! warning "Important"
+
+    Status transitions are final and unidirectional. Once skipped or failed, tasks can't return to success.
 
 ```ruby
 # Valid status transitions
@@ -53,24 +47,19 @@ result.bad?     #=> true if skipped OR failed (not success)
 
 ## Handlers
 
-Use status-based handlers for business logic branching. The `on_good` and `on_bad` handlers are particularly useful for handling success/skip vs failed outcomes respectively.
+Branch business logic with status-based handlers. Use `handle_good` and `handle_bad` for success/skip vs failed outcomes:
 
 ```ruby
 result = ProcessNotification.execute
 
 # Individual status handlers
 result
-  .on_success { |result| mark_notification_sent(result) }
-  .on_skipped { |result| log_notification_skipped(result) }
-  .on_failed { |result| queue_retry_notification(result) }
+  .handle_success { |result| mark_notification_sent(result) }
+  .handle_skipped { |result| log_notification_skipped(result) }
+  .handle_failed { |result| queue_retry_notification(result) }
 
 # Outcome-based handlers
 result
-  .on_good { |result| update_message_stats(result) }
-  .on_bad { |result| track_delivery_failure(result) }
+  .handle_good { |result| update_message_stats(result) }
+  .handle_bad { |result| track_delivery_failure(result) }
 ```
-
----
-
-- **Prev:** [Outcomes - States](states.md)
-- **Next:** [Attributes - Definitions](../attributes/definitions.md)

data/docs/stylesheets/extra.css

@@ -0,0 +1,42 @@
+:root  > * {
+  /* Primary color shades */
+  --md-primary-fg-color:        #fe1817;
+  --md-primary-fg-color--light: #fe1817;
+  --md-primary-fg-color--dark:  #fe1817;
+
+  /* Accent color shades */
+  --md-accent-fg-color:                hsla(#{hex2hsl(#fe1817)}, 1);
+  --md-accent-fg-color--transparent:   hsla(#{hex2hsl(#fe1817)}, 0.1);
+}
+
+/* Atom One Light Pro syntax highlighting */
+[data-md-color-scheme="default"] {
+  --md-code-hl-color:            #2c3036;
+  --md-code-hl-keyword-color:    #a626a4;
+  --md-code-hl-string-color:     #50a14f;
+  --md-code-hl-name-color:       #e4564a;
+  --md-code-hl-function-color:   #4078f2;
+  --md-code-hl-number-color:     #ca7601;
+  --md-code-hl-constant-color:   #c18401;
+  --md-code-hl-comment-color:    #9ca0a4;
+  --md-code-hl-operator-color:   #0184bc;
+  --md-code-hl-punctuation-color:#383a42;
+  --md-code-hl-variable-color:   #e4564a;
+  --md-code-hl-generic-color:    #e4564a;
+}
+
+/* Atom One Dark Pro syntax highlighting */
+[data-md-color-scheme="slate"] {
+  --md-code-hl-color:            #e5e5e6;
+  --md-code-hl-keyword-color:    #c678dd;
+  --md-code-hl-string-color:     #98c379;
+  --md-code-hl-name-color:       #e06c75;
+  --md-code-hl-function-color:   #61afef;
+  --md-code-hl-number-color:     #d19a66;
+  --md-code-hl-constant-color:   #d19a66;
+  --md-code-hl-comment-color:    #7f848e;
+  --md-code-hl-operator-color:   #56b6c2;
+  --md-code-hl-punctuation-color:#abb2bf;
+  --md-code-hl-variable-color:   #e06c75;
+  --md-code-hl-generic-color:    #e06c75;
+}

data/docs/tips_and_tricks.md

@@ -1,16 +1,6 @@
 # Tips and Tricks
 
-This guide covers advanced patterns and optimization techniques for getting the most out of CMDx in production applications.
-
-## Table of Contents
-
-- [Project Organization](#project-organization)
-  - [Directory Structure](#directory-structure)
-  - [Naming Conventions](#naming-conventions)
-  - [Story Telling](#story-telling)
-  - [Style Guide](#style-guide)
-- [Attribute Options](#attribute-options)
-- [ActiveRecord Query Tagging](#activerecord-query-tagging)
+Best practices, patterns, and techniques to build maintainable CMDx applications.
 
 ## Project Organization
 
@@ -54,7 +44,7 @@ class TokenGeneration < CMDx::Task; end    # ❌ Avoid
 
 ### Story Telling
 
-Consider using descriptive methods to express the task’s flow, rather than concentrating all logic inside the `work` method.
+Break down complex logic into descriptive methods that read like a narrative:
 
 ```ruby
 class ProcessOrder < CMDx::Task
@@ -86,7 +76,7 @@ end
 
 ### Style Guide
 
-Follow a style pattern for consistent task design:
+Follow this order for consistent, readable tasks:
 
 ```ruby
 class ExportReport < CMDx::Task
@@ -129,7 +119,7 @@ end
 
 ## Attribute Options
 
-Use Rails `with_options` to reduce duplication and improve readability:
+Use `with_options` to reduce duplication:
 
 ```ruby
 class ConfigureCompany < CMDx::Task
@@ -155,36 +145,7 @@ class ConfigureCompany < CMDx::Task
 end
 ```
 
-## ActiveRecord Query Tagging
-
-Automatically tag SQL queries for better debugging:
-
-```ruby
-# config/application.rb
-config.active_record.query_log_tags_enabled = true
-config.active_record.query_log_tags << :cmdx_task_class
-config.active_record.query_log_tags << :cmdx_chain_id
-
-# app/tasks/application_task.rb
-class ApplicationTask < CMDx::Task
-  before_execution :set_execution_context
-
-  private
-
-  def set_execution_context
-    # NOTE: This could easily be made into a middleware
-    ActiveSupport::ExecutionContext.set(
-      cmdx_task_class: self.class.name,
-      cmdx_chain_id: chain.id
-    )
-  end
-end
-
-# SQL queries will now include comments like:
-# /*cmdx_task_class:ExportReportTask,cmdx_chain_id:018c2b95-b764-7615*/ SELECT * FROM reports WHERE id = 1
-```
-
----
+## Advanced Examples
 
-- **Prev:** [Workflows](workflows.md)
-- **Next:** [Getting Started](getting_started.md)
+- [Active Record Query Tagging](https://github.com/drexed/cmdx/blob/main/examples/active_record_query_tagging.md)
+- [Paper Trail Whatdunnit](https://github.com/drexed/cmdx/blob/main/examples/paper_trail_whatdunnit.md)

data/docs/workflows.md

@@ -1,26 +1,14 @@
 # Workflows
 
-Workflow orchestrates sequential execution of multiple tasks in a linear pipeline. Workflows provide a declarative DSL for composing complex business logic from individual task components, with support for conditional execution, context propagation, and configurable halt behavior.
-
-## Table of Contents
-
-- [Declarations](#declarations)
-  - [Task](#task)
-  - [Group](#group)
-  - [Conditionals](#conditionals)
-- [Halt Behavior](#halt-behavior)
-  - [Task Configuration](#task-configuration)
-  - [Group Configuration](#group-configuration)
-- [Nested Workflows](#nested-workflows)
-- [Parallel Execution](#parallel-execution)
-- [Task Generator](#task-generator)
+Compose multiple tasks into powerful, sequential pipelines. Workflows provide a declarative way to build complex business processes with conditional execution, shared context, and flexible error handling.
 
 ## Declarations
 
-Tasks execute sequentially in declaration order (FIFO). The workflow context propagates to each task, allowing access to data from previous executions.
+Tasks run in declaration order (FIFO), sharing a common context across the pipeline.
 
-> [!IMPORTANT]
-> Do **NOT** define a `work` method in workflow tasks. The included module automatically provides the execution logic.
+!!! warning
+
+    Don't define a `work` method in workflows—the module handles execution automatically.
 
 ### Task
 
@@ -35,15 +23,17 @@ class OnboardingWorkflow < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Execute tasks in parallel via the [cmdx-parallel](https://github.com/drexed/cmdx-parallel) gem.
+!!! tip
+
+    Execute tasks in parallel via the [cmdx-parallel](https://github.com/drexed/cmdx-parallel) gem.
 
 ### Group
 
-Group related tasks for better organization and shared configuration:
+Group related tasks to share configuration:
 
-> [!IMPORTANT]
-> Settings and conditionals for a group apply to all tasks within that group.
+!!! warning "Important"
+
+    Settings and conditionals apply to all tasks in the group.
 
 ```ruby
 class ContentModerationWorkflow < CMDx::Task
@@ -78,10 +68,10 @@ class OnboardingWorkflow < CMDx::Task
   task SendWelcomeEmail, if: :email_configured?, unless: :email_disabled?
 
   # Proc
-  task SendWelcomeEmail, if: ->(workflow) { Rails.env.production? && workflow.class.name.include?("Premium") }
+  task SendWelcomeEmail, if: -> { Rails.env.production? && self.class.name.include?("Premium") }
 
   # Lambda
-  task SendWelcomeEmail, if: proc { |workflow| workflow.context.features_enabled? }
+  task SendWelcomeEmail, if: proc { context.features_enabled? }
 
   # Class or Module
   task SendWelcomeEmail, unless: ContentAccessCheck
@@ -95,7 +85,7 @@ class OnboardingWorkflow < CMDx::Task
   private
 
   def email_configured?
-    context.user.email_address.present?
+    context.user.email_address == true
   end
 
   def email_disabled?
@@ -106,9 +96,7 @@ end
 
 ## Halt Behavior
 
-By default skipped tasks are considered no-op executions and does not stop workflow execution.
-This is configurable via global and task level breakpoint settings. Task and group configurations
-can be used together within a workflow.
+By default, skipped tasks don't stop the workflow—they're treated as no-ops. Configure breakpoints globally or per-task to customize this behavior.
 
 ```ruby
 class AnalyticsWorkflow < CMDx::Task
@@ -164,7 +152,7 @@ end
 
 ## Nested Workflows
 
-Workflows can task other workflows for hierarchical composition:
+Build hierarchical workflows by composing workflows within workflows:
 
 ```ruby
 class EmailPreparationWorkflow < CMDx::Task
@@ -191,10 +179,11 @@ end
 
 ## Parallel Execution
 
-Parallel task execution leverages the [Parallel](https://github.com/grosser/parallel) gem, which automatically detects the number of available processors to maximize concurrent task execution.
+Run tasks concurrently using the [Parallel](https://github.com/grosser/parallel) gem. It automatically uses all available processors for maximum throughput.
+
+!!! warning
 
-> [!IMPORTANT]
-> Context cannot be modified during parallel execution. Ensure that all required data is preloaded into the context before parallelization begins.
+    Context is read-only during parallel execution. Load all required data beforehand.
 
 ```ruby
 class SendWelcomeNotifications < CMDx::Task
@@ -232,10 +221,6 @@ class SendNotifications < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`
-
----
+!!! tip
 
-- **Prev:** [Deprecation](deprecation.md)
-- **Next:** [Tips and Tricks](tips_and_tricks.md)
+    Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`

data/examples/active_record_query_tagging.md

@@ -0,0 +1,46 @@
+# Active Record Query Tagging
+
+Add a comment to every query indicating some context to help you track down where that query came from, eg:
+
+```sh
+/*cmdx_task_class:ExportReportTask,cmdx_chain_id:018c2b95-b764-7615*/ SELECT * FROM reports WHERE id = 1
+```
+
+### Setup
+
+```ruby
+# config/application.rb
+config.active_record.query_log_tags_enabled = true
+config.active_record.query_log_tags += [
+  :cmdx_correlation_id,
+  :cmdx_chain_id,
+  :cmdx_task_class,
+  :cmdx_task_id
+]
+
+# lib/cmdx_query_tagging_middleware.rb
+class CmdxQueryTaggingMiddleware
+  def self.call(task, **options, &)
+    ActiveSupport::ExecutionContext.set(
+      cmdx_correlation_id: task.result.metadata[:correlation_id],
+      cmdx_chain_id: task.chain.id,
+      cmdx_task_class: task.class.name,
+      cmdx_task_id: task.id,
+      &
+    )
+  end
+end
+```
+
+### Usage
+
+```ruby
+class MyTask < CMDx::Task
+  register :middleware, CmdxQueryTaggingMiddleware
+
+  def work
+    # Do work...
+  end
+
+end
+```

data/examples/paper_trail_whatdunnit.md

@@ -0,0 +1,39 @@
+# Paper Trail Whatdunnit
+
+Tag paper trail version records with which service made a change with a custom `whatdunnit` attribute.
+
+<https://github.com/paper-trail-gem/paper_trail?tab=readme-ov-file#4c-storing-metadata>
+
+### Setup
+
+```ruby
+# lib/cmdx_paper_trail_middleware.rb
+class CmdxPaperTrailMiddleware
+  def self.call(task, **options, &)
+    # This makes sure to reset the whatdunnit value to the previous
+    # value for nested task calls
+
+    begin
+      PaperTrail.request.controller_info ||= {}
+      old_whatdunnit = PaperTrail.request.controller_info[:whatdunnit]
+      PaperTrail.request.controller_info[:whatdunnit] = task.class.name
+      yield
+    ensure
+      PaperTrail.request.controller_info[:whatdunnit] = old_whatdunnit
+    end
+  end
+end
+```
+
+### Usage
+
+```ruby
+class MyTask < CMDx::Task
+  register :middleware, CmdxPaperTrailMiddleware
+
+  def work
+    # Do work...
+  end
+
+end
+```

data/lib/cmdx/attribute.rb

@@ -6,14 +6,71 @@ module CMDx
   # They can be nested to create complex hierarchical data structures.
   class Attribute
 
+    # @rbs AFFIX: Proc
     AFFIX = proc do |value, &block|
       value == true ? block.call : value
     end.freeze
     private_constant :AFFIX
 
+    # Returns the task instance associated with this attribute.
+    #
+    # @return [CMDx::Task] The task instance
+    #
+    # @example
+    #   attribute.task.context[:user_id] # => 42
+    #
+    # @rbs @task: Task
     attr_accessor :task
 
-    attr_reader :name, :options, :children, :parent, :types
+    # Returns the name of this attribute.
+    #
+    # @return [Symbol] The attribute name
+    #
+    # @example
+    #   attribute.name # => :user_id
+    #
+    # @rbs @name: Symbol
+    attr_reader :name
+
+    # Returns the configuration options for this attribute.
+    #
+    # @return [Hash{Symbol => Object}] Configuration options hash
+    #
+    # @example
+    #   attribute.options # => { required: true, default: 0 }
+    #
+    # @rbs @options: Hash[Symbol, untyped]
+    attr_reader :options
+
+    # Returns the child attributes for nested structures.
+    #
+    # @return [Array<Attribute>] Array of child attributes
+    #
+    # @example
+    #   attribute.children # => [#<Attribute @name=:street>, #<Attribute @name=:city>]
+    #
+    # @rbs @children: Array[Attribute]
+    attr_reader :children
+
+    # Returns the parent attribute if this is a nested attribute.
+    #
+    # @return [Attribute, nil] The parent attribute, or nil if root-level
+    #
+    # @example
+    #   attribute.parent # => #<Attribute @name=:address>
+    #
+    # @rbs @parent: (Attribute | nil)
+    attr_reader :parent
+
+    # Returns the expected type(s) for this attribute's value.
+    #
+    # @return [Array<Class>] Array of expected type classes
+    #
+    # @example
+    #   attribute.types # => [Integer, String]
+    #
+    # @rbs @types: Array[Class]
+    attr_reader :types
 
     # Creates a new attribute with the specified name and configuration.
     #
@@ -35,6 +92,8 @@ module CMDx
     #     required :name, types: String
     #     optional :email, types: String
     #   end
+    #
+    # @rbs ((Symbol | String) name, ?Hash[Symbol, untyped] options) ?{ () -> void } -> void
     def initialize(name, options = {}, &)
       @parent = options.delete(:parent)
       @required = options.delete(:required) || false
@@ -62,11 +121,13 @@ module CMDx
       #
       # @example
       #   Attribute.build(:first_name, :last_name, required: true, types: String)
+      #
+      # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
       def build(*names, **options, &)
         if names.none?
           raise ArgumentError, "no attributes given"
         elsif (names.size > 1) && options.key?(:as)
-          raise ArgumentError, ":as option only supports one attribute per definition"
+          raise ArgumentError, "the :as option only supports one attribute per definition"
         end
 
         names.filter_map { |name| new(name, **options, &) }
@@ -83,6 +144,8 @@ module CMDx
       #
       # @example
       #   Attribute.optional(:description, :tags, types: String)
+      #
+      # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
       def optional(*names, **options, &)
         build(*names, **options.merge(required: false), &)
       end
@@ -98,6 +161,8 @@ module CMDx
       #
       # @example
       #   Attribute.required(:id, :name, types: [Integer, String])
+      #
+      # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
       def required(*names, **options, &)
         build(*names, **options.merge(required: true), &)
       end
@@ -110,6 +175,8 @@ module CMDx
     #
     # @example
     #   attribute.required? # => true
+    #
+    # @rbs () -> bool
     def required?
       !!@required
     end
@@ -120,6 +187,8 @@ module CMDx
     #
     # @example
     #   attribute.source # => :context
+    #
+    # @rbs () -> untyped
     def source
       @source ||= parent&.method_name || begin
         value = options[:source]
@@ -140,6 +209,8 @@ module CMDx
     #
     # @example
     #   attribute.method_name # => :user_name
+    #
+    # @rbs () -> Symbol
     def method_name
       @method_name ||= options[:as] || begin
         prefix = AFFIX.call(options[:prefix]) { "#{source}_" }
@@ -150,6 +221,8 @@ module CMDx
     end
 
     # Defines and verifies the entire attribute tree including nested children.
+    #
+    # @rbs () -> void
     def define_and_verify_tree
       define_and_verify
 
@@ -172,6 +245,8 @@ module CMDx
     #
     # @example
     #   attributes :street, :city, :zip, types: String
+    #
+    # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
     def attributes(*names, **options, &)
       attrs = self.class.build(*names, **options.merge(parent: self), &)
       children.concat(attrs)
@@ -189,6 +264,8 @@ module CMDx
     #
     # @example
     #   optional :middle_name, :nickname, types: String
+    #
+    # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
     def optional(*names, **options, &)
       attributes(*names, **options.merge(required: false), &)
     end
@@ -204,6 +281,8 @@ module CMDx
     #
     # @example
     #   required :first_name, :last_name, types: String
+    #
+    # @rbs (*untyped names, **untyped options) ?{ () -> void } -> Array[Attribute]
     def required(*names, **options, &)
       attributes(*names, **options.merge(required: true), &)
     end
@@ -211,12 +290,15 @@ module CMDx
     # Defines the attribute method on the task and validates the configuration.
     #
     # @raise [RuntimeError] When the method name is already defined on the task
+    #
+    # @rbs () -> void
     def define_and_verify
       if task.respond_to?(method_name, true)
-        raise <<~MESSAGE.gsub!(/[[:space:]]+/, " ").strip!
-          #{task.class.name}##{method_name} already defined.
-          Use :as, :prefix, or :suffix option to avoid
-          conflicts with existing methods
+        raise <<~MESSAGE
+          The method #{method_name.inspect} is already defined on the #{task.class.name} task.
+          This may be due conflicts with one of the task's user defined or internal methods/attributes.
+
+          Use :as, :prefix, and/or :suffix attribute options to avoid conflicts with existing methods.
         MESSAGE
       end