cmdx 1.7.5 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0238294eeb6dd614280c7c386832d6780ea4005879c1162e7cacc4f97c54d5fd'
-  data.tar.gz: 50c49904dbc84ffa7451a585e443c061b71576498ad00504ee87ae2efff07945
+  metadata.gz: 5ac9af727a0dd815dad8285e7e46d666e3f26f51eb03c3f1ec014c12e4af0e23
+  data.tar.gz: 8279a9ebcf5339fb281cd685cb0484b005f72b2605749f1418baea282be1afdf
 SHA512:
-  metadata.gz: 7bac1596b901e86412d241f81c2c5fa331d2bf05b63c0ef3ee3691dd832c30fa8a187e6d8d4788fe9f3d1760bb8f7b1da62c2701a9a86bac6d9a4b5116f3e490
-  data.tar.gz: 8794c3049d206178d68a4e9446d001668ee8b3a7902569dd1f66d05fe10b67f9cbc59e5264286ebfb075681415f430a3d69c40f181fdbe6f541caf4ec7fb4e56
+  metadata.gz: f97ef5703cacbfa7c51e4e513e214322c330750066e2420727d1bdc6469dac092b4f9b601291c8b0a721cba6bca863d22d4189bf10a8aa4b0ec53683f6598ccc
+  data.tar.gz: 3a1019a2f2db8088ec70821d51c5d13a10554f788a7732a70a8c14830cd9804fee354447e61dae3ca86fcf4a8a664932bdff5465a78256845d224870e78951ce

data/.cursor/prompts/docs.md

@@ -3,10 +3,10 @@ You are a senior Ruby developer with expert knowledge of CMDx and writing docume
 Update the active tab using the following guidelines:
 
 - Follow best practices and implementation
-- Use a consistent professional voice
+- Use a consistent warm, friendly and professional voice
 - Examples should be concise, non-repetitive, and realistic
 - Update any pre-existing documentation to match stated rules
 - Examples should not cross boundaries or focus
