cmdx 1.8.0 → 1.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85aac46372133bca5764f5bfe14b1809e5a910aed2c449660d2d1123d79540f1
-  data.tar.gz: 4e377e2bd36936a83f8f244ddea45e2af05277daecbf5e49db76f4cb38fe46fd
+  metadata.gz: 9220688eed061c4c48562665fe9c2c780a2ecc08642eeaedb095d6bfc312e643
+  data.tar.gz: f470f2ccebce524942277865f2967979244dde07ba1a43095c7f95209127c635
 SHA512:
-  metadata.gz: 38fec1c99ea4cb1cdd7639f65d85c76aeeac37fa1be3410344a2dda709e2a1f34cdf26d3b50cc7c7309a7234c756def0db8e2feb083972783018f6f4fc2fade1
-  data.tar.gz: d08526598534fddb102297b1312304696bb4ffd6783d3549f7b4332cd83c8895cda84faeb1d427b14c8f60ae8a30839e983c1a649dcace3da1ec6a6978ab079d
+  metadata.gz: 155e2d09a4ca6147a7df578b0f2952ab81e781d5c492d821a4b71b08b41ef510cfccade001cc2e593f08ea1876ba6e5b658595a2bddaf6919f243c8df07d0569
+  data.tar.gz: fd0dba94495d6d139dc13507169143ee83f13dfac521d6ef607800c6d6e4cfd13e47cc03e2f27e047b185a0b9ebfc0a9d080143f7c6c2ec61aec139f38ea17cd

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 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/yardoc.md

@@ -12,3 +12,4 @@ Add yardoc to the active tab using the following guidelines:
 - Method level docs should include `@example`, `param`, `@options`, `@return`, and any `@raise`
 - Hash `@params` should expand with possible `@option`
 - Module and method level docs should NOT include `@since`
+- Add RBS inline comments after YARDoc block

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

@@ -4,27 +4,44 @@ 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).
 
-## [TODO]
-- Update exceptions with more info on how to fix the issue
-- Add trnasform option to attributes
-- Add option to output failure backtraces
-- Add durability (retries) to execution
- - N-retries (3 default)
- - Backoff strategy
- - On specific errors
-
 ## [UNRELEASED]
 
-- N/A
+## [1.9.1] - 2025-10-22
+
+### Added
+- Added RBS inlines type signatures
+- Added YARDocs for `attr_reader` and `attr_accessor` methods
+
+## [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
 
-### Changes
-- Generalize locale values for fault `invalid` and `unspecified`
-- Nest attribute error messages under `error` key within metadata
-- Reordered logstash formatter keys
-- Improved already defined error message
-- Hash coercion for `nil` returns `{}`
+### 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
 
@@ -42,69 +59,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
 
@@ -328,6 +372,15 @@ end
 > [!TIP]
 > Use **present tense verbs + noun** for task names, eg: `ModerateBlogPost`, `ScheduleAppointment`, `ValidateDocument`
 
+## Type safety
+
+CMDx includes built-in RBS (Ruby Type Signature) inline annotations throughout the codebase, providing type information for static analysis and editor support.
+
+- **Type checking** — Catch type errors before runtime using tools like Steep or TypeProf
+- **Better IDE support** — Enhanced autocomplete, navigation, and inline documentation
+- **Self-documenting code** — Clear method signatures and return types
+- **Refactoring confidence** — Type-aware refactoring reduces bugs
+
 ---
 
 url: https://github.com/drexed/cmdx/blob/main/docs/basics/setup.md
@@ -1170,6 +1223,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.
@@ -1321,19 +1377,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
@@ -1455,9 +1511,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) }
 ```
 
 ---
@@ -1520,14 +1576,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) }
 ```
 
 ---
@@ -2419,6 +2475,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
 ---
 
@@ -2487,7 +2617,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! }
@@ -2534,10 +2664,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
@@ -2552,7 +2682,7 @@ class ProcessBooking < CMDx::Task
   private
 
   def messaging_enabled?
-    context.guest.messaging_preference.present?
+    context.guest.messaging_preference == true
   end
 
   def messaging_blocked?
@@ -3076,7 +3206,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
@@ -3227,10 +3357,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
@@ -3244,7 +3374,7 @@ class OnboardingWorkflow < CMDx::Task
   private
 
   def email_configured?
-    context.user.email_address.present?
+    context.user.email_address == true
   end
 
   def email_disabled?
@@ -3536,33 +3666,9 @@ class ConfigureCompany < CMDx::Task
 end
 ```
 
-## ActiveRecord Query Tagging
+## Advance Examples
 
-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
-```
+- [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)
 
 ---