cmdx 1.1.2 → 1.5.0

data/lib/cmdx/workflow.rb

@@ -1,117 +1,121 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Sequential task execution orchestration system for CMDx framework.
-  #
-  # Workflow provides declarative composition of multiple tasks into linear pipelines
-  # with conditional execution, context propagation, and configurable halt behavior.
-  # Workflows inherit from Task, gaining all task capabilities including callbacks,
-  # parameter validation, result tracking, and configuration while coordinating
-  # other tasks rather than implementing business logic directly.
-  class Workflow < Task
+  # Provides workflow execution capabilities by organizing tasks into execution groups.
+  # Workflows allow you to define sequences of tasks that can be executed conditionally
+  # with breakpoint handling and context management.
+  module Workflow
 
-    # Data structure containing a group of tasks and their execution options.
-    #
-    # @!attribute [r] tasks
-    #   @return [Array<Class>] array of Task or Workflow classes to execute
-    # @!attribute [r] options
-    #   @return [Hash] execution options including conditional and halt configuration
-    Group = Struct.new(:tasks, :options)
-
-    class << self
+    module ClassMethods
 
-      # Returns the array of workflow groups defined for this workflow class.
+      # Prevents redefinition of the work method to maintain workflow integrity.
       #
-      # Each group contains tasks and their execution options. Groups are processed
-      # sequentially during workflow execution, with each group's tasks executing
-      # in order unless halted by a result status.
+      # @param method_name [Symbol] The name of the method being added
       #
-      # @return [Array<Group>] array of workflow groups containing tasks and options
+      # @raise [RuntimeError] If attempting to redefine the work method
       #
-      # @example Access workflow groups
-      #   class MyWorkflow < CMDx::Workflow
-      #     process TaskA, TaskB
-      #     process TaskC, if: :condition_met?
+      # @example
+      #   class MyWorkflow
+      #     include CMDx::Workflow
+      #     # This would raise an error:
+      #     # def work; end
       #   end
-      #
-      #   MyWorkflow.workflow_groups.size #=> 2
-      #   MyWorkflow.workflow_groups.first.tasks #=> [TaskA, TaskB]
-      def workflow_groups
-        @workflow_groups ||= []
+      def method_added(method_name)
+        raise "cannot redefine #{name}##{method_name} method" if method_name == :work
+
+        super
       end
 
-      # Declares a group of tasks to execute sequentially with optional conditions.
-      #
-      # Tasks are executed in the order specified, with shared context propagated
-      # between executions. Groups support conditional execution and configurable
-      # halt behavior to control workflow flow based on task results.
+      # Returns the collection of execution groups for this workflow.
       #
-      # @param tasks [Array<Class>] Task or Workflow classes to execute in sequence
-      # @param options [Hash] execution configuration options
+      # @return [Array<ExecutionGroup>] Array of execution groups
       #
-      # @option options [Proc, Symbol, String] :if condition that must be truthy for group execution
-      # @option options [Proc, Symbol, String] :unless condition that must be falsy for group execution
-      # @option options [String, Array<String>] :workflow_halt result statuses that halt workflow execution
-      #
-      # @return [void]
-      #
-      # @raise [TypeError] when tasks contain objects that are not Task or Workflow classes
-      #
-      # @example Declare sequential tasks
-      #   class UserRegistrationWorkflow < CMDx::Workflow
-      #     process CreateUserTask, SendWelcomeEmailTask
+      # @example
+      #   class MyWorkflow
+      #     include CMDx::Workflow
+      #     task Task1
+      #     task Task2
+      #     puts execution_groups.size # => 2
       #   end
+      def execution_groups
+        @execution_groups ||= []
+      end
+
+      # Adds multiple tasks to the workflow with optional configuration.
       #
-      # @example Declare conditional task group
-      #   class OrderProcessingWorkflow < CMDx::Workflow
-      #     process ValidateOrderTask
-      #     process ChargePaymentTask, if: ->(workflow) { workflow.context.payment_required? }
-      #     process ShipOrderTask, unless: :digital_product?
-      #     process NotifyAdminTask, if: proc { context.admin.active? }
-      #   end
+      # @param tasks [Array<Class>] Array of task classes to add
+      # @param options [Hash] Configuration options for the task execution
+      # @option options [Hash] :breakpoints Breakpoints that trigger workflow interruption
+      # @option options [Hash] :conditions Conditional logic for task execution
       #
