cmdx 1.20.0 → 2.0.0

data/lib/generators/cmdx/install_generator.rb

@@ -1,32 +1,22 @@
 # frozen_string_literal: true
 
 module Cmdx
-  # Generates CMDx initializer file for Rails applications
+  # Rails generator that scaffolds the CMDx initializer at
+  # `config/initializers/cmdx.rb`. The initializer template seeds global
+  # {CMDx.configuration} defaults (middlewares, callbacks, coercions,
+  # validators, telemetry) that all tasks inherit from.
   #
-  # 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.
+  # Invoked via `rails generate cmdx:install`.
   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
-    #
-    # 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.
+    # Copies the initializer template into the host application's
+    # `config/initializers` directory.
     #
     # @return [void]
-    #
-    # @example Basic usage
-    #   rails generate cmdx:install
-    #
-    # @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,32 +1,23 @@
 # frozen_string_literal: true
 
 module Cmdx
-  # Generates CMDx task files for Rails applications
+  # Rails generator that scaffolds a new {CMDx::Task} subclass under
+  # `app/tasks`, honoring nested module paths supplied through the NAME
+  # argument (e.g. `Billing::ChargeCard` writes to
+  # `app/tasks/billing/charge_card.rb`).
   #
-  # 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.
+  # Invoked via `rails generate cmdx:task NAME`.
+  #
+  # @see CMDx::Task
   class TaskGenerator < Rails::Generators::NamedBase
 
     source_root File.expand_path("templates", __dir__)
 
     desc "Creates a task with the given NAME"
 
-    # Copies the task template to the Rails application
-    #
-    # 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.
+    # Renders `task.rb.tt` into `app/tasks/<class_path>/<file_name>.rb`.
     #
     # @return [void]
-    #
-    # @example Basic usage
-    #   rails generate cmdx:task UserRegistration
-    #   # => Creates app/tasks/user_registration.rb
-    #
-    # @example Nested task
-    #   rails generate cmdx:task Admin::UserManagement
-    #   # => Creates app/tasks/admin/user_management.rb
     def copy_files
       path = File.join("app/tasks", class_path, "#{file_name}.rb")
       template("task.rb.tt", path)
@@ -34,19 +25,11 @@ module Cmdx
 
     private
 
-    # Determines the appropriate parent class name for the generated task
-    #
-    # 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 [Class] The parent class for the generated task
-    #
-    # @example
-    #   parent_class_name # => ApplicationTask
+    # Selects the parent class for the generated task: prefers the host
+    # application's `ApplicationTask` when defined, falling back to
+    # {CMDx::Task} otherwise. Consumed by the ERB template via `<%= %>`.
     #
-    # @example Fallback behavior
-    #   parent_class_name # => CMDx::Task
+    # @return [Class] either `ApplicationTask` or {CMDx::Task}
     def parent_class_name
       ApplicationTask
     rescue NameError

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

@@ -1,61 +1,137 @@
 # frozen_string_literal: true
 
 CMDx.configure do |config|
-  # 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_breakpoints = %w[failed]
-
-  # 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_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::Json
-  # - CMDx::LogFormatters::KeyValue
-  # - CMDx::LogFormatters::Line
-  # - CMDx::LogFormatters::Logstash
-  # - CMDx::LogFormatters::Raw
-  config.logger = Logger.new(
-    $stdout,
-    progname: "cmdx",
-    formatter: CMDx::LogFormatters::Line.new,
-    level: Logger::INFO
-  )
-
-  # Rollback configuration - controls which statuses trigger task rollback
-  # 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 rollback
-  config.rollback_on = %w[failed]
-
-  # Default locale configuration - used for built-in translation lookups
-  # Must match the basename of a YAML file in lib/locales/ (e.g. "en", "es", "ja")
+  # ===========================================================================
+  # Locale
+  # ===========================================================================
+  # Fallback locale for built-in messages (validation, coercion, etc.) when
+  # the I18n gem is not present. With I18n loaded, CMDx follows `I18n.locale`.
+  #
   # config.default_locale = "en"
 
