cmdx 0.5.0 → 1.0.0

data/lib/generators/cmdx/task_generator.rb

@@ -1,13 +1,54 @@
 # frozen_string_literal: true
 
 module Cmdx
+  ##
+  # Rails generator for creating CMDx task classes.
+  #
+  # This generator creates individual task files that encapsulate specific
+  # business logic operations. Tasks inherit from CMDx::Task and provide
+  # parameter validation, callbacks, result tracking, and error handling
+  # capabilities for focused business operations.
+  #
+  # The generator handles name normalization, ensuring "Task" suffix
+  # and proper file naming conventions. Generated tasks inherit from
+  # ApplicationTask when available, falling back to CMDx::Task.
+  #
+  # @example Generate a task
+  #   rails generate cmdx:task SendEmail
+  #   rails generate cmdx:task ProcessPayment
+  #   rails generate cmdx:task ProcessPaymentTask  # "Task" suffix preserved
+  #
+  # @example Generated file location
+  #   app/cmds/send_email_task.rb
+  #   app/cmds/process_payment_task.rb
+  #
+  # @since 1.0.0
   class TaskGenerator < Rails::Generators::NamedBase
 
     source_root File.expand_path("templates", __dir__)
     check_class_collision suffix: "Task"
 
-    desc "Generates a task with the given NAME (if one does not exist)."
+    desc "Creates a task with the given NAME"
 
+    ##
+    # Copies the task template to the application commands directory.
+    #
+    # Creates a new task file in `app/cmds/` with the normalized name.
+    # The generator automatically handles:
+    # - Removing "Task" suffix from file naming
+    # - Converting to snake_case for file naming
+    # - Adding "_task" suffix to the filename
+    # - Setting up proper class inheritance
+    #
+    # @return [void]
+    # @raise [Thor::Error] if the destination file cannot be created
+    #
+    # @example Generated task structure
+    #   class SendEmailTask < ApplicationTask
+    #     def call
+    #       # Task business logic
+    #     end
+    #   end
     def copy_files
       name = file_name.sub(/_?task$/i, "")
       path = File.join("app/cmds", class_path, "#{name}_task.rb")
@@ -16,10 +57,37 @@ module Cmdx
 
     private
 
+    ##
+    # Normalizes the class name by ensuring "Task" suffix.
+    #
+    # Ensures consistent class naming by adding "Task" suffix if not
+    # already present, allowing users to specify either "SendEmail"
+    # or "SendEmailTask".
+    #
+    # @return [String] the normalized class name with "Task" suffix
+    #
+    # @example Class name normalization
+    #   # Input: "SendEmail"
+    #   # Output: "SendEmailTask"
+    #
+    #   # Input: "SendEmailTask"
+    #   # Output: "SendEmailTask"
     def class_name
       @class_name ||= super.end_with?("Task") ? super : "#{super}Task"
     end
 
+    ##
+    # Determines the parent class for the generated task.
+    #
+    # Attempts to use ApplicationTask as the parent class if available,
+    # falling back to CMDx::Task if ApplicationTask is not defined.
+    # This allows applications to define custom base task behavior.
+    #
+    # @return [String] the parent class name to inherit from
+    #
+    # @example Parent class resolution
+    #   # If ApplicationTask exists: "ApplicationTask"
+    #   # If ApplicationTask missing: "CMDx::Task"
     def parent_class_name
       ApplicationTask
     rescue StandardError

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

@@ -1,23 +1,19 @@
 # frozen_string_literal: true
 
 CMDx.configure do |config|
-  # Define which statuses a bang `call!` will halt and raise a fault.
-  # This option can accept an array of statuses.
+  # Halt execution and raise fault on these result statuses when using `call!`
   config.task_halt = CMDx::Result::FAILED
 
-  # Enable task timeouts to prevent call execution beyond a defined threshold.
-  config.task_timeout = nil
+  # Global timeout for individual tasks (nil = no timeout)
 
-  # Define which statuses a batch task will halt execution from proceeding to the next step.
-  # By default skipped tasks are treated as a NOOP so processing is continued.
-  # This option can accept an array of statuses.
-  config.batch_halt = CMDx::Result::FAILED
+  # Stop workflow execution when tasks return these statuses
+  # Note: Skipped tasks continue processing by default
+  config.workflow_halt = CMDx::Result::FAILED
 
