cmdx 1.0.1 → 1.1.1

data/lib/generators/cmdx/install_generator.rb

@@ -1,48 +1,31 @@
 # frozen_string_literal: true
 
 module Cmdx
-  ##
-  # Rails generator for creating CMDx initializer configuration.
+  # Rails generator for creating CMDx initializer configuration file.
   #
-  # This generator creates a configuration initializer file that sets up
-  # global CMDx settings for task execution, workflow processing, logging,
-  # and error handling behaviors.
-  #
-  # The generated initializer provides sensible defaults that can be
-  # customized for specific application requirements.
-  #
-  # @example Generate CMDx initializer
-  #   rails generate cmdx:install
-  #
-  # @example Generated file location
-  #   config/initializers/cmdx.rb
-  #
-  # @since 1.0.0
+  # 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.
   class InstallGenerator < Rails::Generators::Base
 
     source_root File.expand_path("templates", __dir__)
 
     desc "Creates CMDx initializer with global configuration settings"
 
-    ##
-    # Copies the CMDx configuration template to the Rails initializers directory.
+    # Copies the CMDx initializer template to the Rails application.
     #
-    # Creates a new initializer file at `config/initializers/cmdx.rb` with
-    # default configuration settings for:
-    # - Task halt behaviors
-    # - Timeout settings
-    # - Workflow execution controls
-    # - Logger configuration
+    # 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.
     #
     # @return [void]
-    # @raise [Thor::Error] if the destination file cannot be created
     #
-    # @example Generated initializer content
-    #   CMDx.configure do |config|
-    #     config.task_halt = CMDx::Result::FAILED
-
-    #     # ... additional settings
-    #   end
+    # @raise [Thor::Error] if the destination file cannot be created or already exists without force
+    #
+    # @example Generate CMDx initializer
+    #   rails generate cmdx:install
+    #   # 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,28 +1,12 @@
 # frozen_string_literal: true
 
 module Cmdx
-  ##
-  # Rails generator for creating CMDx task classes.
+  # Rails generator for creating CMDx task files.
   #
-  # 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
+  # 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.
   class TaskGenerator < Rails::Generators::NamedBase
 
     source_root File.expand_path("templates", __dir__)
@@ -30,25 +14,21 @@ module Cmdx
 
     desc "Creates a task with the given NAME"
 
-    ##
-    # Copies the task template to the application commands directory.
+    # Creates the task file from the template.
     #
-    # 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
+    # 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.
     #
     # @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
+    # @example Generate a user task
+    #   rails generate cmdx:task user
+    #   #=> Creates app/cmds/user_task.rb
+    #
+    # @example Generate a nested task
+    #   rails generate cmdx:task admin/users
+    #   #=> Creates app/cmds/admin/users_task.rb
     def copy_files
       name = file_name.sub(/_?task$/i, "")
       path = File.join("app/cmds", class_path, "#{name}_task.rb")
@@ -57,37 +37,41 @@ module Cmdx
 
     private
 
-    ##
-    # Normalizes the class name by ensuring "Task" suffix.
+    # Ensures the class name ends with "Task" suffix.
     #
-    # Ensures consistent class naming by adding "Task" suffix if not
-    # already present, allowing users to specify either "SendEmail"
-    # or "SendEmailTask".
+    # 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.
     #
-    # @return [String] the normalized class name with "Task" suffix
+    # @return [String] the class name with "Task" suffix
     #
-    # @example Class name normalization
-    #   # Input: "SendEmail"
-    #   # Output: "SendEmailTask"
+    # @example Class name without suffix
+    #   # Given name: "User"
+    #   class_name #=> "UserTask"
     #
-    #   # Input: "SendEmailTask"
-    #   # Output: "SendEmailTask"
+    # @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 available,
-    # falling back to CMDx::Task if ApplicationTask is not defined.
-    # This allows applications to define custom base task behavior.
+    # 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
     #
-    # @return [String] the parent class name to inherit from
+    # @example With ApplicationTask defined
+    #   parent_class_name #=> ApplicationTask
     #
-    # @example Parent class resolution
-    #   # If ApplicationTask exists: "ApplicationTask"
-    #   # If ApplicationTask missing: "CMDx::Task"
+    # @example Without ApplicationTask
+    #   parent_class_name #=> CMDx::Task
     def parent_class_name
       ApplicationTask
     rescue StandardError

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

@@ -33,19 +33,37 @@ CMDx.configure do |config|
   # 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::Timeout, seconds: 30
   # config.middlewares.use CMDx::Middlewares::Correlate
