cmdx 0.5.0 → 1.0.1

data/docs/tips_and_tricks.md

@@ -1,79 +1,140 @@
 # Tips & Tricks
 
-## Configuration
+This guide covers advanced patterns and optimization techniques for getting the most out of CMDx in production applications.
 
-Configure `CMDx` to get the most out of your Rails application.
+## Table of Contents
 
-```ruby
-CMDx.configure do |config|
-  # Redirect your logs through the app defined logger:
-  config.logger = Rails.logger
+- [TLDR](#tldr)
+- [Project Organization](#project-organization)
+  - [Directory Structure](#directory-structure)
+  - [Naming Conventions](#naming-conventions)
+- [Parameter Optimization](#parameter-optimization)
+  - [Efficient Parameter Definitions](#efficient-parameter-definitions)
+- [Monitoring and Observability](#monitoring-and-observability)
+  - [ActiveRecord Query Tagging](#activerecord-query-tagging)
 
-  # Adjust the log level to write depending on the environment:
-  config.logger.level = Rails.env.development? ? Logger::DEBUG : Logger::INFO
+## TLDR
 
-  # Structure log lines using a pre-built or custom formatter:
-  config.logger.formatter = CMDx::LogFormatters::Logstash.new
-end
-```
+- **Organization** - Group commands by domain in `/app/commands` with descriptive subdirectories
+- **Naming** - Tasks use "Verb + Noun + Task", workflows use "Noun + Verb + Workflow"
+- **Parameter optimization** - Use `with_options` to reduce duplication in parameter definitions
+- **Monitoring** - Enable ActiveRecord query tagging for better debugging and observability
+- **Base classes** - Create `ApplicationTask` and `ApplicationWorkflow` for shared configuration
 
-## Setup
+## Project Organization
 
-While not required, a common setup involves creating an `app/cmds` directory
-to place all of your tasks and batches under, eg:
+### Directory Structure
+
+Create a well-organized command structure for maintainable applications:
 
 ```txt
 /app
-  /cmds
+  /commands
+    /orders
+      - process_order_task.rb
+      - validate_order_task.rb
+      - fulfill_order_task.rb
+      - order_processing_workflow.rb
     /notifications
-      - deliver_email_task.rb
+      - send_email_task.rb
+      - send_sms_task.rb
       - post_slack_message_task.rb
-      - send_carrier_pigeon_task.rb
-      - batch_deliver_all.rb
-    - process_order_task.rb
-    - application_batch.rb
+      - notification_delivery_workflow.rb
+    /payments
+      - charge_payment_task.rb
+      - refund_payment_task.rb
+      - validate_payment_method_task.rb
     - application_task.rb
+    - application_workflow.rb
 ```
 
-> [!TIP]
-> Prefix batches with `batch_` and suffix tasks with `_task` to they convey their function.
-> Use a verb+noun naming structure to convey the work that will be performed, eg:
-> `BatchDeliverNotifications` or `DeliverEmailTask`
-
-## Parameters
+### Naming Conventions
 
-Use the Rails `with_options` as an elegant way to factor duplication
-out of options passed to a series of parameter definitions. The following
-are a few common example:
+Follow consistent naming patterns for clarity and maintainability:
 
 ```ruby
-class UpdateUserDetailsTask < CMDx::Task
+# Tasks: Verb + Noun + Task
+class ProcessOrderTask < CMDx::Task; end
+class SendEmailTask < CMDx::Task; end
+class ValidatePaymentTask < CMDx::Task; end
+
+# Workflows: Noun + Verb + Workflow
+class OrderProcessingWorkflow < CMDx::Workflow; end
+class NotificationDeliveryWorkflow < CMDx::Workflow; end
+
+# Use present tense verbs for actions
+class CreateUserTask < CMDx::Task; end      # ✓ Good
+class CreatingUserTask < CMDx::Task; end    # ❌ Avoid
+class UserCreationTask < CMDx::Task; end    # ❌ Avoid
+```
 