-  # Enable batch timeouts to prevent call execution beyond a defined threshold.
-  # TIP: remember to account for all defined tasks when setting this value
-  config.batch_timeout = nil
+  # Global timeout for entire workflow execution (nil = no timeout)
+  # Tip: Account for all tasks when setting this value
 
-  # A list of available log formatter can be found at:
+  # Logger with formatter - see available formatters at:
   # https://github.com/drexed/cmdx/tree/main/lib/cmdx/log_formatters
   config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
 end

data/lib/generators/cmdx/workflow_generator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Cmdx
+  ##
+  # Rails generator for creating CMDx workflow task classes.
+  #
+  # This generator creates workflow task files that coordinate multiple
+  # individual tasks in a structured workflow. Workflow tasks inherit
+  # from CMDx::Workflow and provide orchestration capabilities for
+  # complex business processes.
+  #
+  # The generator handles name normalization, ensuring proper file naming
+  # conventions and class names. Generated workflow tasks inherit from
+  # ApplicationWorkflow when available, falling back to CMDx::Workflow.
+  #
+  # @example Generate a workflow task
+  #   rails generate cmdx:workflow OrderProcessing
+  #   rails generate cmdx:workflow PaymentWorkflow  # "Workflow" suffix preserved
+  #
+  # @example Generated file location
+  #   app/cmds/order_processing_workflow.rb
+  #   app/cmds/payment_workflow.rb
+  #
+  # @example Generated class structure
+  #   class OrderProcessingWorkflow < ApplicationWorkflow
+  #     def call
+  #       # Workflow orchestration logic
+  #     end
+  #   end
+  #
+  # @see CMDx::Workflow Base workflow class
+  # @see Rails::Generators::NamedBase Rails generator base class
+  # @since 1.0.0
+  class WorkflowGenerator < Rails::Generators::NamedBase
+
+    source_root File.expand_path("templates", __dir__)
+    check_class_collision suffix: "Workflow"
+
+    desc "Creates a workflow with the given NAME"
+
+    ##
+    # Copies the workflow task template to the application commands directory.
+    #
+    # Creates a new workflow task file in `app/cmds/` with the normalized
+    # name. The generator automatically handles:
+    # - Removing "workflow" suffix from the provided name for filename
+    # - Converting to snake_case for file naming
+    # - Adding "_workflow" suffix to the filename
+    # - Setting up proper class inheritance
+    # - Ensuring class names end with "Workflow"
+    #
+    # @return [void]
+    # @raise [Thor::Error] if the destination file cannot be created
+    #
+    # @example File generation
+    #   # Input: rails generate cmdx:workflow OrderProcessing
+    #   # Creates: app/cmds/order_processing_workflow.rb
+    #   # Class: OrderProcessingWorkflow
+    #
+    #   # Input: rails generate cmdx:workflow PaymentWorkflow
+    #   # Creates: app/cmds/payment_workflow.rb
+    #   # Class: PaymentWorkflow
+    def copy_files
+      name = file_name.sub(/_?workflow$/i, "")
+      path = File.join("app/cmds", class_path, "#{name}_workflow.rb")
+      template("workflow.rb.tt", path)
+    end
+
+    private
+
+    ##
+    # Normalizes the class name by ensuring it ends with "Workflow".
+    #
+    # Ensures consistent class naming by appending "Workflow" suffix
+    # to the provided generator name if it doesn't already end with it,
+    # allowing users to specify either "OrderProcessing" or "OrderProcessingWorkflow".
+    #
+    # @return [String] the normalized class name with "Workflow" suffix
+    #
+    # @example Class name normalization
+    #   # Input: "OrderProcessing"
+    #   # Output: "OrderProcessingWorkflow"
+    #
+    #   # Input: "PaymentWorkflow"
+    #   # Output: "PaymentWorkflow"
+    def class_name
+      @class_name ||= super.end_with?("Workflow") ? super : "#{super}Workflow"
+    end
+
+    ##
+    # Determines the parent class for the generated workflow task.
+    #
+    # Attempts to use ApplicationWorkflow as the parent class if available,
+    # falling back to CMDx::Workflow if ApplicationWorkflow is not defined.
+    # This allows applications to define custom base workflow behavior.
+    #
+    # @return [String] the parent class name to inherit from
+    #
+    # @example Parent class resolution
+    #   # If ApplicationWorkflow exists: "ApplicationWorkflow"
+    #   # If ApplicationWorkflow missing: "CMDx::Workflow"
+    def parent_class_name
+      ApplicationWorkflow
+    rescue StandardError
+      CMDx::Workflow
+    end
+
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Juan Gomez
 bindir: exe
 cert_chain: []