-  # config.middlewares.use CustomAuthMiddleware, role: "admin"
-  # config.middlewares.use PerformanceMiddleware.new(threshold: 5.0)
+  # 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, :log_task_end
-  # config.callbacks.register :on_success, NotificationCallback.new([:email])
+  # 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, callback_type|
+  # 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)
+  # }
 end

data/lib/generators/cmdx/workflow_generator.rb

@@ -1,36 +1,12 @@
 # frozen_string_literal: true
 
 module Cmdx
-  ##
-  # Rails generator for creating CMDx workflow task classes.
+  # Rails generator for creating CMDx workflow files.
   #
-  # 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
+  # This generator creates workflow files in the app/cmds directory with proper
+  # class naming conventions and inheritance. It ensures workflow names end with
+  # "Workflow" suffix and creates files in the correct location within the Rails
+  # application structure.
   class WorkflowGenerator < Rails::Generators::NamedBase
 
     source_root File.expand_path("templates", __dir__)
@@ -38,28 +14,23 @@ module Cmdx
 
     desc "Creates a workflow with the given NAME"
 
-    ##
-    # Copies the workflow task template to the application commands directory.
+    # Creates the workflow file from the template.
     #
-    # 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"
+    # Generates a new workflow file in the app/cmds directory based on the provided
+    # name. The file name is normalized to ensure it ends with "_workflow.rb" and
+    # is placed in the appropriate subdirectory structure.
     #
     # @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
+    # @raise [Thor::Error] if the destination file cannot be created or already exists without force
+    #
+    # @example Generate a user workflow
+    #   rails generate cmdx:workflow user
+    #   #=> Creates app/cmds/user_workflow.rb
     #
-    #   # Input: rails generate cmdx:workflow PaymentWorkflow
-    #   # Creates: app/cmds/payment_workflow.rb
-    #   # Class: PaymentWorkflow
+    # @example Generate a nested workflow
+    #   rails generate cmdx:workflow admin/users
+    #   #=> Creates app/cmds/admin/users_workflow.rb
     def copy_files
       name = file_name.sub(/_?workflow$/i, "")
       path = File.join("app/cmds", class_path, "#{name}_workflow.rb")
@@ -68,37 +39,41 @@ module Cmdx
 
     private
 
-    ##
-    # Normalizes the class name by ensuring it ends with "Workflow".
+    # Ensures the class name ends with "Workflow" suffix.
     #
-    # 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".
+    # Takes the provided class name and appends "Workflow" if it doesn't already
+    # end with that suffix, ensuring consistent naming conventions across
+    # all generated workflow classes.
     #
-    # @return [String] the normalized class name with "Workflow" suffix
+    # @return [String] the class name with "Workflow" suffix
     #
-    # @example Class name normalization
-    #   # Input: "OrderProcessing"
-    #   # Output: "OrderProcessingWorkflow"
+    # @example Class name without suffix
+    #   # Given name: "User"
+    #   class_name #=> "UserWorkflow"
     #
-    #   # Input: "PaymentWorkflow"
-    #   # Output: "PaymentWorkflow"
+    # @example Class name with suffix
+    #   # Given name: "UserWorkflow"
+    #   class_name #=> "UserWorkflow"
     def class_name
       @class_name ||= super.end_with?("Workflow") ? super : "#{super}Workflow"
     end
 
-    ##
-    # Determines the parent class for the generated workflow task.
+    # Determines the parent class for the generated workflow.
+    #
+    # Attempts to use ApplicationWorkflow as the parent class if it exists in the
+    # application, otherwise falls back to CMDx::Workflow as the base class.
+    # This allows applications to define their own base workflow class with
+    # common functionality.
+    #
+    # @return [Class] the parent class for the generated workflow
     #
-    # 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.
+    # @raise [StandardError] if neither ApplicationWorkflow nor CMDx::Workflow are available
     #
-    # @return [String] the parent class name to inherit from
+    # @example With ApplicationWorkflow defined
+    #   parent_class_name #=> ApplicationWorkflow
     #
-    # @example Parent class resolution
-    #   # If ApplicationWorkflow exists: "ApplicationWorkflow"
-    #   # If ApplicationWorkflow missing: "CMDx::Workflow"
+    # @example Without ApplicationWorkflow
+    #   parent_class_name #=> CMDx::Workflow
     def parent_class_name
       ApplicationWorkflow
     rescue StandardError

data/lib/locales/ar.yml

