cmdx 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c054b422d416bb8f3605c0c75961c2dc65fc3ba7aba3125fcd66f1107276dc8a
-  data.tar.gz: 05b168249fcf03d62cee5a68a98b30fb038f5da90bea4044809a6e52ee1f2ca2
+  metadata.gz: 8483d78b67a6dfffa6721b39e623ac08d57d443b499287891bfb9c6e06422c89
+  data.tar.gz: 02cb722299d6a97fb4e2d07a84880c7374a8c17b691f42bee995bd4f3ea698ab
 SHA512:
-  metadata.gz: fe3426a7c2d2a8839583695c9682fb3499bc6e2707349a5e872b293a7100442a7f328212783e083c68f3995379fd8db0cf44b56156506b71e14abf59f3c0d3ec
-  data.tar.gz: d29594887e332518500b3af872f987540fc41ff8293a13252bf665b0a2669da38944875b91caab1916d004de6e7b616ef17016de55b667ad80fcff301a153dc7
+  metadata.gz: b6600b6d617c11a3ec3b66367a7fa309e191bd2d1f20a3fb1a538565a0c2b45e05f8093f2c3e07edbb155e308e6c90c486f069db171aac68e8658bbe85bd4b34
+  data.tar.gz: 6ad4a1348066d3aa4d0ed2733fc88f94af293835cc970be5986f3c002cf3b3615f474bff774a2b48f7e043920ca01b5f278cd26850b5b4827a70d2a4b0e6ab50

data/.cursor/rules/cursor-instructions.mdc

@@ -10,8 +10,8 @@ Follow the official Ruby gem guides for best practices.
 Reference the guides outlined in https://guides.rubygems.org
 
 ## Project Context
-CMDx provides a framework for designing and executing complex
-business logic within service/command objects.
+CMDx provides a framework for designing and executing complex business logic within service/command objects.
+Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM.md
 
 ## Technology Stack
 - Ruby 3.4+

data/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [TODO]
 
+## [1.7.0] - 2025-08-25
+
+### Added
+- Workflow generator
+
+### Changes
+- Port over `cmdx-parallel` changes
+- Port over `cmdx-i18n` changes
+
+## [1.6.2] - 2025-08-24
+
+### Changes
+- Prefix railtie I18n with `::` to play nice with `CMDx::I18n`
+- Use `cmdx-rspec` for matchers support
+
 ## [1.6.1] - 2025-08-23
 
 ### Changes
@@ -27,7 +42,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 ## [1.5.1] - 2025-08-21
 
 ### Changes
-- Prefix I18n with `::` to play nice with `CMDx::I18n`
+- Prefix locale I18n with `::` to play nice with `CMDx::I18n`
 - Safe navigate length and numeric validators
 - Update railtie file path points to correct directory
 

data/LLM.md

@@ -72,6 +72,8 @@ end
 
 ### Middlewares
 