-date: 2025-03-21 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -158,6 +186,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".DS_Store"
+- ".cursor/rules/cursor-instructions.mdc"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
@@ -166,19 +195,19 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/ai_prompts.md
 - docs/basics/call.md
+- docs/basics/chain.md
 - docs/basics/context.md
-- docs/basics/run.md
 - docs/basics/setup.md
-- docs/batch.md
+- docs/callbacks.md
 - docs/configuration.md
-- docs/example.md
 - docs/getting_started.md
-- docs/hooks.md
 - docs/interruptions/exceptions.md
 - docs/interruptions/faults.md
 - docs/interruptions/halt.md
 - docs/logging.md
+- docs/middlewares.md
 - docs/outcomes/result.md
 - docs/outcomes/states.md
 - docs/outcomes/statuses.md
@@ -187,10 +216,16 @@ files:
 - docs/parameters/definitions.md
 - docs/parameters/namespacing.md
 - docs/parameters/validations.md
+- docs/testing.md
 - docs/tips_and_tricks.md
+- docs/workflows.md
 - lib/cmdx.rb
 - lib/cmdx/.DS_Store
-- lib/cmdx/batch.rb
+- lib/cmdx/callback.rb
+- lib/cmdx/callback_registry.rb
+- lib/cmdx/chain.rb
+- lib/cmdx/chain_inspector.rb
+- lib/cmdx/chain_serializer.rb
 - lib/cmdx/coercions/array.rb
 - lib/cmdx/coercions/big_decimal.rb
 - lib/cmdx/coercions/boolean.rb
@@ -209,6 +244,7 @@ files:
 - lib/cmdx/core_ext/hash.rb
 - lib/cmdx/core_ext/module.rb
 - lib/cmdx/core_ext/object.rb
+- lib/cmdx/correlator.rb
 - lib/cmdx/error.rb
 - lib/cmdx/errors.rb
 - lib/cmdx/fault.rb
@@ -226,12 +262,16 @@ files:
 - lib/cmdx/logger.rb
 - lib/cmdx/logger_ansi.rb
 - lib/cmdx/logger_serializer.rb
+- lib/cmdx/middleware.rb
+- lib/cmdx/middleware_registry.rb
+- lib/cmdx/middlewares/correlate.rb
+- lib/cmdx/middlewares/timeout.rb
 - lib/cmdx/parameter.rb
 - lib/cmdx/parameter_inspector.rb
+- lib/cmdx/parameter_registry.rb
 - lib/cmdx/parameter_serializer.rb
 - lib/cmdx/parameter_validator.rb
 - lib/cmdx/parameter_value.rb
-- lib/cmdx/parameters.rb
 - lib/cmdx/parameters_inspector.rb
 - lib/cmdx/parameters_serializer.rb
 - lib/cmdx/railtie.rb
@@ -240,11 +280,9 @@ files:
 - lib/cmdx/result_inspector.rb
 - lib/cmdx/result_logger.rb
 - lib/cmdx/result_serializer.rb
-- lib/cmdx/run.rb
-- lib/cmdx/run_inspector.rb
-- lib/cmdx/run_serializer.rb
+- lib/cmdx/rspec/result_matchers.rb
+- lib/cmdx/rspec/task_matchers.rb
 - lib/cmdx/task.rb
-- lib/cmdx/task_hook.rb
 - lib/cmdx/task_serializer.rb
 - lib/cmdx/utils/ansi_color.rb
 - lib/cmdx/utils/log_timestamp.rb
@@ -258,12 +296,13 @@ files:
 - lib/cmdx/validators/numeric.rb
 - lib/cmdx/validators/presence.rb
 - lib/cmdx/version.rb
-- lib/generators/cmdx/batch_generator.rb
+- lib/cmdx/workflow.rb
 - lib/generators/cmdx/install_generator.rb
 - lib/generators/cmdx/task_generator.rb
-- lib/generators/cmdx/templates/batch.rb.tt
 - lib/generators/cmdx/templates/install.rb
 - lib/generators/cmdx/templates/task.rb.tt