@@ -11,7 +11,6 @@ ar:
       required: "معامل مطلوب"
       undefined: "يفوض لطريقة غير معرفة %{source}"
     validators:
-      custom: "غير صالح"
       exclusion:
         of: "يجب ألا يكون أحد: %{values}"
         within: "يجب ألا يكون بين %{min} و %{max}"

data/lib/locales/cs.yml

@@ -11,7 +11,6 @@ cs:
       required: "je povinný parametr"
       undefined: "deleguje na nedefinovanou metodu %{source}"
     validators:
-      custom: "není platný"
       exclusion:
         of: "nesmí být jeden z: %{values}"
         within: "nesmí být mezi %{min} a %{max}"

data/lib/locales/da.yml

@@ -11,7 +11,6 @@ da:
       required: "er en påkrævet parameter"
       undefined: "delegerer til udefineret metode %{source}"
     validators:
-      custom: "er ikke gyldig"
       exclusion:
         of: "må ikke være en af: %{values}"
         within: "må ikke være mellem %{min} og %{max}"

data/lib/locales/de.yml

@@ -11,7 +11,6 @@ de:
       required: "ist ein erforderlicher Parameter"
       undefined: "delegiert an undefinierte Methode %{source}"
     validators:
-      custom: "ist nicht gültig"
       exclusion:
         of: "darf nicht einer von: %{values} sein"
         within: "darf nicht zwischen %{min} und %{max} liegen"

data/lib/locales/el.yml

@@ -11,7 +11,6 @@ el:
       required: "είναι υποχρεωτική παράμετρος"
       undefined: "αναθέτει σε μη ορισμένη μέθοδο %{source}"
     validators:
-      custom: "δεν είναι έγκυρο"
       exclusion:
         of: "δεν πρέπει να είναι ένα από: %{values}"
         within: "δεν πρέπει να είναι μεταξύ %{min} και %{max}"

data/lib/locales/en.yml

@@ -11,7 +11,6 @@ en:
       required: "is a required parameter"
       undefined: "delegates to undefined method %{source}"
     validators:
-      custom: "is not valid"
       exclusion:
         of: "must not be one of: %{values}"
         within: "must not be within %{min} and %{max}"

data/lib/locales/es.yml

@@ -11,7 +11,6 @@ es:
       required: "es un parámetro requerido"
       undefined: "delegado al método indefinido %{source}"
     validators:
-      custom: "no es válida"
       exclusion:
         of: "no debe ser uno de: %{values}"
         within: "no debe estar dentro %{min} y %{max}"

data/lib/locales/fi.yml

@@ -11,7 +11,6 @@ fi:
       required: "on pakollinen parametri"
       undefined: "delegoi määrittelemättömään metodiin %{source}"
     validators:
-      custom: "ei ole kelvollinen"
       exclusion:
         of: "ei saa olla mikään seuraavista: %{values}"
         within: "ei saa olla välillä %{min} ja %{max}"

data/lib/locales/fr.yml

@@ -11,7 +11,6 @@ fr:
       required: "est un paramètre obligatoire"
       undefined: "délègue à une méthode indéfinie %{source}"
     validators:
-      custom: "n'est pas valide"
       exclusion:
         of: "ne doit pas être un de: %{values}"
         within: "ne doit pas être entre %{min} et %{max}"

data/lib/locales/he.yml

@@ -11,7 +11,6 @@ he:
       required: "הוא פרמטר חובה"
       undefined: "מאציל למתודה לא מוגדרת %{source}"
     validators:
-      custom: "לא תקין"
       exclusion:
         of: "לא יכול להיות אחד מהבאים: %{values}"
         within: "לא יכול להיות בין %{min} ל%{max}"

data/lib/locales/hi.yml

@@ -11,7 +11,6 @@ hi:
       required: "एक आवश्यक पैरामीटर है"
       undefined: "अपरिभाषित मेथड %{source} को प्रत्यायोजित करता है"
     validators:
-      custom: "मान्य नहीं है"
       exclusion:
         of: "इनमें से एक नहीं होना चाहिए: %{values}"
         within: "%{min} और %{max} के बीच नहीं होना चाहिए"

data/lib/locales/it.yml

@@ -11,7 +11,6 @@ it:
       required: "è un parametro obbligatorio"
       undefined: "delega al metodo indefinito %{source}"
     validators:
-      custom: "non è valido"
       exclusion:
         of: "non deve essere uno di: %{values}"
         within: "non deve essere tra %{min} e %{max}"