-- Docs must cover both typical use cases, including invalid inputs and error conditions
-- Use GitHub flavored markdown, including alerts to emphasize critical information (https://github.com/orgs/community/discussions/16925)
+- Docs must cover both typical use cases, including invalid and error conditions
+- Use mkdocs Admonitions to emphasize critical information (https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
 - Optimize for LLM's including coding and AI agents

data/.cursor/prompts/llms.md

@@ -4,9 +4,7 @@ Process the following instructions in the order given:
 2. Append all files within `docs/**/*.md` into @LLM.md
   2a. Use order outlined in the table of contents of @README.md
   2b. Process one file at a time faster performance and improved accuracy
-  2c. Remove the table of contents from the chunk
-  2c. Remove the navigations below `---` from the chunk
-  2d. Wrap the chunk the files GitHub url the top and a spacer at the bottom like so:
+  2c. Wrap the chunk the files GitHub url the top and a spacer at the bottom like so:
       ```
 
       ---

data/.cursor/prompts/rspec.md

@@ -18,7 +18,7 @@ Add tests for the active tab using the following guidelines:
 - Use clear and descriptive names for describe, context, and it blocks
 - Prefer the expect syntax for assertions to improve readability
 - Keep test code concise; avoid unnecessary complexity or duplication
-- Tests must cover both typical cases and edge cases, including invalid inputs and error conditions
+- Tests must cover both typical cases and edge cases, including Invalid and error conditions
 - Consider all possible scenarios for each method or behavior and ensure they are tested
 - Do NOT include integration or real world examples
 - Verify all specs are passing

data/.irbrc

@@ -2,5 +2,17 @@
 
 require "pp"
 
-# To reload the gem, you must exit and restart the IRB session
-require_relative "lib/cmdx" unless defined?(CMDx)
+# rubocop:disable Style/MixinUsage
+unless defined?(CMDx)
+  require_relative "lib/cmdx"
+
+  require_relative "spec/support/helpers/task_builders"
+  require_relative "spec/support/helpers/workflow_builders"
+  include CMDx::Testing::TaskBuilders
+  include CMDx::Testing::WorkflowBuilders
+end
+# rubocop:enable Style/MixinUsage
+
+def reload!
+  exec("irb")
+end

data/CHANGELOG.md

@@ -6,6 +6,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [UNRELEASED]
 
+## [1.9.0] - 2025-10-21
+
+### Added
+- Added `transform` option to attributes
+- Added option to output failure backtraces
+- Added exception handling for non-bang methods
+- Added durability with automatic retries to execution
+- Added `to_h` hash coercion support
+- Added comprehensive MkDocs configuration with material theme
+
+### Changed
+- Improved performance of task settings setup
+- Improved error messages for raised exceptions
+- Improved inheritance of parent settings
+- Cleaned halt backtrace frames for better readability
+
+### Removed
+- Removed `Freezer` module and moved logic into executor `freeze_execution!` method
+- Removed task parameter from callback signature
+- Removed task and workflow arguments from conditional checks
+- Removed chain persistence after execution in specs
+
+## [1.8.0] - 2025-09-22
+
+### Changed
+- Generalized locale values for fault `invalid` and `unspecified`
+- Nested attribute error messages under `error` key within metadata
+- Reordered logstash formatter keys for consistency
+- Improved error message for already defined items
+- Changed hash coercion for `nil` to return `{}`
+
 ## [1.7.5] - 2025-09-10
 
 ### Added
@@ -22,69 +53,71 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [1.7.3] - 2025-09-03
 
-### Changes
-- Return generic validation reason
-- Move validation full message string to `:full_message` within metadata
+### Changed
+- Changed validation reasons to use generic values
+- Moved validation full message string to `:full_message` key within metadata
 
 ## [1.7.2] - 2025-09-03
 
-### Changes
-- Correlation ID is set before continuing to further steps
+### Changed
+- Changed correlation ID to be set before continuing to further steps
 
 ## [1.7.1] - 2025-08-26
 
 ### Added
-- Yield result if block given to `execute` and `execute!` methods
+- Added result yielding when block is given to `execute` and `execute!` methods
 
 ## [1.7.0] - 2025-08-25
 
 ### Added
-- Workflow generator
+- Added workflow generator
 
-### Changes
-- Port over `cmdx-parallel` changes
-- Port over `cmdx-i18n` changes
+### Changed
+- Ported `cmdx-parallel` changes into core
+- Ported `cmdx-i18n` changes into core
 
 ## [1.6.2] - 2025-08-24
 
-### Changes
-- Prefix railtie I18n with `::` to play nice with `CMDx::I18n`
-- Use `cmdx-rspec` for matchers support
+### Changed
+- Prefixed railtie I18n with `::` for compatibility with `CMDx::I18n`
+- Changed to use `cmdx-rspec` for matchers support
 
 ## [1.6.1] - 2025-08-23
 
-### Changes
-- Log task results before freezing
-- Rename `execute_tasks_sequentially` to `execute_tasks_in_sequence`
+### Changed
+- Changed task results to be logged before freezing
+- Renamed `execute_tasks_sequentially` to `execute_tasks_in_sequence`
 
 ## [1.6.0] - 2025-08-22
 
-### Changes
-- Rename `Worker` class to `Executor`
-- Move workflow `work` logic into `Pipeline`
-- Add workflow task `:breakpoints`
+### Added
+- Added workflow task `:breakpoints` support
+
+### Changed
+- Renamed `Worker` class to `Executor`
+- Moved workflow `work` logic into `Pipeline`
 
 ## [1.5.2] - 2025-08-22
 
-### Changes
-- Rename workflow `execution_groups` attribute to `pipeline`
+### Changed
+- Renamed workflow `execution_groups` attribute to `pipeline`
 
 ## [1.5.1] - 2025-08-21
 
-### Changes
-- Prefix locale I18n with `::` to play nice with `CMDx::I18n`
-- Safe navigate length and numeric validators
-- Update railtie file path points to correct directory
+### Changed
+- Prefixed locale I18n with `::` for compatibility with `CMDx::I18n`
+- Added safe navigation to length and numeric validators
+- Updated railtie file path to point to correct directory
 
 ## [1.5.0] - 2025-08-21
 
-### Changes
-- BREAKING - Revamp CMDx for clarity, transparency, and higher performance
+### Changed
+- **BREAKING**: Revamped CMDx for improved clarity, transparency, and higher performance
 
 ## [1.1.2] - 2025-07-20
 
 ### Changed
-- All items between versions `0.1.0` and `1.1.2` should be reviewed within its own tag
+- All changes between versions `0.1.0` and `1.1.2` should be reviewed within their respective git tags
 
 ## [0.1.0] - 2025-03-07
 

data/LLM.md

@@ -87,6 +87,45 @@ CMDx.configure do |config|
 end
 ```
 
+### Backtraces
+
+Enable backtraces to be logged on any non-fault exceptions for improved debugging context. Run them through a cleaner to remove unwanted stack trace noise.
+
+> [!NOTE]
+> The `backtrace_cleaner` is set to `Rails.backtrace_cleaner.clean` in a Rails env by default.
+
+```ruby
+CMDx.configure do |config|
+  # Truthy
+  config.backtrace = true
+
+  # Via callable (must respond to `call(backtrace)`)
+  config.backtrace_cleaner = AdvanceCleaner.new
+
+  # Via proc or lambda
+  config.backtrace_cleaner = ->(backtrace) { backtrace[0..5] }
+end
+```
+
+### Exception Handlers
+
+Use exception handlers are called on non-fault standard error based exceptions.
+
+> [!TIP]
+> Use exception handlers to send errors to your APM of choice.
+
+```ruby
+CMDx.configure do |config|
+  # Via callable (must respond to `call(task, exception)`)
+  config.exception_handler = NewRelicReporter
+
+  # Via proc or lambda
+  config.exception_handler = proc do |task, exception|
+    APMService.report(exception, extra_data: { task: task.name, id: task.id })
+  end
+end
+```
+
 ### Logging
 
 ```ruby
@@ -213,6 +252,8 @@ class GenerateInvoice < CMDx::Task
     # Global configuration overrides
     task_breakpoints: ["failed"],                # Breakpoint override
     workflow_breakpoints: [],                    # Breakpoint override
+    backtrace: true,                             # Toggle backtrace
+    backtrace_cleaner: ->(bt) { bt[0..5] },      # Backtrace cleaner
     logger: CustomLogger.new($stdout),           # Custom logger
 
     # Task configuration settings
@@ -220,7 +261,10 @@ class GenerateInvoice < CMDx::Task
     log_level: :info,                            # Log level override
     log_formatter: CMDx::LogFormatters::Json.new # Log formatter override
     tags: ["billing", "financial"],              # Logging tags
-    deprecated: true                             # Task deprecations
+    deprecated: true,                            # Task deprecations
+    retries: 3,                                  # Non-fault exception retries
+    retry_on: [External::ApiError],              # List of exceptions to retry on
+    retry_jitter: 1                              # Space between retry iteration, eg: current retry num + 1
   )
 
   def work
@@ -229,8 +273,8 @@ class GenerateInvoice < CMDx::Task
 end
 ```
 
-> [!TIP]
-> Use task-level settings for tasks that require special handling, such as financial reporting, external API integrations, or critical system operations.
+> [!IMPORTANT]
+> Retries reuse the same context when executing its work. By default all `StandardErrors` will be retried if no `retry_on` option is passed.
 
 ### Registrations
 
@@ -783,7 +827,7 @@ result = ProcessInventory.execute(inventory_id: 456)
 result.status #=> "skipped"
 
 # Without a reason
-result.reason #=> "No reason given"
+result.reason #=> "Unspecified"
 
 # With a reason
 result.reason #=> "Warehouse closed"
@@ -818,7 +862,7 @@ result = ProcessRefund.execute(refund_id: 789)
 result.status #=> "failed"
 
 # Without a reason
-result.reason #=> "No reason given"
+result.reason #=> "Unspecified"
 
 # With a reason
 result.reason #=> "Refund period has expired"
@@ -938,8 +982,28 @@ skip!("Paused")
 fail!("Unsupported")
 
 # Bad: Default, cannot determine reason
-skip! #=> "No reason given"
-fail! #=> "No reason given"
+skip! #=> "Unspecified"
+fail! #=> "Unspecified"
+```
+
+## Manual Errors
+
+There are rare cases where you need to manually assign errors.
+
+> [!IMPORTANT]
+> Keep in mind you will still need to initiate a fault if a stoppage of work is required.
+
+```ruby
+class ProcessRenewal < CMDx::Task
+  def work
+    if document.nonrenewable?
+      errors.add(:document, "not renewable")
+      fail!("document could not be renewed")
+    else
+      document.renew!
+    end
+  end
+end
 ```
 
 ---
@@ -1150,6 +1214,9 @@ result.reason   #=> "[ActiveRecord::NotFoundError] record not found"
 result.cause    #=> <ActiveRecord::NotFoundError>
 ```
 
+> [!NOTE]
+> The `exception_handler` setting only works with non-bang execution as it catches all exceptions preventing them from reaching your apps global error handler.
+
 ### Bang execution
 
 The `execute!` method allows unhandled exceptions to propagate, enabling standard Ruby exception handling while respecting CMDx fault configuration.
@@ -1301,19 +1368,19 @@ result = BuildApplication.execute(version: "1.2.3")
 
 # Status-based handlers
 result
-  .on_success { |result| notify_deployment_ready(result) }
-  .on_failed { |result| handle_build_failure(result) }
-  .on_skipped { |result| log_skip_reason(result) }
+  .handle_success { |result| notify_deployment_ready(result) }
+  .handle_failed { |result| handle_build_failure(result) }
+  .handle_skipped { |result| log_skip_reason(result) }
 
 # State-based handlers
 result
-  .on_complete { |result| update_build_status(result) }
-  .on_interrupted { |result| cleanup_partial_artifacts(result) }
+  .handle_complete { |result| update_build_status(result) }
+  .handle_interrupted { |result| cleanup_partial_artifacts(result) }
 
 # Outcome-based handlers
 result
-  .on_good { |result| increment_success_counter(result) }
-  .on_bad { |result| alert_operations_team(result) }
+  .handle_good { |result| increment_success_counter(result) }
+  .handle_bad { |result| alert_operations_team(result) }
 ```
 
 ## Pattern Matching
@@ -1435,9 +1502,9 @@ 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) }
 ```
 
 ---
@@ -1500,14 +1567,14 @@ 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) }
 ```
 
 ---
@@ -1754,12 +1821,14 @@ result = ConfigureServer.execute(server_id: "srv-001")
 
 result.state    #=> "interrupted"
 result.status   #=> "failed"
-result.reason   #=> "Invalid inputs"
+result.reason   #=> "Invalid"
 result.metadata #=> {
-                #     full_message: "environment is required. network_config is required.",
-                #     messages: {
-                #       environment: ["is required"],
-                #       network_config: ["is required"]
+                #     errors: {
+                #       full_message: "environment is required. network_config is required.",
+                #       messages: {
+                #         environment: ["is required"],
+                #         network_config: ["is required"]
+                #       }
                 #     }
                 #   }
 
@@ -1772,11 +1841,13 @@ result = ConfigureServer.execute(
 
 result.state    #=> "interrupted"
 result.status   #=> "failed"
-result.reason   #=> "Invalid inputs"
+result.reason   #=> "Invalid"
 result.metadata #=> {
-                #     full_message: "port is required.",
-                #     messages: {
-                #       port: ["is required"]
+                #     errors: {
+                #       full_message: "port is required.",
+                #       messages: {
+                #         port: ["is required"]
+                #       }
                 #     }
                 #   }
 ```