+- lib/generators/cmdx/templates/workflow.rb.tt
+- lib/generators/cmdx/workflow_generator.rb
 - lib/locales/en.yml
 - lib/locales/es.yml
 homepage: https://github.com/drexed/cmdx
@@ -290,7 +329,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Command (aka service) objects with intent
 test_files: []

data/docs/basics/run.md

@@ -1,34 +0,0 @@
-# Basics - Run
-
-A run represents a group of tasks executed as part of collection.
-
-When building complex tasks, it's best to pass the parents context to subtasks
-(unless necessary or preventative) so that it gains automated indexing and the
-parents `run_id`. This makes it easy to identify all tasks involved in one
-execution from logging and stdout console calls.
-
-```ruby
-class ProcessOrderTask < CMDx::Task
-
-  def call
-    # Subtasks inherit the ProcessOrderTask run_id:
-    SendEmailConfirmationTask.call(context)
-    NotifyPartnerWarehousesTask.call(context)
-  end
-
-end
-
-result = ProcessOrderTask.call
-puts result.run.to_s
-
-#   Task name                     Index   Run ID      Task ID   etc
-# -----------------------------------------------------------------
-#=> ProcessOrderTask              0       foobar123   abc123    ...
-#=> SendEmailConfirmationTask     1       foobar123   def456    ...
-#=> NotifyPartnerWarehousesTask   2       foobar123   ghi789    ...
-```
-
----
-
-- **Prev:** [Basics - Context](https://github.com/drexed/cmdx/blob/main/docs/basics/context.md)
-- **Next:** [Interruptions - Halt](https://github.com/drexed/cmdx/blob/main/docs/interruptions/halt.md)

data/docs/batch.md

@@ -1,53 +0,0 @@
-# Batch
-
-A CMDx::Batch is a task that calls other tasks in a linear fashion. The
-context is passed down to each task, building on it knowledge with
-each step. This is useful for composing multiple steps into one call.
-
-> [!WARNING]
-> Do **NOT** define a call method in this class. The batch class automatically
-> defines the call logic.
-
-```ruby
-class BatchProcessCheckout < CMDx::Batch
-
-  # Task level settings:
-  task_settings!(batch_halt: CMDx::Result::FAILED)
-
-  # Single declaration:
-  process FinalizeInvoiceTask
-
-  # Multiple declarations:
-  process SendConfirmationEmailTask, SendConfirmationTextTask
-
-  # With options (applies to all declared in that group):
-  process BatchNotifyPartnerWarehouses, batch_halt: [CMDx::Result::SKIPPED, CMDx::Result::FAILED]
-  process BatchNotifyUsaWarehouses, unless: proc { context.invoice.fulfilled_in_house? }
-
-end
-```
-
-> [!IMPORTANT]
-> Process steps are executed in the order they are declared (FIFO: first in, first out).
-
-The `process` method support the following options:
-
-| Option        | Description |
-| ------------- | ----------- |
-| `:if`         | Specifies a callable method, proc or string to determine if processing steps should occur. |
-| `:unless`     | Specifies a callable method, proc, or string to determine if processing steps should not occur. |
-| `:batch_halt` | Sets which result statuses processing of further steps should be prevented. (default: `CMDx::Result::FAILED`) |
-
-> [!NOTE]
-> Batches stop execution on `failed` by default. This is due to the concept
-> of `skipped` being a bypass mechanism, rather than a choke point in execution.
-
-## Generator
-
-Run `rails g cmdx:batch [NAME]` to create a batch task template file under `app/cmds`.
-Tasks will inherit from `ApplicationBatch` if available or fall back to `CMDx::Batch`.
-
----
-
-- **Prev:** [Hooks](https://github.com/drexed/cmdx/blob/main/docs/hooks.md)
-- **Next:** [Logging](https://github.com/drexed/cmdx/blob/main/docs/logging.md)

data/docs/example.md

@@ -1,82 +0,0 @@
-# Example
-
-The following is a full example of task that is commonly implemented.
-
-## Setup
-
-```ruby
-class ProcessOrderTask < CMDx::Task
-
-  required :order
-  required :billing_details, :shipping_details, from: :order
-
-  optional :package do
-    required :delivery_company, default: -> { Current.account.premium? ? "UPS" : "DHL" }
-    optional :weight, :volume, type: :float
-  end
-
-  after_execution :track_metrics
-
-  def call
-    if cart_abandoned?
-      skip!(reason: "Cart was abandoned due to 30 days of inactivity")
-    elsif cart_items_out_of_stock?
-      fail!(reason: "Items in the cart are out of stock", item: [123, 987])
-    else
-      charge_payment_method
-      ship_order_packages
-      send_confirmation_email
-    end
-  end
-
-  private
-
-  def charge_payment_method
-    @charge_payment_method ||= ChargePaymentMethodTask.call(details: billing_details)
-  end
-
-  def ship_order_packages
-    @ship_order_packages ||= ShipOrderPackagesTask.call(details: shipping_details)
-  end
-
-  def send_confirmation_email
-    return if charge_payment_method.failed? || ship_order_packages.bad?
-
-    BatchSendConfirmationNotifications.call(context)
-  end
-
-  def track_metrics
-    if Rails.env.development?
-      logger.debug { "Sending metrics to collector" }
-    else
-      TrackMetricsTask.call(metric: :process_order, status: order.status)
-    end
-  end
-
-end
-```
-
-## Execution
-
-```ruby
-class OrdersController < ApplicationController
-
-  def create
-    task = ProcessOrderTask.call(order_params)
-
-    if task.success?
-      flash[:success] = "Order is on its way!"
-      redirect_to(my_orders_path)
-    else
-      flash[:error] = "Whoops something is wrong: #{task.metadata[:reason]}"
-      render(:new)
-    end
-  end
-
-end
-```
-
----
-
-- **Prev:** [Tips & Tricks](https://github.com/drexed/cmdx/blob/main/docs/tips_and_tricks.md)
-- **Next:** [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md)

data/docs/hooks.md

@@ -1,62 +0,0 @@
-# Hooks
-
-Hooks (callbacks) run logic at task transition points. Callable hooks have access
-to all the same information as the `call` method.
-
-> [!TIP]
-> Hooks are inheritable which is handy for setting up global logic execution,
-> eg: setting tracking markers, account plan checks, etc.
-
-```ruby
-class ProcessOrderTask < CMDx::Task
-
-  # Symbol or string declaration:
-  after_validation :verify_message_starting_chars
-
-  # Proc or lambda declaration:
-  on_complete -> { send_telemetry_data }
-
-  # Multiple declarations:
-  on_success :increment_success_task_counter, :scrub_secret_message_data
-
-  # With options (applies to all declared in that group):
-  on_failure :increment_failure_task_counter, if: :worth_keep_track?
-
-  def call
-    # Do work...
-  end
-
-end
-```
-
-The hook methods support the following options:
-
-| Option        | Description |
-| ------------- | ----------- |
-| `:if`         | Specifies a callable method, proc or string to determine if hook processing should occur. |
-| `:unless`     | Specifies a callable method, proc, or string to determine if hook processing should not occur. |
-
-## Order
-
-Hook types are executed in the following order:
-
-```ruby
-0. before_execution
-1. on_executing
-2. before_validation
-3. after_validation
-4. on_[complete, interrupted]
-5. on_executed
-6. on_[success, skipped, failed]
-7. on_good
-8. on_bad
-9. after_execution
-```
-
-> [!IMPORTANT]
-> Callable hooks are executed in the order they are declared (FIFO: first in, first out).
-
----
-
-- **Prev:** [Outcomes - States](https://github.com/drexed/cmdx/blob/main/docs/outcomes/states.md)
-- **Next:** [Batch](https://github.com/drexed/cmdx/blob/main/docs/batch.md)

data/lib/cmdx/batch.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  class Batch < Task
-
-    Group = Struct.new(:tasks, :options)
-
-    class << self
-
-      def batch_groups
-        @batch_groups ||= []
-      end
-
-      def process(*tasks, **options)
-        batch_groups << Group.new(
-          tasks.flatten.map do |task|
-            next task if task <= Task
-
-            raise ArgumentError, "must be a Batch or Task"
-          end,
-          options
-        )
-      end
-
-    end
-
-    def call
-      self.class.batch_groups.each do |group|
-        next unless __cmdx_eval(group.options)
-
-        batch_halt = group.options[:batch_halt] || task_setting(:batch_halt)
-
-        group.tasks.each do |task|
-          task_result = task.call(context)
-          next unless Array(batch_halt).include?(task_result.status)
-
-          throw!(task_result)
-        end
-      end
-    end
-
-  end
-end