-  # Backtrace configuration - controls whether to log backtraces on faults and exceptions
-  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#backtraces
-  # config.backtrace = false
-  # config.backtrace_cleaner = nil
+  # ===========================================================================
+  # Strict context
+  # ===========================================================================
+  # When true, dynamic reads on `context` raise `NoMethodError` for unknown
+  # keys instead of returning `nil` (`[]`, `fetch`, `dig`, and `?` predicates
+  # stay lenient). Override per-task via `settings(strict_context: true)`.
+  #
+  # config.strict_context = true
+
+  # ===========================================================================
+  # Correlation ID (xid)
+  # ===========================================================================
+  # Resolves an external correlation id (e.g. Rails `request_id`) once per
+  # root execution. The value is stored on the Chain and surfaces on every
+  # Result (`result.xid`, `result.to_h[:xid]`) and Telemetry::Event (`event.xid`),
+  # so all tasks within the same request can be filtered together in logs.
+  #
+  # config.correlation_id = -> { Current.request_id }
+
+  # ===========================================================================
+  # Logging
+  # ===========================================================================
+  # In Rails, the Railtie already wires `config.logger = Rails.logger` and a
+  # backtrace cleaner — override here only if you need something different.
+  #
+  # Formatters: Line (default), Json, KeyValue, Logstash, Raw
+  #
+  # config.backtrace_cleaner = ->(bt) { Rails.backtrace_cleaner.clean(bt) }
+  # config.log_exclusions = [:context]
+  # config.log_formatter  = CMDx::LogFormatters::Line.new
+  # config.log_level      = Logger::INFO
+  # config.logger         = Logger.new($stdout, progname: "cmdx")
+
+  # ===========================================================================
+  # Middlewares
+  # ===========================================================================
+  # Wrap every task's execution. Must respond to `call(task) { ... }`.
+  #
+  # Example — run each task under the current user's locale:
+  #
+  # config.middlewares.register(proc do |task, &next_link|
+  #   locale = Current.user.locale || I18n.default_locale
+  #   I18n.with_locale(locale) do
+  #     task.metadata[:locale] = locale
+  #     next_link.call
+  #   end
+  # end)
+
+  # ===========================================================================
+  # Callbacks
+  # ===========================================================================
+  # Events:
+  #   :before_validation, :before_execution,
+  #   :on_complete, :on_interrupted,
+  #   :on_success, :on_skipped, :on_failed,
+  #   :on_ok, :on_ko
+  #
+  # config.callbacks.register(:on_failed, proc do |task|
+  #   Rails.logger.error("[cmdx] #{task.class.name} failed: #{task.metadata[:reason]}")
+  # end)
+
+  # ===========================================================================
+  # Telemetry
+  # ===========================================================================
+  # Events and payloads:
+  #   :task_started      payload: {}
+  #   :task_deprecated   payload: {}
+  #   :task_retried      payload: { attempt: Integer }
+  #   :task_rolled_back  payload: {}
+  #   :task_executed     payload: { result: CMDx::Result }
+  #
+  # Every event also carries: event.cid, event.xid, event.tid, event.task,
+  # event.type, event.root, event.timestamp.
+  #
+  # config.telemetry.subscribe(:task_executed, proc do |event|
+  #   StatsD.timing("cmdx.task", event.payload[:result].duration)
+  # end)
+
+  # ===========================================================================
+  # Coercions
+  # ===========================================================================
+  # Register custom type coercions. Callable receives `(value, **options)`.
+  #
+  # config.coercions.register(:currency, proc do |value, **|
+  #   BigDecimal(value.to_s.gsub(/[^\d.-]/, ""))
+  # end)
 