-  # Apply `type: :string, presence: true` to this set of parameters:
+## Parameter Optimization
+
+### Efficient Parameter Definitions
+
+Use Rails `with_options` to reduce duplication and improve readability:
+
+```ruby
+class UpdateUserProfileTask < CMDx::Task
+  # Apply common options to multiple parameters
   with_options(type: :string, presence: true) do
-    required :email, format: { with: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i }
+    required :email, format: { with: URI::MailTo::EMAIL_REGEXP }
     optional :first_name, :last_name
+    optional :phone, format: { with: /\A\+?[\d\s\-\(\)]+\z/ }
   end
 
+  # Nested parameters with shared prefix
   required :address do
-    # Apply the `address_*` prefix to this set of nested parameters:
     with_options(prefix: :address_) do
-      required :city, :country
-      optional :state
+      required :street, :city, :postal_code, type: :string
+      required :country, type: :string, inclusion: { in: VALID_COUNTRIES }
+      optional :state, type: :string
     end
   end
 
-  def call
-    # Do work
+  # Shared validation rules
+  with_options(type: :integer, numericality: { greater_than: 0 }) do
+    optional :age, numericality: { less_than: 150 }
+    optional :years_experience, numericality: { less_than: 80 }
   end
 
+  def call
+    # Implementation
+  end
 end
 ```
 