data/lib/locales/ja.yml

@@ -11,7 +11,6 @@ ja:
       required: "必須パラメータです"
       undefined: "未定義メソッド%{source}に委譲します"
     validators:
-      custom: "無効です"
       exclusion:
         of: "次のいずれかであってはいけません: %{values}"
         within: "%{min}と%{max}の間であってはいけません"

data/lib/locales/ko.yml

@@ -11,7 +11,6 @@ ko:
       required: "필수 매개변수입니다"
       undefined: "정의되지 않은 메서드 %{source}에 위임합니다"
     validators:
-      custom: "유효하지 않습니다"
       exclusion:
         of: "다음 중 하나가 아니어야 합니다: %{values}"
         within: "%{min}과 %{max} 사이에 있지 않아야 합니다"

data/lib/locales/nl.yml

@@ -11,7 +11,6 @@ nl:
       required: "is een vereiste parameter"
       undefined: "delegeert naar ongedefinieerde methode %{source}"
     validators:
-      custom: "is niet geldig"
       exclusion:
         of: "mag niet een van zijn: %{values}"
         within: "mag niet tussen %{min} en %{max} liggen"

data/lib/locales/no.yml

@@ -11,7 +11,6 @@
       required: "er en påkrevd parameter"
       undefined: "delegerer til udefinert metode %{source}"
     validators:
-      custom: "er ikke gyldig"
       exclusion:
         of: "må ikke være en av: %{values}"
         within: "må ikke være mellom %{min} og %{max}"

data/lib/locales/pl.yml

@@ -11,7 +11,6 @@ pl:
       required: "jest wymaganym parametrem"
       undefined: "deleguje do niezdefiniowanej metody %{source}"
     validators:
-      custom: "jest nieprawidłowy"
       exclusion:
         of: "nie może być jednym z: %{values}"
         within: "nie może być między %{min} a %{max}"

data/lib/locales/pt.yml

@@ -11,7 +11,6 @@ pt:
       required: "é um parâmetro obrigatório"
       undefined: "delega para método indefinido %{source}"
     validators:
-      custom: "não é válido"
       exclusion:
         of: "não deve ser um de: %{values}"
         within: "não deve estar entre %{min} e %{max}"

data/lib/locales/ru.yml

@@ -11,7 +11,6 @@ ru:
       required: "обязательный параметр"
       undefined: "делегирует неопределенному методу %{source}"
     validators:
-      custom: "недействительный"
       exclusion:
         of: "не должен быть одним из: %{values}"
         within: "не должен быть между %{min} и %{max}"

data/lib/locales/sv.yml

@@ -11,7 +11,6 @@ sv:
       required: "är en obligatorisk parameter"
       undefined: "delegerar till odefinierad metod %{source}"
     validators:
-      custom: "är inte giltig"
       exclusion:
         of: "får inte vara en av: %{values}"
         within: "får inte vara mellan %{min} och %{max}"

data/lib/locales/th.yml

@@ -11,7 +11,6 @@ th:
       required: "เป็นพารามิเตอร์ที่จำเป็น"
       undefined: "ส่งต่อไปยังเมธอดที่ไม่ได้กำหนด %{source}"
     validators:
-      custom: "ไม่ถูกต้อง"
       exclusion:
         of: "ต้องไม่เป็นหนึ่งใน: %{values}"
         within: "ต้องไม่อยู่ระหว่าง %{min} และ %{max}"

data/lib/locales/tr.yml

@@ -11,7 +11,6 @@ tr:
       required: "gerekli bir parametredir"
       undefined: "tanımsız metoda %{source} yetki verir"
     validators:
-      custom: "geçerli değil"
       exclusion:
         of: "şunlardan biri olmamalı: %{values}"
         within: "%{min} ve %{max} arasında olmamalı"

data/lib/locales/vi.yml

@@ -11,7 +11,6 @@ vi:
       required: "là một tham số bắt buộc"
       undefined: "ủy quyền cho phương thức không xác định %{source}"
     validators:
-      custom: "không hợp lệ"
       exclusion:
         of: "không được là một trong: %{values}"
         within: "không được nằm giữa %{min} và %{max}"

data/lib/locales/zh.yml

@@ -11,7 +11,6 @@ zh:
       required: "是必需参数"
       undefined: "委托给未定义的方法%{source}"
     validators:
-      custom: "无效"
       exclusion:
         of: "不能是以下任一值: %{values}"
         within: "不能在%{min}和%{max}之间"