-  # Exception handler configuration - called when non-fault exceptions are raised
-  # https://github.com/drexed/cmdx/blob/main/docs/getting_started.md#exception-handler
-  # config.exception_handler = nil
+  # ===========================================================================
+  # Validators
+  # ===========================================================================
+  # Register custom validators. Callable receives `(value, options)` and
+  # returns a `CMDx::Validators::Failure.new(message)` on failure.
+  #
+  # config.validators.register(:uuid, proc do |value, _options|
+  #   unless value.to_s.match?(/\A[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/i)
+  #     CMDx::Validators::Failure.new("is not a valid UUID")
+  #   end
+  # end)
+
+  # ===========================================================================
+  # Executors
+  # ===========================================================================
+  # Registered executors drive `:parallel` workflow groups. Built-ins:
+  # `:threads` (default), `:fibers`. A callable receives
+  # `call(jobs:, concurrency:, on_job:)` and must invoke `on_job.call(job)`
+  # for each job, blocking until every job is done.
+  #
+  # config.executors.register(:ractors, proc do |jobs:, concurrency:, on_job:|
+  #   jobs.each_slice(concurrency) do |slice|
+  #     slice.map { |job| Ractor.new(job) { |j| on_job.call(j) } }.each(&:take)
+  #   end
+  # end)
 
-  # Additional global configurations - automatically applied to all tasks
+  # ===========================================================================
+  # Mergers
+  # ===========================================================================
+  # Merge strategies fold successful parallel task contexts back into the
+  # workflow context. Built-ins: `:last_write_wins` (default), `:deep_merge`,
+  # `:no_merge`. A callable receives `call(workflow_context, result)`.
   #
-  # Middlewares - https://github.com/drexed/cmdx/blob/main/docs/middlewares.md
-  # Callbacks - https://github.com/drexed/cmdx/blob/main/docs/callbacks.md
-  # Coercions - https://github.com/drexed/cmdx/blob/main/docs/coercions.md
-  # Validations - https://github.com/drexed/cmdx/blob/main/docs/validations.md
+  # config.mergers.register(:whitelist, proc do |workflow_context, result|
+  #   result.context.to_h.slice(:order_id, :total).each do |key, value|
+  #     workflow_context[key] = value
+  #   end
+  # end)
 end

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

@@ -3,7 +3,7 @@
 
     def work
       # Your logic here...
-      # Docs: https://github.com/drexed/cmdx
+      # Docs: https://drexed.github.io/cmdx/getting_started
     end
 
   end

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

@@ -2,7 +2,6 @@
   class <%= class_name %> < <%= parent_class_name %>
     include CMDx::Workflow
 
-    tasks Task1, Task2
-    # Docs: https://github.com/drexed/cmdx/docs/workflows.md
+    # Docs: https://drexed.github.io/cmdx/workflows
   end
 <% end -%>

data/lib/generators/cmdx/workflow_generator.rb

@@ -1,32 +1,23 @@
 # frozen_string_literal: true
 
 module Cmdx
-  # Generates CMDx workflow files for Rails applications
+  # Rails generator that scaffolds a new {CMDx::Workflow} subclass under
+  # `app/tasks`, honoring nested module paths supplied through the NAME
+  # argument (e.g. `Billing::Checkout` writes to
+  # `app/tasks/billing/checkout.rb`).
   #
-  # 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.
+  # Invoked via `rails generate cmdx:workflow NAME`.
+  #
+  # @see CMDx::Workflow
   class WorkflowGenerator < Rails::Generators::NamedBase
 
     source_root File.expand_path("templates", __dir__)
 
     desc "Creates a workflow with the given NAME"
 
-    # Copies the task template to the Rails application
-    #
-    # 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.
+    # Renders `workflow.rb.tt` into `app/tasks/<class_path>/<file_name>.rb`.
     #
     # @return [void]
-    #
-    # @example Basic usage
-    #   rails generate cmdx:workflow SendNotifications
-    #   # => Creates app/tasks/send_notifications.rb
-    #
-    # @example Nested task
-    #   rails generate cmdx:workflow Admin::SendNotifications
-    #   # => Creates app/tasks/admin/send_notifications.rb
     def copy_files
       path = File.join("app/tasks", class_path, "#{file_name}.rb")
       template("workflow.rb.tt", path)