@@ -2000,12 +2071,14 @@ result = AnalyzePerformance.execute(
 
 result.state    #=> "interrupted"
 result.status   #=> "failed"
-result.reason   #=> "Invalid inputs"
+result.reason   #=> "Invalid"
 result.metadata #=> {
-                #     full_message: "iterations could not coerce into an integer. score could not coerce into one of: float, big_decimal.",
-                #     messages: {
-                #       iterations: ["could not coerce into an integer"],
-                #       score: ["could not coerce into one of: float, big_decimal"]
+                #     errors: {
+                #       full_message: "iterations could not coerce into an integer. score could not coerce into one of: float, big_decimal.",
+                #       messages: {
+                #         iterations: ["could not coerce into an integer"],
+                #         score: ["could not coerce into one of: float, big_decimal"]
+                #       }
                 #     }
                 #   }
 ```
@@ -2294,14 +2367,16 @@ result = CreateProject.execute(
 
 result.state    #=> "interrupted"
 result.status   #=> "failed"
-result.reason   #=> "Invalid inputs"
+result.reason   #=> "Invalid"
 result.metadata #=> {
-                #     full_message: "project_name is too short (minimum is 3 characters). budget must be greater than 1000. priority is not included in the list. contact_email is invalid.",
-                #     messages: {
-                #       project_name: ["is too short (minimum is 3 characters)"],
-                #       budget: ["must be greater than 1000"],
-                #       priority: ["is not included in the list"],
-                #       contact_email: ["is invalid"]
+                #     errors: {
+                #       full_message: "project_name is too short (minimum is 3 characters). budget must be greater than 1000. priority is not included in the list. contact_email is invalid.",
+                #       messages: {
+                #         project_name: ["is too short (minimum is 3 characters)"],
+                #         budget: ["must be greater than 1000"],
+                #         priority: ["is not included in the list"],
+                #         contact_email: ["is invalid"]
+                #       }
                 #     }
                 #   }
 ```
@@ -2391,6 +2466,80 @@ end
 
 ---
 
+url: https://github.com/drexed/cmdx/blob/main/docs/attributes/transformations.md
+---
+
+# Attributes - Transformations
+
+Transformations allow you to modify attribute values after they are derived and coerced from their source but before any validations. This enables data normalization, formatting, and conditional processing within the attribute pipeline.
+
+## Declarations
+
+### Symbol References
+
+Reference instance methods by symbol for dynamic value transformations:
+
+```ruby
+class ProcessAnalytics < CMDx::Task
+  attribute :options, transform: :compact_blank
+end
+```
+
+### Proc or Lambda
+
+Use anonymous functions for dynamic value transformations:
+
+```ruby
+class CacheContent < CMDx::Task
+  # Proc
+  attribute :expire_hours, transform: proc { |v| v * 2 }
+
+  # Lambda
+  attribute :compression, transform: ->(v) { v.to_s.upcase.strip[0..2]  }
+end
+```
+
+### Class or Module
+
+Use any object that responds to `call` for reusable transformation logic:
+
+```ruby
+class EmailNormalizer
+  def call(value)
+    value.to_s.downcase.strip
+  end
+end
+
+class ProcessContacts < CMDx::Task
+  # Class or Module
+  attribute :email, transform: EmailNormalizer
+
+  # Instance
+  attribute :email, transform: EmailNormalizer.new
+end
+```
+
+## Validations
+
+Transformed values are subject to the same validation rules as untransformed values, ensuring consistency and catching configuration errors early.
+
+```ruby
+class ScheduleBackup < CMDx::Task
+  # Coercions
+  attribute :retention_days, type: :integer, transform: proc { |v| v.clamp(1, 5) }
+
+  # Validations
+  optional :frequency, transform: :downcase, inclusion: { in: %w[hourly daily weekly monthly] }
+end
+```
+
+---
+
+- **Prev:** [Attributes - Defaults](defaults.md)
+- **Next:** [Callbacks](../callbacks.md)
+
+---
+
 url: https://github.com/drexed/cmdx/blob/main/docs/callbacks.md
 ---
 
@@ -2459,7 +2608,7 @@ Use anonymous functions for inline callback logic:
 ```ruby
 class ProcessBooking < CMDx::Task
   # Proc
-  on_interrupted proc { |task| ReservationSystem.pause! }
+  on_interrupted proc { ReservationSystem.pause! }
 
   # Lambda
   on_complete -> { ReservationSystem.resume! }
@@ -2506,10 +2655,10 @@ class ProcessBooking < CMDx::Task
   before_execution :notify_guest, if: :messaging_enabled?, unless: :messaging_blocked?
 
   # Proc
-  on_failure :increment_failure, if: ->(task) { Rails.env.production? && task.class.name.include?("Legacy") }
+  on_failure :increment_failure, if: -> { Rails.env.production? && self.class.name.include?("Legacy") }
 
   # Lambda
-  on_success :ping_housekeeping, if: proc { |task| task.context.rooms_need_cleaning? }
+  on_success :ping_housekeeping, if: proc { context.rooms_need_cleaning? }
 
   # Class or Module
   on_complete :send_confirmation, unless: MessagingPermissionCheck
@@ -2524,7 +2673,7 @@ class ProcessBooking < CMDx::Task
   private
 
   def messaging_enabled?
-    context.guest.messaging_preference.present?
+    context.guest.messaging_preference == true
   end
 
   def messaging_blocked?
@@ -3048,7 +3197,7 @@ result = ProcessOldData.execute
 result.successful? #=> true
 
 # Ruby warning appears in stderr:
-# [ProcessOldData] DEPRECATED: migrate to replacement or discontinue use
+# [ProcessOldData] DEPRECATED: migrate to a replacement or discontinue use
 ```
 
 ## Declarations
@@ -3199,10 +3348,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
@@ -3216,7 +3365,7 @@ class OnboardingWorkflow < CMDx::Task
   private
 
   def email_configured?
-    context.user.email_address.present?
+    context.user.email_address == true
   end
 
   def email_disabled?
@@ -3508,33 +3657,9 @@ 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
+## Advance Examples
 
-# 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
-```
+- [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)
 
 ---