+See the [Middelwares](#https://github.com/drexed/cmdx/blob/main/docs/middlewares.md#declarations) docs for task level configurations.
+
 ```ruby
 CMDx.configure do |config|
   # Via callable (must respond to `call(task, options)`)
@@ -99,6 +101,8 @@ end
 
 ### Callbacks
 
+See the [Callbacks](#https://github.com/drexed/cmdx/blob/main/docs/callbacks.md#declarations) docs for task level configurations.
+
 ```ruby
 CMDx.configure do |config|
   # Via method
@@ -123,6 +127,8 @@ end
 
 ### Coercions
 
+See the [Attributes - Coercions](#https://github.com/drexed/cmdx/blob/main/docs/attributes/coercions.md#declarations) docs for task level configurations.
+
 ```ruby
 CMDx.configure do |config|
   # Via callable (must respond to `call(value, options)`)
@@ -147,6 +153,8 @@ end
 
 ### Validators
 
+See the [Attributes - Validations](#https://github.com/drexed/cmdx/blob/main/docs/attributes/validations.md#declarations) docs for task level configurations.
+
 ```ruby
 CMDx.configure do |config|
   # Via callable (must respond to `call(value, options)`)
@@ -907,6 +915,7 @@ fail!("Unsupported")
 # Bad: Default, cannot determine reason
 skip! #=> "no reason given"
 fail! #=> "no reason given"
+```
 
 ---
 
@@ -1727,6 +1736,7 @@ result.metadata #=> {
                 #       port: ["is required"]
                 #     }
                 #   }
+```
 
 ---
 
@@ -1810,6 +1820,8 @@ url: https://github.com/drexed/cmdx/blob/main/docs/attributes/coercions.md
 
 Attribute coercions automatically convert task arguments to expected types, ensuring type safety while providing flexible input handling. Coercions transform raw input values into the specified types, supporting simple conversions like string-to-integer and complex operations like JSON parsing.
 
+Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#coercions) docs for global configuration.
+
 ## Usage
 
 Define attribute types to enable automatic coercion:
@@ -1952,6 +1964,7 @@ result.metadata #=> {
                 #       score: ["could not coerce into one of: float, big_decimal"]
                 #     }
                 #   }
+```
 
 ---
 
@@ -1962,6 +1975,8 @@ url: https://github.com/drexed/cmdx/blob/main/docs/attributes/validations.md
 
 Attribute validations ensure task arguments meet specified requirements before execution begins. Validations run after coercions and provide declarative rules for data integrity, supporting both built-in validators and custom validation logic.
 
+Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#validations) docs for global configuration.
+
 ## Usage
 
 Define validation rules on attributes to enforce data requirements:
@@ -2338,6 +2353,8 @@ url: https://github.com/drexed/cmdx/blob/main/docs/callbacks.md
 
 Callbacks provide precise control over task execution lifecycle, running custom logic at specific transition points. Callback callables have access to the same context and result information as the `execute` method, enabling rich integration patterns.
 
+Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#callbacks) docs for global configuration.
+
 > [!IMPORTANT]
 > Callbacks execute in the order they are declared within each hook type. Multiple callbacks of the same type execute in declaration order (FIFO: first in, first out).
 
@@ -2497,6 +2514,8 @@ url: https://github.com/drexed/cmdx/blob/main/docs/middlewares.md
 
 Middleware provides Rack-style wrappers around task execution for cross-cutting concerns like authentication, logging, caching, and error handling.
 
+Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#middlewares) docs for global configuration.
+
 ## Order
 
 Middleware executes in a nested fashion, creating an onion-like execution pattern:
@@ -2811,8 +2830,109 @@ I18n.with_locale(:fr) do
 end
 ```
 
-> [!TIP]
-> CMDx supports 85+ locales via the [cmdx-i18n](https://github.com/drexed/cmdx-i18n) gem.
+## Configuration
+
+Localization is handled by the `I18n` gem. In Rails applications, locales are loaded automatically and managed via the `I18n.available_locales` setting.
+
+### Local Copies
+
+Execute the following command to copy any locale into the Rails applications `config/locales` directory:
+
+```bash
+rails generate cmdx:locale [LOCALE]
+
+# Eg: generate french locale
+rails generate cmdx:locale fr
+```
+
+### Available Locales
+
+- af - Afrikaans
+- ar - Arabic
+- az - Azerbaijani
+- be - Belarusian
+- bg - Bulgarian
+- bn - Bengali
+- bs - Bosnian
+- ca - Catalan
+- cnr - Montenegrin
+- cs - Czech
+- cy - Welsh
+- da - Danish
+- de - German
+- dz - Dzongkha
+- el - Greek
+- en - English
+- eo - Esperanto
+- es - Spanish
+- et - Estonian
+- eu - Basque
+- fa - Persian
+- fi - Finnish
+- fr - French
+- fy - Western Frisian
+- gd - Scottish Gaelic
+- gl - Galician
+- he - Hebrew
+- hi - Hindi
+- hr - Croatian
+- hu - Hungarian
+- hy - Armenian
+- id - Indonesian
+- is - Icelandic
+- it - Italian
+- ja - Japanese
+- ka - Georgian
+- kk - Kazakh
+- km - Khmer
+- kn - Kannada
+- ko - Korean
+- lb - Luxembourgish
+- lo - Lao
+- lt - Lithuanian
+- lv - Latvian
+- mg - Malagasy
+- mk - Macedonian
+- ml - Malayalam
+- mn - Mongolian
+- mr-IN - Marathi (India)
+- ms - Malay
+- nb - Norwegian Bokmål
+- ne - Nepali
+- nl - Dutch
+- nn - Norwegian Nynorsk
+- oc - Occitan
+- or - Odia
+- pa - Punjabi
+- pl - Polish
+- pt - Portuguese
+- rm - Romansh
+- ro - Romanian
+- ru - Russian
+- sc - Sardinian
+- sk - Slovak
+- sl - Slovenian
+- sq - Albanian
+- sr - Serbian
+- st - Southern Sotho
+- sv - Swedish
+- sw - Swahili
+- ta - Tamil
+- te - Telugu
+- th - Thai
+- tl - Tagalog
+- tr - Turkish
+- tt - Tatar
+- ug - Uyghur
+- uk - Ukrainian
+- ur - Urdu
+- uz - Uzbek
+- vi - Vietnamese
+- wo - Wolof
+- zh-CN - Chinese (Simplified)
+- zh-HK - Chinese (Hong Kong)
+- zh-TW - Chinese (Traditional)
+- zh-YUE - Chinese (Yue)
 
 ---
 
@@ -3147,6 +3267,52 @@ class CompleteEmailWorkflow < CMDx::Task
 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.
+
+> [!IMPORTANT]
+> Context cannot be modified during parallel execution. Ensure that all required data is preloaded into the context before parallelization begins.
+
+```ruby
+class SendWelcomeNotifications < CMDx::Task
+  include CMDx::Workflow
+
+  # Default options (dynamically calculated to available processors)
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel
+
+  # Fix number of threads
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_threads: 2
+
+  # Fix number of forked processes
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_processes: 2
+
+  # NOTE: Reactors are not supported
+end
+```
+
+## Task Generator
+
+Generate new CMDx workflow tasks quickly using the built-in generator:
+
+```bash
+rails generate cmdx:workflow SendNotifications
+```
+
+This creates a new workflow task file with the basic structure:
+
+```ruby
+# app/tasks/send_notifications.rb
+class SendNotifications < CMDx::Task
+  include CMDx::Workflow
+
+  tasks Task1, Task2
+end
+```
+
+> [!TIP]
+> Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`
+
 ---
 
 url: https://github.com/drexed/cmdx/blob/main/docs/tips_and_tricks.md

data/docs/attributes/coercions.md

@@ -2,6 +2,8 @@
 
 Attribute coercions automatically convert task arguments to expected types, ensuring type safety while providing flexible input handling. Coercions transform raw input values into the specified types, supporting simple conversions like string-to-integer and complex operations like JSON parsing.
 
+Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#coercions) docs for global configuration.
+
 ## Table of Contents
 
 - [Usage](#usage)

data/docs/attributes/validations.md

@@ -2,6 +2,8 @@
 
 Attribute validations ensure task arguments meet specified requirements before execution begins. Validations run after coercions and provide declarative rules for data integrity, supporting both built-in validators and custom validation logic.
 
+Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#validations) docs for global configuration.
+
 ## Table of Contents
 
 - [Usage](#usage)

data/docs/callbacks.md

@@ -2,6 +2,8 @@
 
 Callbacks provide precise control over task execution lifecycle, running custom logic at specific transition points. Callback callables have access to the same context and result information as the `execute` method, enabling rich integration patterns.
 
+Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#callbacks) docs for global configuration.
+
 > [!IMPORTANT]
 > Callbacks execute in the order they are declared within each hook type. Multiple callbacks of the same type execute in declaration order (FIFO: first in, first out).
 

data/docs/getting_started.md

@@ -82,6 +82,8 @@ end
 
 ### Middlewares
 
+See the [Middelwares](#https://github.com/drexed/cmdx/blob/main/docs/middlewares.md#declarations) docs for task level configurations.
+
 ```ruby
 CMDx.configure do |config|
   # Via callable (must respond to `call(task, options)`)
@@ -109,6 +111,8 @@ end
 
 ### Callbacks
 
+See the [Callbacks](#https://github.com/drexed/cmdx/blob/main/docs/callbacks.md#declarations) docs for task level configurations.
+
 ```ruby
 CMDx.configure do |config|
   # Via method
@@ -133,6 +137,8 @@ end
 
 ### Coercions
 
+See the [Attributes - Coercions](#https://github.com/drexed/cmdx/blob/main/docs/attributes/coercions.md#declarations) docs for task level configurations.
+
 ```ruby
 CMDx.configure do |config|
   # Via callable (must respond to `call(value, options)`)
@@ -157,6 +163,8 @@ end
 
 ### Validators
 
+See the [Attributes - Validations](#https://github.com/drexed/cmdx/blob/main/docs/attributes/validations.md#declarations) docs for task level configurations.
+
 ```ruby
 CMDx.configure do |config|
   # Via callable (must respond to `call(value, options)`)

data/docs/internationalization.md

@@ -5,6 +5,9 @@ CMDx provides comprehensive internationalization support for all error messages,
 ## Table of Contents
 
 - [Localization](#localization)
+- [Configuration](#configuration)
+  - [Local Copies](#local-copies)
+  - [Available Locales](#available-locales)
 
 ## Localization
 
@@ -25,8 +28,109 @@ I18n.with_locale(:fr) do
 end
 ```
 
-> [!TIP]
-> CMDx supports 85+ locales via the [cmdx-i18n](https://github.com/drexed/cmdx-i18n) gem.
+## Configuration
+
+Localization is handled by the `I18n` gem. In Rails applications, locales are loaded automatically and managed via the `I18n.available_locales` setting.
+
+### Local Copies
+
+Execute the following command to copy any locale into the Rails applications `config/locales` directory:
+
+```bash
+rails generate cmdx:locale [LOCALE]
+
+# Eg: generate french locale
+rails generate cmdx:locale fr
+```
+
+### Available Locales
+
+- af - Afrikaans
+- ar - Arabic
+- az - Azerbaijani
+- be - Belarusian
+- bg - Bulgarian
+- bn - Bengali
+- bs - Bosnian
+- ca - Catalan
+- cnr - Montenegrin
+- cs - Czech
+- cy - Welsh
+- da - Danish
+- de - German
+- dz - Dzongkha
+- el - Greek
+- en - English
+- eo - Esperanto
+- es - Spanish
+- et - Estonian
+- eu - Basque
+- fa - Persian
+- fi - Finnish
+- fr - French
+- fy - Western Frisian
+- gd - Scottish Gaelic
+- gl - Galician
+- he - Hebrew
+- hi - Hindi
+- hr - Croatian
+- hu - Hungarian
+- hy - Armenian
+- id - Indonesian
+- is - Icelandic
+- it - Italian
+- ja - Japanese
+- ka - Georgian
+- kk - Kazakh
+- km - Khmer
+- kn - Kannada
+- ko - Korean
+- lb - Luxembourgish
+- lo - Lao
+- lt - Lithuanian
+- lv - Latvian
+- mg - Malagasy
+- mk - Macedonian
+- ml - Malayalam
+- mn - Mongolian
+- mr-IN - Marathi (India)
+- ms - Malay
+- nb - Norwegian Bokmål
+- ne - Nepali
+- nl - Dutch
+- nn - Norwegian Nynorsk
+- oc - Occitan
+- or - Odia
+- pa - Punjabi
+- pl - Polish
+- pt - Portuguese
+- rm - Romansh
+- ro - Romanian
+- ru - Russian
+- sc - Sardinian
+- sk - Slovak
+- sl - Slovenian
+- sq - Albanian
+- sr - Serbian
+- st - Southern Sotho
+- sv - Swedish
+- sw - Swahili
+- ta - Tamil
+- te - Telugu
+- th - Thai
+- tl - Tagalog
+- tr - Turkish
+- tt - Tatar
+- ug - Uyghur
+- uk - Ukrainian
+- ur - Urdu
+- uz - Uzbek
+- vi - Vietnamese
+- wo - Wolof
+- zh-CN - Chinese (Simplified)
+- zh-HK - Chinese (Hong Kong)
+- zh-TW - Chinese (Traditional)
+- zh-YUE - Chinese (Yue)
 
 ---
 

data/docs/middlewares.md

@@ -2,6 +2,8 @@
 
 Middleware provides Rack-style wrappers around task execution for cross-cutting concerns like authentication, logging, caching, and error handling.
 
+Check out the [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#middlewares) docs for global configuration.
+
 ## Table of Contents
 
 - [Order](#order)

data/docs/workflows.md

@@ -12,6 +12,8 @@ Workflow orchestrates sequential execution of multiple tasks in a linear pipelin
   - [Task Configuration](#task-configuration)
   - [Group Configuration](#group-configuration)
 - [Nested Workflows](#nested-workflows)
+- [Parallel Execution](#parallel-execution)
+- [Task Generator](#task-generator)
 
 ## Declarations
 
@@ -187,6 +189,52 @@ class CompleteEmailWorkflow < CMDx::Task
 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.
+
+> [!IMPORTANT]
+> Context cannot be modified during parallel execution. Ensure that all required data is preloaded into the context before parallelization begins.
+
+```ruby
+class SendWelcomeNotifications < CMDx::Task
+  include CMDx::Workflow
+
+  # Default options (dynamically calculated to available processors)
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel
+
+  # Fix number of threads
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_threads: 2
+
+  # Fix number of forked processes
+  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_processes: 2
+
+  # NOTE: Reactors are not supported
+end
+```
+
+## Task Generator
+
+Generate new CMDx workflow tasks quickly using the built-in generator:
+
+```bash
+rails generate cmdx:workflow SendNotifications
+```
+
+This creates a new workflow task file with the basic structure:
+
+```ruby
+# app/tasks/send_notifications.rb
+class SendNotifications < CMDx::Task
+  include CMDx::Workflow
+
+  tasks Task1, Task2
+end
+```
+
+> [!TIP]
+> Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`
+
 ---
 
 - **Prev:** [Deprecation](deprecation.md)

data/lib/cmdx/pipeline.rb

@@ -55,23 +55,22 @@ module CMDx
 
     private
 
-    # Executes tasks within a group using the configured execution strategy.
-    # Override this method to implement custom execution strategies like parallel
-    # processing or conditional task execution.
+    # Executes a group of tasks using the specified execution strategy.
     #
-    # @param group [ExecutionGroup] The group of tasks to execute
-    # @param breakpoints [Array<String>] Breakpoint statuses that trigger workflow interruption
+    # @param group [CMDx::Group] The task group to execute
+    # @param breakpoints [Array<Symbol>] Status values that trigger execution breaks
+    # @option group.options [Symbol, String] :strategy Execution strategy (:sequential, :parallel, or nil for default)
     #
     # @return [void]
     #
     # @example
-    #   def execute_group_tasks(group, breakpoints)
-    #     # Custom parallel execution strategy
-    #     group.tasks.map { |task| Thread.new { task.execute(workflow.context) } }
-    #   end
+    #   execute_group_tasks(group, ["failed", "skipped"])
     def execute_group_tasks(group, breakpoints)
-      # NOTE: Override this method to introduce alternative execution strategies
-      execute_tasks_in_sequence(group, breakpoints)
+      case strategy = group.options[:strategy]
+      when NilClass, /sequential/ then execute_tasks_in_sequence(group, breakpoints)
+      when /parallel/ then execute_tasks_in_parallel(group, breakpoints)
+      else raise "unknown execution strategy #{strategy.inspect}"
+      end
     end
 
     # Executes tasks sequentially within a group, checking breakpoints after each task.
@@ -95,5 +94,38 @@ module CMDx
       end
     end
 
+    # Executes tasks in parallel using the parallel gem.
+    #
+    # @param group [CMDx::Group] The task group to execute in parallel
+    # @param breakpoints [Array<Symbol>] Status values that trigger execution breaks
+    # @option group.options [Integer] :in_threads Number of threads to use
+    # @option group.options [Integer] :in_processes Number of processes to use
+    #
+    # @return [void]
+    #
+    # @raise [HaltError] When a task result status matches a breakpoint
+    #
+    # @example
+    #   execute_tasks_in_parallel(group, ["failed"])
+    def execute_tasks_in_parallel(group, breakpoints)
+      raise "install the `parallel` gem to use this feature" unless defined?(::Parallel)
+
+      parallel_options = group.options.slice(:in_threads, :in_processes)
+      throwable_result = nil
+
+      ::Parallel.each(group.tasks, **parallel_options) do |task|
+        Chain.current = workflow.chain
+
+        task_result = task.execute(workflow.context)
+        next unless breakpoints.include?(task_result.status)
+
+        raise ::Parallel::Break, throwable_result = task_result
+      end
+
+      return if throwable_result.nil?
+
+      workflow.throw!(throwable_result)
+    end
+
   end
 end

data/lib/cmdx/railtie.rb

@@ -26,10 +26,10 @@ module CMDx
         path = CMDx.gem_path.join("lib/locales/#{locale}.yml")
         next unless File.file?(path)
 
-        I18n.load_path << path
+        ::I18n.load_path << path
       end
 
-      I18n.reload!
+      ::I18n.reload!
     end
 
   end

data/lib/cmdx/version.rb

@@ -2,6 +2,6 @@
 
 module CMDx
 
-  VERSION = "1.6.1"
+  VERSION = "1.7.0"
 
 end

data/lib/cmdx.rb

@@ -48,7 +48,9 @@ require_relative "cmdx/faults"
 # Conditionally load Rails components if Rails is available
 if defined?(Rails::Generators)
   require_relative "generators/cmdx/install_generator"
+  require_relative "generators/cmdx/locale_generator"
   require_relative "generators/cmdx/task_generator"
+  require_relative "generators/cmdx/workflow_generator"
 end
 
 # Load the Railtie last after everything else is required so we don't