-[Learn More](https://api.rubyonrails.org/classes/Object.html#method-i-with_options)
-about its usages on the official Rails docs.
+## Monitoring and Observability
+
+### 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
+
+# app/commands/application_task.rb
+class ApplicationTask < CMDx::Task
+  before_execution :set_execution_context
+
+  private
+
+  def set_execution_context
+    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:ProcessOrderTask,cmdx_chain_id:018c2b95-b764-7615*/ SELECT * FROM orders WHERE id = 1
+```
 
 ---
 
-- **Prev:** [Logging](https://github.com/drexed/cmdx/blob/main/docs/logging.md)
-- **Next:** [Example](https://github.com/drexed/cmdx/blob/main/docs/example.md)
+- **Prev:** [AI Prompts](ai_prompts.md)
+- **Next:** [Getting Started](getting_started.md)

data/docs/workflows.md

@@ -0,0 +1,329 @@
+# Workflow
+
+A CMDx::Workflow orchestrates sequential execution of multiple tasks in a linear pipeline. Workflows provide a declarative DSL for composing complex business workflows from individual task components, with support for conditional execution, context propagation, and configurable halt behavior.
+
+Workflows inherit from Task, gaining all task capabilities including callbacks, parameter validation, result tracking, and configuration. The key difference is that workflows coordinate other tasks rather than implementing business logic directly.
+
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Basic Usage](#basic-usage)
+- [Task Declaration](#task-declaration)
+- [Context Propagation](#context-propagation)
+- [Conditional Execution](#conditional-execution)
+- [Halt Behavior](#halt-behavior)
+  - [Default Behavior](#default-behavior)
+  - [Class-Level Configuration](#class-level-configuration)
+  - [Group-Level Configuration](#group-level-configuration)
+  - [Available Result Statuses](#available-result-statuses)
+- [Process Method Options](#process-method-options)
+  - [Condition Callables](#condition-callables)
+- [Nested Workflows](#nested-workflows)
+- [Task Settings Integration](#task-settings-integration)
+- [Generator](#generator)
+
+## TLDR
+
+- **Purpose** - Orchestrate sequential execution of multiple tasks in linear pipeline
+- **Declaration** - Use `process` method to declare tasks in execution order
+- **Context sharing** - Context object shared across all tasks for data pipeline
+- **Conditional execution** - Support `:if` and `:unless` options for conditional tasks
+- **Halt behavior** - Configurable stopping on failed/skipped results (default: halt on failed only)
+- **No call method** - Workflows automatically provide execution logic, don't define `call`
+
+## Basic Usage
+
+> [!WARNING]
+> Do **NOT** define a `call` method in workflow classes. The workflow class automatically provides the call logic.
+
+```ruby
+class OrderProcessingWorkflow < CMDx::Workflow
+  # Sequential task execution
+  process ValidateOrderTask
+  process CalculateTaxTask
+  process ChargePaymentTask
+  process FulfillOrderTask
+end
+
+# Execute the workflow
+result = WorkflowProcessOrders.call(order: order, user: current_user)
+
+if result.success?
+  redirect_to success_path
+elsif result.failed?
+  flash[:error] = "Order processing failed: #{result.metadata[:reason]}"
+  redirect_to cart_path
+end
+```
+
+## Task Declaration
+
+Tasks are declared using the `process` method and organized into groups with shared execution options:
+
+```ruby
+class NotificationDeliveryWorkflow < CMDx::Workflow
+  # Single task declaration
+  process PrepareNotificationTask
+
+  # Multiple tasks in one declaration (grouped)
+  process SendEmailTask, SendSmsTask, SendPushTask
+
+  # Tasks with conditions
+  process SendWebhookTask, if: proc { context.webhook_enabled? }
+  process SendSlackTask, unless: :slack_disabled?
+
+  private
+
+  def slack_disabled?
+    !context.user.slack_enabled?
+  end
+end
+```
+
+> [!IMPORTANT]
+> Process steps are executed in the order they are declared (FIFO: first in, first out).
+
+## Context Propagation
+
+The context object is shared across all tasks in the workflow, creating a data pipeline:
+
+```ruby
+class EcommerceProcessingWorkflow < CMDx::Workflow
+  process ValidateOrderTask # Sets context.validation_result
+  process CalculateTaxTask  # Uses context.order, sets context.tax_amount
+  process ChargePaymentTask # Uses context.tax_amount, sets context.payment_id
+  process FulfillOrderTask  # Uses context.payment_id, sets context.tracking_number
+end
+
+result = WorkflowProcessEcommerce.call(order: order)
+# Final context contains data from all executed tasks
+result.context.validation_result # From ValidateOrderTask
+result.context.tax_amount        # From CalculateTaxTask
+result.context.payment_id        # From ChargePaymentTask
+result.context.tracking_number   # From FulfillOrderTask
+```
+
+## Conditional Execution
+
+Tasks can be executed conditionally using `:if` and `:unless` options. Conditions can be procs, lambdas, or method names:
+
+```ruby
+class UserProcessingWorkflow < CMDx::Workflow
+  process ValidateUserTask
+
+  # Proc condition
+  process UpgradeToPremiumTask, if: proc { context.user.premium? }
+
+  # Lambda condition
+  process ProcessInternationalTask, unless: -> { context.user.domestic? }
+
+  # Method condition
+  process LogDebugInfoTask, if: :debug_enabled?
+
+  # Complex condition
+  process SendSpecialOfferTask, if: proc {
+    context.user.active? &&
+    context.feature_enabled?(:offers) &&
+    Time.now.hour.between?(9, 17)
+  }
+
+  private
+
+  def debug_enabled?
+    Rails.env.development?
+  end
+end
+```
+
+## Halt Behavior
+
+Workflows control execution flow through halt behavior, which determines when to stop processing based on task results.
+
+### Default Behavior
+
+By default, workflows halt on `FAILED` status but continue on `SKIPPED`. This reflects the philosophy that skipped tasks are bypass mechanisms, not execution blockers.
+
+```ruby
+class DataProcessingWorkflow < CMDx::Workflow
+  process LoadDataTask     # If this fails, workflow stops
+  process ValidateDataTask # If this is skipped, workflow continues
+  process SaveDataTask     # This only runs if LoadDataTask and ValidateDataTask don't fail
+end
+```
+
+### Class-Level Configuration
+
+Configure halt behavior for the entire workflow using `task_settings!`:
+
+```ruby
+class CriticalDataProcessingWorkflow < CMDx::Workflow
+  # Halt on both failed and skipped results
+  task_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
+
+  process LoadCriticalDataTask
+  process ValidateCriticalDataTask
+end
+
+class OptionalDataProcessingWorkflow < CMDx::Workflow
+  # Never halt, always continue
+  task_settings!(workflow_halt: [])
+
+  process TryLoadDataTask
+  process TryValidateDataTask
+  process TrySaveDataTask
+end
+```
+
+### Group-Level Configuration
+
+Different groups can have different halt behavior:
+
+```ruby
+class UserAccountProcessingWorkflow < CMDx::Workflow
+  # Critical tasks - halt on any failure or skip
+  process CreateUserTask, ValidateUserTask,
+    workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
+
+  # Optional tasks - never halt execution
+  process SendWelcomeEmailTask, CreateProfileTask, workflow_halt: []
+
+  # Notification tasks - use default behavior (halt on failed only)
+  process NotifyAdminTask, LogUserCreationTask
+end
+```
+
+### Available Result Statuses
+
+The following result statuses can be used in `workflow_halt` arrays:
+
+- `CMDx::Result::SUCCESS` - Task completed successfully
+- `CMDx::Result::SKIPPED` - Task was skipped intentionally
+- `CMDx::Result::FAILED` - Task failed due to error or validation
+
+## Process Method Options
+
+The `process` method supports 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. |
+| `:workflow_halt` | Sets which result statuses processing of further steps should be prevented. (default: `CMDx::Result::FAILED`) |
+
+### Condition Callables
+
+Conditions can be provided in several formats:
+
+```ruby
+class AccountProcessingWorkflow < CMDx::Workflow
+  # Proc - executed in workflow instance context
+  process UpgradeAccountTask, if: proc { context.user.admin? }
+
+  # Lambda - executed in workflow instance context
+  process MaintenanceModeTask, unless: -> { context.maintenance_mode? }
+
+  # Symbol - method name called on workflow instance
+  process AdvancedFeatureTask, if: :feature_enabled?
+
+  # String - method name called on workflow instance
+  process OptionalTask, unless: "skip_task?"
+
+  private
+
+  def feature_enabled?
+    context.features.include?(:advanced)
+  end
+
+  def skip_task?
+    context.skip_optional_tasks?
+  end
+end
+```
+
+## Nested Workflows
+
+Workflows can process other workflows, creating hierarchical workflows:
+
+```ruby
+class DataPreProcessingWorkflow < CMDx::Workflow
+  process ValidateInputTask
+  process SanitizeDataTask
+end
+
+class DataProcessingWorkflow < CMDx::Workflow
+  process TransformDataTask
+  process ApplyBusinessLogicTask
+end
+
+class DataPostProcessingWorkflow < CMDx::Workflow
+  process GenerateReportTask
+  process SendNotificationTask
+end
+
+class CompleteDataProcessingWorkflow < CMDx::Workflow
+  process DataPreProcessingWorkflow
+  process DataProcessingWorkflow, if: proc { context.pre_processing_successful? }
+  process DataPostProcessingWorkflow, unless: proc { context.skip_post_processing? }
+end
+```
+
+## Task Settings Integration
+
+Workflows support all task settings and can be configured like regular tasks:
+
+```ruby
+class PaymentProcessingWorkflow < CMDx::Workflow
+  # Configure workflow-specific settings
+  task_settings!(
+    workflow_halt: [CMDx::Result::FAILED],
+    log_level: :debug,
+    tags: [:critical, :payment]
+  )
+
+  # Parameter validation
+  required :order_id, type: :integer
+  optional :notify_user, type: :boolean, default: true
+
+  # Callbacks
+  before_execution :setup_context
+  after_execution :cleanup_resources
+
+  process ValidateOrderTask
+  process ProcessPaymentTask
+  process NotifyUserTask, if: proc { context.notify_user }
+
+  private
+
+  def setup_context
+    context.start_time = Time.now
+  end
+
+  def cleanup_resources
+    context.temp_files&.each(&:delete)
+  end
+end
+```
+
+## Generator
+
+Generate a new workflow using the Rails generator:
+
+```bash
+rails g cmdx:workflow ProcessOrder
+```
+
+This creates a workflow template file under `app/cmds`:
+
+```ruby
+class OrderProcessingWorkflow < ApplicationWorkflow
+  process # TODO
+end
+```
+
+> [!NOTE]
+> The generator creates workflow files in `app/commands/workflow_[name].rb`, inherits from `ApplicationWorkflow` if available (otherwise `CMDx::Workflow`) and handles proper naming conventions.
+
+---
+
+- **Prev:** [Middlewares](middlewares.md)
+- **Next:** [Logging](logging.md)

data/lib/cmdx/callback.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module CMDx
+  ##
+  # Base class for CMDx callbacks that provides lifecycle execution points.
+  #
+  # Callback components can wrap or observe task execution at specific lifecycle
+  # points like before validation, on success, after execution, etc.
+  # Each callback must implement the `call` method which receives the
+  # task instance and callback context.
+  #
+  # @example Basic callback implementation
+  #   class LoggingCallback < CMDx::Callback
+  #     def call(task, callback_type)
+  #       puts "Executing #{callback_type} callback for #{task.class.name}"
+  #       task.logger.info("Callback executed: #{callback_type}")
+  #     end
+  #   end
+  #
+  # @example Callback with initialization parameters
+  #   class NotificationCallback < CMDx::Callback
+  #     def initialize(channels)
+  #       @channels = channels
+  #     end
+  #
+  #     def call(task, callback_type)
+  #       return unless callback_type == :on_success
+  #
+  #       @channels.each do |channel|
+  #         NotificationService.send(channel, "Task #{task.class.name} completed")
+  #       end
+  #     end
+  #   end
+  #
+  # @example Conditional callback execution
+  #   class ErrorReportingCallback < CMDx::Callback
+  #     def call(task, callback_type)
+  #       return unless callback_type == :on_failure
+  #       return unless task.result.failed?
+  #
+  #       ErrorReporter.notify(
+  #         task.errors.full_messages.join(", "),
+  #         context: task.context.to_h
+  #       )
+  #     end
+  #   end
+  #
+  # @see CallbackRegistry Callback management
+  # @see Task Callback integration
+  # @since 1.0.0
+  class Callback
+
+    ##
+    # Executes the callback logic.
+    #
+    # This method must be implemented by subclasses to define the callback
+    # behavior. The method receives the task instance and the callback type
+    # being executed.
+    #
+    # @param task [Task] the task instance being executed
+    # @param callback_type [Symbol] the type of callback being executed
+    # @return [void]
+    # @abstract Subclasses must implement this method
+    def call(_task, _callback_type)
+      raise UndefinedCallError, "call method not defined in #{self.class.name}"
+    end
+
+  end
+end

data/lib/cmdx/callback_registry.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module CMDx
+  ##
+  # The CallbackRegistry collection provides a lifecycle callback system that executes
+  # registered callbacks at specific points during task execution. Callbacks can be
+  # conditionally executed based on task state and support both method references
+  # and callable objects.
+  #
+  # The CallbackRegistry collection extends Hash to provide specialized functionality for
+  # managing collections of callback definitions within CMDx tasks. It handles
+  # callback registration, conditional execution, and inspection.
+  #
+  # @example Basic callback usage
+  #   callback_registry = CallbackRegistry.new
+  #   callback_registry.register(:before_validation, :check_permissions)
+  #   callback_registry.register(:on_success, :log_success, if: :important?)
+  #   callback_registry.register(:on_failure, proc { alert_admin }, unless: :test_env?)
+  #
+  #   callback_registry.call(task, :before_validation)
+  #
+  # @example Hash-like operations
+  #   callback_registry[:before_validation] = [[:check_permissions, {}]]
+  #   callback_registry.keys  # => [:before_validation]
+  #   callback_registry.empty?  # => false
+  #   callback_registry.each { |callback_name, callbacks| puts "#{callback_name}: #{callbacks}" }
+  #
+  # @see Callback Base callback execution class
+  # @see Task Task lifecycle callbacks
+  # @since 1.0.0
+  class CallbackRegistry < Hash
+
+    ##
+    # Initializes a new CallbackRegistry.
+    #
+    # @param registry [CallbackRegistry, Hash, nil] Optional registry to copy from
+    #
+    # @example Initialize empty registry
+    #   registry = CallbackRegistry.new
+    #
+    # @example Initialize with existing registry
+    #   global_callbacks = CallbackRegistry.new
+    #   task_callbacks = CallbackRegistry.new(global_callbacks)
+    def initialize(registry = nil)
+      super()
+
+      registry&.each do |callback_type, callback_definitions|
+        self[callback_type] = callback_definitions.dup
+      end
+    end
+
+    # Registers a callback for the given callback type.
+    #
+    # @param callback [Symbol] The callback type (e.g., :before_validation, :on_success)
+    # @param callables [Array<Symbol, Proc, #call>] Methods or callables to execute
+    # @param options [Hash] Conditions for callback execution
+    # @option options [Symbol, Proc, #call] :if condition that must be truthy
+    # @option options [Symbol, Proc, #call] :unless condition that must be falsy
+    # @param block [Proc] Block to execute as part of the callback
+    # @return [CallbackRegistry] self for method chaining
+    #
+    # @example Register method callback
+    #   registry.register(:before_validation, :check_permissions)
+    #
+    # @example Register conditional callback
+    #   registry.register(:on_failure, :alert_admin, if: :critical?)
+    #
+    # @example Register proc callback
+    #   registry.register(:on_success, proc { log_completion })
+    def register(callback, *callables, **options, &block)
+      callables << block if block_given?
+      (self[callback] ||= []).push([callables, options]).uniq!
+      self
+    end
+
+    # Executes all callbacks registered for a specific callback type on the given task.
+    # Each callback is evaluated for its conditions (if/unless) before execution.
+    #
+    # @param task [Task] The task instance to execute callbacks on
+    # @param callback [Symbol] The callback type to execute (e.g., :before_validation, :on_success)
+    # @return [void]
+    #
+    # @example Execute callbacks
+    #   registry.call(task, :before_validation)
+    #
+    # @example Execute conditional callbacks
+    #   # Only executes if task.critical? returns true
+    #   registry.call(task, :on_failure) # where registry has on_failure :alert, if: :critical?
+    def call(task, callback)
+      return unless key?(callback)
+
+      Array(self[callback]).each do |callables, options|
+        next unless task.__cmdx_eval(options)
+
+        Array(callables).each do |c|
+          if c.is_a?(Callback)
+            c.call(task, callback)
+          else
+            task.__cmdx_try(c)
+          end
+        end
+      end
+    end
+
+  end
+end