-      # @example Configure halt behavior per group
-      #   class DataProcessingWorkflow < CMDx::Workflow
-      #     process LoadDataTask, ValidateDataTask, workflow_halt: %w[failed skipped]
-      #     process OptionalCleanupTask, workflow_halt: []
+      # @raise [TypeError] If any task is not a CMDx::Task subclass
+      #
+      # @example
+      #   class MyWorkflow
+      #     include CMDx::Workflow
+      #     tasks ValidateTask, ProcessTask, NotifyTask, breakpoints: [:failure, :halt]
       #   end
-      def process(*tasks, **options)
-        workflow_groups << Group.new(
-          tasks.flatten.map do |task|
+      def tasks(*tasks, **options)
+        execution_groups << ExecutionGroup.new(
+          tasks.map do |task|
             next task if task.is_a?(Class) && (task <= Task)
 
-            raise TypeError, "must be a Task or Workflow"
+            raise TypeError, "must be a CMDx::Task"
           end,
           options
         )
       end
+      alias task tasks
+
+    end
+
+    # Represents a group of tasks with shared execution options.
+    # @attr tasks [Array<Class>] Array of task classes in this group
+    # @attr options [Hash] Configuration options for the group
+    ExecutionGroup = Struct.new(:tasks, :options)
 
+    # Extends the including class with workflow capabilities.
+    #
+    # @param base [Class] The class including this module
+    #
+    # @example
+    #   class MyWorkflow
+    #     include CMDx::Workflow
+    #     # Now has access to task, tasks, and work methods
+    #   end
+    def self.included(base)
+      base.extend(ClassMethods)
     end
 
-    # Each group is evaluated for conditional execution, and if the group should
-    # execute, all tasks in the group are called in sequence. If any task returns
-    # a status that matches the workflow halt criteria, execution is halted and
-    # the result is thrown.
+    # Executes the workflow by processing each execution group sequentially.
+    # Tasks within each group are executed based on conditional logic and breakpoint handling.
     #
     # @return [void]
     #
-    # @raise [Fault] if a task fails and its status matches the workflow halt criteria
+    # @raise [CMDx::Fault] If a breakpoint is encountered during execution
     #
-    # @example Execute workflow
-    #   workflow = MyWorkflow.new(user_id: 123)
-    #   workflow.call
-    def call
-      self.class.workflow_groups.each do |group|
-        next unless cmdx_eval(group.options)
+    # @example
+    #   workflow = MyWorkflow.new
+    #   workflow.work # Executes all tasks in the workflow
+    # @example
+    #   class DataProcessingWorkflow
+    #     include CMDx::Workflow
+    #     task ValidateDataTask, breakpoints: [:failure]
+    #     task ProcessDataTask, breakpoints: [:halt]
+    #     task NotifyCompletionTask
+    #   end
+    #   workflow = DataProcessingWorkflow.new
+    #   workflow.work # Stops on first breakpoint encountered
+    def work
+      self.class.execution_groups.each do |group|
+        next unless Utils::Condition.evaluate(self, group.options, self)
 
-        workflow_halt = Array(
-          group.options[:workflow_halt] ||
-          cmd_setting(:workflow_halt)
-        ).map(&:to_s)
+        breakpoints = group.options[:breakpoints] || self.class.settings[:workflow_breakpoints]
+        breakpoints = Array(breakpoints).map(&:to_s).uniq
 
         group.tasks.each do |task|
-          task_result = task.call(context)
-          next unless workflow_halt.include?(task_result.status)
+          task_result = task.execute(context)
+          next unless breakpoints.include?(task_result.status)
 
           throw!(task_result)
         end

data/lib/cmdx.rb

@@ -2,47 +2,53 @@
 
 require "bigdecimal"
 require "date"
-require "i18n"
+require "forwardable"
 require "json"
 require "logger"
-require "pp"
 require "securerandom"
+require "set"
 require "time"
 require "timeout"
+require "yaml"
 require "zeitwerk"
 
-module CMDx; end
+module CMDx
+
+  extend self
+
+  def gem_path
+    @gem_path ||= Pathname.new(__dir__).parent
+  end
+
+end
 
 # Set up Zeitwerk loader for the CMDx gem
 loader = Zeitwerk::Loader.for_gem
-loader.inflector.inflect("cmdx" => "CMDx")
-loader.ignore("#{__dir__}/cmdx/core_ext")
+loader.inflector.inflect("cmdx" => "CMDx", "json" => "JSON")
 loader.ignore("#{__dir__}/cmdx/configuration")
+loader.ignore("#{__dir__}/cmdx/exceptions")
 loader.ignore("#{__dir__}/cmdx/faults")
 loader.ignore("#{__dir__}/cmdx/railtie")
-loader.ignore("#{__dir__}/cmdx/rspec")
 loader.ignore("#{__dir__}/generators")
 loader.ignore("#{__dir__}/locales")
 loader.setup
 
-# Pre-load core extensions to avoid circular dependencies
-require_relative "cmdx/core_ext/module"
-require_relative "cmdx/core_ext/object"
-require_relative "cmdx/core_ext/hash"
-
 # Pre-load configuration to make module methods available
 # This is acceptable since configuration is fundamental to the framework
 require_relative "cmdx/configuration"
 
+# Pre-load exceptions to make them available at the top level
+# This ensures CMDx::Error and its descendants are always available
+require_relative "cmdx/exceptions"
+
 # Pre-load fault classes to make them available at the top level
-# This ensures CMDx::Failed and CMDx::Skipped are always available
+# This ensures CMDx::FailFault and CMDx::SkipFault are always available
 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/task_generator"
-  require_relative "generators/cmdx/workflow_generator"
 end
 
 # Load the Railtie last after everything else is required so we don't

data/lib/generators/cmdx/install_generator.rb

@@ -1,31 +1,32 @@
 # frozen_string_literal: true
 
 module Cmdx
-  # Rails generator for creating CMDx initializer configuration file.
+  # Generates CMDx initializer file for Rails applications
   #
-  # This generator creates a new initializer file at config/initializers/cmdx.rb
-  # with global configuration settings for the CMDx framework. The generated
-  # initializer provides a centralized location for configuring CMDx behavior
-  # such as logging, error handling, and default parameter settings.
+  # This generator creates a configuration initializer that sets up global
+  # CMDx settings for the Rails application. It copies a pre-configured
+  # initializer template to the standard Rails initializers directory.
   class InstallGenerator < Rails::Generators::Base
 
     source_root File.expand_path("templates", __dir__)
 
     desc "Creates CMDx initializer with global configuration settings"
 
-    # Copies the CMDx initializer template to the Rails application.
+    # Copies the CMDx initializer template to the Rails application
     #
-    # Creates a new initializer file at config/initializers/cmdx.rb by copying
-    # the install.rb template. This file contains the default CMDx configuration
-    # that can be customized for the specific application needs.
+    # Creates a new initializer file at `config/initializers/cmdx.rb` containing
+    # the default CMDx configuration settings. This allows applications to
+    # customize global CMDx behavior through the standard Rails configuration
+    # pattern.
     #
     # @return [void]
     #
-    # @raise [Thor::Error] if the destination file cannot be created or already exists without force
-    #
-    # @example Generate CMDx initializer
+    # @example Basic usage
     #   rails generate cmdx:install
-    #   # Creates config/initializers/cmdx.rb
+    #
+    # @example Custom initializer location
+    #   generator.copy_initializer_file
+    #   # => Creates config/initializers/cmdx.rb
     def copy_initializer_file
       copy_file("install.rb", "config/initializers/cmdx.rb")
     end

data/lib/generators/cmdx/task_generator.rb

@@ -1,80 +1,55 @@
 # frozen_string_literal: true
 
 module Cmdx
-  # Rails generator for creating CMDx task files.
+  # Generates CMDx task files for Rails applications
   #
-  # This generator creates task files in the app/cmds directory with proper
-  # class naming conventions and inheritance. It ensures task names end with
-  # "Task" suffix and creates files in the correct location within the Rails
-  # application structure.
+  # This generator creates task classes that inherit from either ApplicationTask
+  # (if defined) or CMDx::Task. It generates the task file in the standard
+  # Rails tasks directory structure.
   class TaskGenerator < Rails::Generators::NamedBase
 
     source_root File.expand_path("templates", __dir__)
-    check_class_collision suffix: "Task"
 
     desc "Creates a task with the given NAME"
 
-    # Creates the task file from the template.
+    # Copies the task template to the Rails application
     #
-    # Generates a new task file in the app/cmds directory based on the provided
-    # name. The file name is normalized to ensure it ends with "_task.rb" and
-    # is placed in the appropriate subdirectory structure.
+    # Creates a new task file at `app/tasks/[class_path]/[file_name].rb` using
+    # the task template. The file is placed in the standard Rails tasks directory
+    # structure, maintaining proper namespacing if the task is nested.
     #
     # @return [void]
     #
-    # @example Generate a user task
-    #   rails generate cmdx:task user
-    #   #=> Creates app/cmds/user_task.rb
+    # @example Basic usage
+    #   rails generate cmdx:task UserRegistration
+    #   # => Creates app/tasks/user_registration.rb
     #
-    # @example Generate a nested task
-    #   rails generate cmdx:task admin/users
-    #   #=> Creates app/cmds/admin/users_task.rb
+    # @example Nested task
+    #   rails generate cmdx:task Admin::UserManagement
+    #   # => Creates app/tasks/admin/user_management.rb
     def copy_files
-      name = file_name.sub(/_?task$/i, "")
-      path = File.join("app/cmds", class_path, "#{name}_task.rb")
+      path = File.join("app/tasks", class_path, "#{file_name}.rb")
       template("task.rb.tt", path)
     end
 
     private
 
-    # Ensures the class name ends with "Task" suffix.
+    # Determines the appropriate parent class name for the generated task
     #
-    # Takes the provided class name and appends "Task" if it doesn't already
-    # end with that suffix, ensuring consistent naming conventions across
-    # all generated task classes.
+    # Attempts to use ApplicationTask if it exists in the application, otherwise
+    # falls back to CMDx::Task. This allows applications to define their own
+    # base task class while maintaining compatibility.
     #
-    # @return [String] the class name with "Task" suffix
+    # @return [Class] The parent class for the generated task
     #
-    # @example Class name without suffix
-    #   # Given name: "User"
-    #   class_name #=> "UserTask"
+    # @example
+    #   parent_class_name # => ApplicationTask
     #
-    # @example Class name with suffix
-    #   # Given name: "UserTask"
-    #   class_name #=> "UserTask"
-    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 it exists in the
-    # application, otherwise falls back to CMDx::Task as the base class.
-    # This allows applications to define their own base task class with
-    # common functionality.
-    #
-    # @return [Class] the parent class for the generated task
-    #
-    # @raise [StandardError] if neither ApplicationTask nor CMDx::Task are available
-    #
-    # @example With ApplicationTask defined
-    #   parent_class_name #=> ApplicationTask
-    #
-    # @example Without ApplicationTask
-    #   parent_class_name #=> CMDx::Task
+    # @example Fallback behavior
+    #   parent_class_name # => CMDx::Task
     def parent_class_name
       ApplicationTask
-    rescue StandardError
+    rescue NameError
       CMDx::Task
     end
 

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

@@ -1,69 +1,34 @@
 # frozen_string_literal: true
 
 CMDx.configure do |config|
-  # Task halt configuration - controls when call! raises faults
+  # Task breakpoint configuration - controls when execute! raises faults
   # See https://github.com/drexed/cmdx/blob/main/docs/outcomes/statuses.md for more details
   #
   # Available statuses: "success", "skipped", "failed"
   # If set to an empty array, task will never halt
-  config.task_halt = %w[failed]
+  config.task_breakpoints = %w[failed]
 
-  # Workflow halt configuration - controls when workflows stop execution
+  # Workflow breakpoint configuration - controls when workflows stop execution
   # When a task returns these statuses, subsequent workflow tasks won't execute
   # See https://github.com/drexed/cmdx/blob/main/docs/workflow.md for more details
   #
   # Available statuses: "success", "skipped", "failed"
   # If set to an empty array, workflow will never halt
-  config.workflow_halt = %w[failed]
+  config.workflow_breakpoints = %w[failed]
 
   # Logger configuration - choose from multiple formatters
   # See https://github.com/drexed/cmdx/blob/main/docs/logging.md for more details
   #
   # Available formatters:
-  # - CMDx::LogFormatters::Line
-  # - CMDx::LogFormatters::PrettyLine
   # - CMDx::LogFormatters::Json
-  # - CMDx::LogFormatters::PrettyJson
   # - CMDx::LogFormatters::KeyValue
-  # - CMDx::LogFormatters::PrettyKeyValue
+  # - CMDx::LogFormatters::Line
   # - CMDx::LogFormatters::Logstash
   # - CMDx::LogFormatters::Raw
-  config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
-
-  # Global middlewares - automatically applied to all tasks
-  # See https://github.com/drexed/cmdx/blob/main/docs/middlewares.md for more details
-  #
-  # config.middlewares.use CMDx::Middlewares::Correlate
-  # config.middlewares.use CMDx::Middlewares::Timeout, seconds: 30
-  # config.middlewares.use CustomAuthMiddleware, if: :admin?
-  # config.middlewares.use CustomPerfMiddleware.new(threshold: 5.0)
-
-  # Global callbacks - automatically applied to all tasks
-  # See https://github.com/drexed/cmdx/blob/main/docs/callbacks.md for more details
-  #
-  # config.callbacks.register :before_execution, :log_task_start
-  # config.callbacks.register :after_execution, TrackTaskCompletion
-  # config.callbacks.register :on_success, NotificationCallback.new(via: [:email, :slack])
-  # config.callbacks.register :on_failure, :alert_support, if: :critical?
-  # config.callbacks.register :on_complete, proc { |task, type|
-  #   Metrics.increment("task.#{task.class.name.underscore}.completed")
-  # }
-
-  # Global coercions - custom parameter type conversions
-  # See https://github.com/drexed/cmdx/blob/main/docs/parameters/coercions.md for more details
-  #
-  # config.coercions.register :money, MoneyCoercion
-  # config.coercions.register :tags, TagsCoercion.new
-  # config.coercions.register :slug, proc { |value|
-  #   value.to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/-+/, '-').strip('-')
-  # }
-
-  # Global validators - parameter validation logic
-  # See https://github.com/drexed/cmdx/blob/main/docs/parameters/validations.md for more details
-  #
-  # config.validators.register :email, EmailValidator
-  # config.validators.register :phone, PhoneValidator.new
-  # config.validators.register :phone, proc { |value, options|
-  #   PhoneValidator.validate(value, options)
-  # }
+  config.logger = Logger.new(
+    $stdout,
+    progname: "cmdx",
+    formatter: CMDx::LogFormatters::Line.new,
+    level: Logger::INFO
+  )
 end

data/lib/generators/cmdx/templates/task.rb.tt

@@ -1,8 +1,9 @@
 <% module_namespacing do -%>
   class <%= class_name %> < <%= parent_class_name %>
 
-    def call
-      # TODO
+    def work
+      # Your logic here...
+      # Docs: https://github.com/drexed/cmdx
     end
 
   end

data/lib/locales/en.yml

@@ -1,15 +1,29 @@
 en:
   cmdx:
+    attributes:
+      required: "must be accessible via the source"
+      undefined: "delegates to undefined method %{method}"
     coercions:
       into_a: "could not coerce into a %{type}"
       into_an: "could not coerce into an %{type}"
-      into_any: "could not coerce into one of: %{values}"
+      into_any: "could not coerce into one of: %{types}"
       unknown: "unknown %{type} coercion type"
     faults:
       unspecified: "no reason given"
-    parameters:
-      required: "is a required parameter"
-      undefined: "delegates to undefined method %{source}"
+    types:
+      array: "array"
+      big_decimal: "big decimal"
+      boolean: "boolean"
+      complex: "complex"
+      date_time: "date time"
+      date: "date"
+      float: "float"
+      hash: "hash"
+      integer: "integer"
+      rational: "rational"
+      string: "string"
+      symbol: "symbol"
+      time: "time"
     validators:
       exclusion:
         of: "must not be one of: %{values}"