@@ -34,19 +25,11 @@ module Cmdx
 
     private
 
-    # Determines the appropriate parent class name for the generated task
-    #
-    # 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 [Class] The parent class for the generated task
-    #
-    # @example
-    #   parent_class_name # => ApplicationTask
+    # Selects the parent class for the generated workflow: prefers the host
+    # application's `ApplicationTask` when defined, falling back to
+    # {CMDx::Task} otherwise. Consumed by the ERB template via `<%= %>`.
     #
-    # @example Fallback behavior
-    #   parent_class_name # => CMDx::Task
+    # @return [Class] either `ApplicationTask` or {CMDx::Task}
     def parent_class_name
       ApplicationTask
     rescue NameError

data/lib/locales/en.yml

@@ -1,17 +1,14 @@
 en:
   cmdx:
     attributes:
-      required: "must be accessible via the %{method} source method"
-      undefined: "delegates to undefined method %{method}"
+      required: "is required"
     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: %{types}"
-      unknown: "unknown %{type} coercion type"
-    faults:
-      invalid: "Invalid"
+    reasons:
       unspecified: "Unspecified"
-    returns:
+    outputs:
       missing: "must be set in the context"
     types:
       array: "array"
@@ -41,6 +38,9 @@ en:
         is_not: "length must not be %{is_not}"
         min: "length must be at least %{min}"
         max: "length must be at most %{max}"
+        gt: "length must be greater than %{gt}"
+        lt: "length must be less than %{lt}"
+        nil_value: "must have a length"
         not_within: "length must not be within %{min} and %{max}"
         within: "length must be within %{min} and %{max}"
       numeric:
@@ -48,6 +48,9 @@ en:
         is_not: "must not be %{is_not}"
         min: "must be at least %{min}"
         max: "must be at most %{max}"
+        gt: "must be greater than %{gt}"
+        lt: "must be less than %{lt}"
+        nil_value: "must be numeric"
         not_within: "must not be within %{min} and %{max}"
         within: "must be within %{min} and %{max}"
       presence: "cannot be empty"

data/mkdocs.yml

@@ -17,8 +17,8 @@ theme:
   icon:
     repo: fontawesome/brands/github
   font:
-    text: Inter
-    code: IBM Plex Mono
+    text: DM Sans
+    code: DM Mono
   palette:
     # Palette toggle for automatic mode
     - media: "(prefers-color-scheme)"
@@ -120,20 +120,21 @@ plugins:
           - basics/context.md: Context object for data sharing, input/output management, and attribute access
           - basics/chain.md: Execution chain tracking for related tasks within threads
         Interruptions:
-          - interruptions/halt.md: Intentional task interruption using skip! and fail! methods
-          - interruptions/faults.md: Fault exceptions (SkipFault, FailFault) raised by execute! with rich context
-          - interruptions/exceptions.md: Exception handling differences between execute and execute! methods
+          - interruptions/signals.md: Intentional task interruption using skip! and fail! methods
+          - interruptions/faults.md: CMDx::Fault raised by execute! with task class, signal, and cleaned backtrace
+          - interruptions/exceptions.md: Complete exception hierarchy (Error, DeprecationError, ImplementationError, MiddlewareError, Fault) and execute vs execute! semantics
         Outcomes:
           - outcomes/result.md: Result objects exposing execution state, status, context, and metadata
           - outcomes/states.md: Execution lifecycle states (initialized, executing, complete, interrupted)
           - outcomes/statuses.md: Business outcome statuses (success, skipped, failed) and transitions
+          - outcomes/errors.md: Structured per-attribute error container accumulated during input/output verification and exposed on result.errors
         Attributes:
-          - attributes/definitions.md: Attribute declarations (required/optional), validation, and type coercion
-          - attributes/naming.md: Customizing accessor method names with prefixes and suffixes
-          - attributes/coercions.md: Automatic type conversion for inputs (string to integer, date parsing, etc.)
-          - attributes/validations.md: Input validation rules (presence, length, format, numeric, inclusion, exclusion)
-          - attributes/defaults.md: Default values for optional attributes (static, dynamic, callable)
-          - attributes/transformations.md: Value transformation after coercion but before validation
+          - inputs/definitions.md: Attribute declarations (required/optional), validation, and type coercion
+          - inputs/naming.md: Customizing accessor method names with prefixes and suffixes
+          - inputs/coercions.md: Automatic type conversion for inputs (string to integer, date parsing, etc.)
+          - inputs/validations.md: Input validation rules (presence, length, format, numeric, inclusion, exclusion)
+          - inputs/defaults.md: Default values for optional inputs (static, dynamic, callable)
+          - inputs/transformations.md: Value transformation after coercion but before validation
         Features:
           - callbacks.md: Execution lifecycle callbacks (before_execution, on_success, on_failure, etc.)
           - middlewares.md: Cross-cutting concerns wrapping task execution (authentication, caching, timeouts)
@@ -141,13 +142,13 @@ plugins:
           - internationalization.md: Multi-language support for error messages and validations (90+ locales)
           - retries.md: Automatic retry functionality for transient failures with jitter and selective retries
           - deprecation.md: Managing deprecated tasks with logging, warnings, or execution prevention
-          - returns.md: Declaring expected context outputs that must be set after task execution
+          - outputs.md: Declaring expected context outputs that must be set after task execution
           - workflows.md: Composing multiple tasks into sequential pipelines with conditional execution
         More:
           - testing.md: Best practices for testing CMDx tasks and workflows with RSpec
-          - exceptions.md: Complete exception hierarchy and error type reference
           - tips_and_tricks.md: Best practices, patterns, and techniques for maintainable CMDx applications
           - comparison.md: Comparison with other command/service object frameworks
+          - v2-migration.md: Migration guide from CMDx 1.x to 2.0
 nav:
   - Home: index.md
   - Documentation:
@@ -159,20 +160,21 @@ nav:
       - Context: basics/context.md
       - Chain: basics/chain.md
     - Interruptions:
-      - Halt: interruptions/halt.md
+      - Signals: interruptions/signals.md
       - Faults: interruptions/faults.md
       - Exceptions: interruptions/exceptions.md
     - Outcomes:
       - Result: outcomes/result.md
       - States: outcomes/states.md
       - Statuses: outcomes/statuses.md
-    - Attributes:
-      - Definitions: attributes/definitions.md
-      - Naming: attributes/naming.md
-      - Coercions: attributes/coercions.md
-      - Validations: attributes/validations.md
-      - Defaults: attributes/defaults.md
-      - Transformations: attributes/transformations.md
+      - Errors: outcomes/errors.md
+    - Inputs:
+      - Definitions: inputs/definitions.md
+      - Naming: inputs/naming.md
+      - Coercions: inputs/coercions.md
+      - Validations: inputs/validations.md
+      - Defaults: inputs/defaults.md
+      - Transformations: inputs/transformations.md
     - Features:
       - Callbacks: callbacks.md
       - Middlewares: middlewares.md
@@ -180,13 +182,13 @@ nav:
       - Internationalization: internationalization.md
       - Retries: retries.md
       - Deprecation: deprecation.md
-      - Returns: returns.md
+      - Outputs: outputs.md
       - Workflows: workflows.md
     - More:
       - Testing: testing.md
-      - Exceptions: exceptions.md
       - Tips and Tricks: tips_and_tricks.md
       - Comparison: comparison.md
+      - v1 → v2 Migration: v2-migration.md
     - References:
       - API Documentation: https://drexed.github.io/cmdx/api/index.html
       - llms.txt: https://drexed.github.io/cmdx/llms.txt