cmdx 0.5.0 → 1.0.1

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.1
 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,20 @@ 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/internationalization.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 +217,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 +245,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 +263,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 +281,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,14 +297,37 @@ 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/ar.yml
+- lib/locales/cs.yml
+- lib/locales/da.yml
+- lib/locales/de.yml
+- lib/locales/el.yml
 - lib/locales/en.yml
 - lib/locales/es.yml
+- lib/locales/fi.yml
+- lib/locales/fr.yml
+- lib/locales/he.yml
+- lib/locales/hi.yml
+- lib/locales/it.yml
+- lib/locales/ja.yml
+- lib/locales/ko.yml
+- lib/locales/nl.yml
+- lib/locales/no.yml
+- lib/locales/pl.yml
+- lib/locales/pt.yml
+- lib/locales/ru.yml
+- lib/locales/sv.yml
+- lib/locales/th.yml
+- lib/locales/tr.yml
+- lib/locales/vi.yml
+- lib/locales/zh.yml
 homepage: https://github.com/drexed/cmdx
 licenses:
 - MIT
@@ -290,7 +352,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

data/lib/cmdx/parameters.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  class Parameters < Array
-
-    def invalid?
-      !valid?
-    end
-
-    def valid?
-      all?(&:valid?)
-    end
-
-    def validate!(task)
-      each { |p| recursive_validate!(task, p) }
-    end
-
-    def to_h
-      ParametersSerializer.call(self)
-    end
-    alias to_a to_h
-
-    def to_s
-      ParametersInspector.call(self)
-    end
-
-    private
-
-    def recursive_validate!(task, parameter)
-      task.send(parameter.method_name)
-      parameter.children.each { |cp| recursive_validate!(task, cp) }
-    end
-
-  end
-end

data/lib/cmdx/run.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  class Run
-
-    __cmdx_attr_delegator :index, to: :results
-    __cmdx_attr_delegator :state, :status, :outcome, :runtime, to: :first_result
-
-    attr_reader :id, :results
-
-    def initialize(attributes = {})
-      @id      = attributes[:id] || SecureRandom.uuid
-      @results = Array(attributes[:results])
-    end
-
-    def freeze
-      first_result
-      super
-    end
-
-    def to_h
-      RunSerializer.call(self)
-    end
-    alias to_a to_h
-
-    def to_s
-      RunInspector.call(self)
-    end
-
-    private
-
-    def first_result
-      return @first_result if defined?(@first_result)
-
-      @first_result = @results.first
-    end
-
-  end
-end

data/lib/cmdx/run_inspector.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module RunInspector
-
-    FOOTER_KEYS = %i[
-      state status outcome runtime
-    ].freeze
-
-    module_function
-
-    def call(run)
-      header = "\nrun: #{run.id}"
-      footer = FOOTER_KEYS.map { |key| "#{key}: #{run.send(key)}" }.join(" | ")
-      spacer = "=" * [header.size, footer.size].max
-
-      run
-        .results
-        .map { |r| r.to_h.except(:run_id).pretty_inspect }
-        .unshift(header, "#{spacer}\n")
-        .push(spacer, "#{footer}\n\n")
-        .join("\n")
-    end
-
-  end
-end

data/lib/cmdx/run_serializer.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module RunSerializer
-
-    module_function
-
-    def call(run)
-      {
-        id: run.id,
-        state: run.state,
-        status: run.status,
-        outcome: run.outcome,
-        runtime: run.runtime,
-        results: run.results.map(&:to_h)
-      }
-    end
-
-  end
-end

data/lib/cmdx/task_hook.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module CMDx
-  module TaskHook
-
-    module_function
-
-    def call(task, hook)
-      Array(task.class.cmd_hooks[hook]).each do |callables, options|
-        next unless task.__cmdx_eval(options)
-
-        hooks = Array(callables)
-        hooks.each { |h| task.__cmdx_try(h) }
-      end
-    end
-
-  end
-end

data/lib/generators/cmdx/batch_generator.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Cmdx
-  class BatchGenerator < Rails::Generators::NamedBase
-
-    source_root File.expand_path("templates", __dir__)
-    check_class_collision prefix: "Batch"
-
-    desc "Generates a batch task with the given NAME (if one does not exist)."
-
-    def copy_files
-      name = file_name.sub(/^batch_?/i, "")
-      path = File.join("app/cmds", class_path, "batch_#{name}.rb")
-      template("batch.rb.tt", path)
-    end
-
-    private
-
-    def class_name
-      @class_name ||= super.delete_prefix("Batch")
-    end
-
-    def parent_class_name
-      ApplicationBatch
-    rescue StandardError
-      CMDx::Batch
-    end
-
-  end
-end