cmdx 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15c3343ebbc1be1654e955561dacc79a9a27f398005bb6aa890e2167de87855a
-  data.tar.gz: 3c3e4f9d6e8d86f89e0bea6cf5573734345ea10608a7ea499f3c5ea00426d8a2
+  metadata.gz: 3bd1613d4572cca134192d5c80bf3016b278b42a9a002d13fba66d2871da92fb
+  data.tar.gz: 1a174bc8b62bf3402e1e464b8252cdcd589731f8e81141723b8dbf3cf97f9f1b
 SHA512:
-  metadata.gz: a9fbc22f9d725f8798fd4efbecab466ca5baaad04ba3a4ece97a1ed878d40813b315cfaab1d2173fd220241904c061aa7b3604e34d7fa2aaa719b48df7d723b9
-  data.tar.gz: 7b2b7532835041a91867d2f0fc7f83c092f247de39d4668b33301008d847af43d352e0c8bf0820911290176af48cf396f351e651a04b126e0aebec42f415a2e9
+  metadata.gz: df70552dbf814fddff62cb3e1d593edf6bf5c33087d84154f36c794d430ee156b986998651383fa15b3b08e4d14d198d69020bb0dec7a13ffab43c75b1c57b02
+  data.tar.gz: 03ad35b1f6007e1afa3c41f3b63d44784566e78b9eb9b7f25f301d81165753af14b06bb8a6cfd67ea7e5bce02a03c311c338f61538d9d981d7de58d7f2b36f8f

data/.cursor/prompts/rspec.md

@@ -0,0 +1,20 @@
+Add tests for the file in context.
+- Expectations should be concise, non-repetitive, and realistic (how it would be used in the real world)
+- Follow best practices and implementation
+- Update any pre-existing specs to match stated rules
+- New tests should be consistent with current `spec/cmdx` specs
+- Use custom matchers available within `lib/cmdx/rspec`
+- Use task helpers available within `spec/support/helpers`
+- Use stubs to return predefined values for specific methods. Isolate the unit being tested, but avoid over-mocking; test real behavior when possible. (mocks should be used only when necessary)
+- Ensure each test is independent; avoid shared state between tests.
+- Use let and let! to define test data, ensuring minimal and necessary setup.
+- Context block descriptions should start with the following words: `when`, `with`, `without`
+- Organize tests logically using describe for classes/modules and context for different scenarios.
+- Use subject to define the object under test when appropriate to avoid repetition.
+- Ensure test file paths mirror the structure of the files being tested, but within the spec directory (e.g., lib/cmdx/task.rb → spec/cmdx/task_spec.rb).
+- Use clear and descriptive names for describe, context, and it blocks.
+- Prefer the expect syntax for assertions to improve readability.
+- Keep test code concise; avoid unnecessary complexity or duplication.
+- Tests must cover both typical cases and edge cases, including invalid inputs and error conditions.
+- Consider all possible scenarios for each method or behavior and ensure they are tested.
+- Verify all specs are passing

data/.cursor/prompts/yardoc.md

@@ -0,0 +1,8 @@
+Add yardoc to the file in context.
+- Do NOT include `CMDx` module level docs
+- Module level docs description should NOT include `@example`
+- Method level docs should include `@example`, `@return`, `@raise`
+- Examples should be concise and realistic
+- Follow best practices and implementation
+- Update any pre-existing docs to match stated rules
+- New documentation should be consistent with current `lib/cmdx` documentation

data/.rubocop.yml

@@ -14,6 +14,9 @@ Layout/EmptyLinesAroundClassBody:
   EnforcedStyle: empty_lines_except_namespace
 Layout/EmptyLinesAroundModuleBody:
   EnforcedStyle: empty_lines_except_namespace
+Layout/ExtraSpacing:
+  Exclude:
+    - 'lib/generators/cmdx/templates/install.rb'
 Layout/LineLength:
   Enabled: false
 Lint/MissingSuper:
@@ -59,6 +62,8 @@ RSpec/SpecFilePathFormat:
     CMDx: cmdx
 RSpec/StubbedMock:
   Enabled: false
+RSpec/SubjectStub:
+  Enabled: false
 RSpec/VerifiedDoubles:
   Enabled: false
 RSpec/VerifiedDoubleReference:

data/CHANGELOG.md

@@ -1,79 +1,131 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [TODO]
+
+- Add table and pretty_table log formatters
+- Refactor all `docs`
+
 ## [Unreleased]
 
+### Added
+- Added `CoercionRegistry` class for managing parameter coercions with support for custom type registration
+- Added `ValidatorRegistry` class for managing parameter validators with support for custom validator registration
+- Added `CallbackRegistry` class to take uninstantiated callback classes
+- Added `Validator` and `Coercion` classes to build their respective handlers
+
+### Changed
+- Moved `Task::CALLBACKS` constant to `CallbackRegistry::TYPES`
+- Updated `ParameterRegistry` class to not inherit from `Hash`
+- Updated `MiddlewareRegistry` class to not inherit from `Hash`
+- Updated `CallbackRegistry` class to not inherit from `Hash`
+
+### Removed
+- Removed task `register` class method
+- Removed `Custom` validator since users can create and register a custom one
+
+## [1.0.1] - 2025-07-07
+
+### Added
+- Added comprehensive internationalization support with 24 language locales
+  - Arabic, Chinese, Czech, Danish, Dutch, English, Finnish, French, German, Greek
+  - Hebrew, Hindi, Italian, Japanese, Korean, Norwegian, Polish, Portuguese
+  - Russian, Spanish, Swedish, Thai, Turkish, Vietnamese
+- Added TLDR sections to documentation for improved accessibility
+
+### Changed
+- Improved configuration template with better defaults and examples
+
 ## [1.0.0] - 2025-07-03
 
 ### Added
-- Zeitwerk gem loader
-- Add middleware support for tasks
-- Add Cursor and Copilot rules
-- Add YARDoc documentation
-- Add `perform!` and `perform` alias to class `call!` and `call`
-- Allow direct instantiation of Task and Batch objects
-- Add pattern matching of results
-- Add a `Hook` class
-- Add hooks via configuration
+- Added `Hook` class for flexible callback management
+- Added `perform!` and `perform` method aliases for class-level `call!` and `call` methods
+- Added comprehensive YARDoc documentation throughout codebase
+- Added configuration-based hook registration system
+- Added Cursor and GitHub Copilot configuration files for enhanced IDE support
+- Added middleware support for tasks enabling extensible request/response processing
+- Added pattern matching support for result objects
+- Added support for direct instantiation of Task and Workflow objects
+- Added Zeitwerk-based gem loading for improved performance and reliability
+
 ### Changed
-- Changed configuration to be a PORO class
-- Changed ArgumentError to TypeError where checking `is_a?`
-- Improve documentation readability, consistency, completeness
-- Improve test readability, consistency, completeness
-- Renames `Parameters` to `ParameterRegistry`
-- Convert hooks hash to a registry
-- Rename `Run` and its associated items to `Chain`
-- Convert `Chain` to use threads instead of passing context
-- Immutator now uses a `SKIP_CMDX_FREEZING` env var instead of `RACK_ENV` or `RAILS_ENV`
-- Rename `Hook` to `Callback`
-- Rename `Batch` to `Workflow`
+- Changed `ArgumentError` to `TypeError` for type validation consistency
+- Changed configuration from hash-based to PORO (Plain Old Ruby Object) class structure
+- Improved documentation readability, consistency, and completeness
+- Improved test suite readability, consistency, and coverage
+- Renamed `Batch` to `Workflow` to better reflect functionality
+- Renamed `Hook` to `Callback` for naming consistency
+- Renamed `Parameters` to `ParameterRegistry` for clarity
+- Renamed `Run` and associated components to `Chain` for better semantic meaning
+- Updated `Chain` to use thread-based execution instead of context passing
+- Updated `Immutator` to use `SKIP_CMDX_FREEZING` environment variable instead of `RACK_ENV`/`RAILS_ENV`
+- Updated hooks from a hash structure to registry pattern
+
 ### Removed
-- Removed configuration `task_timeout` and `batch_timeout`
+- Removed deprecated `task_timeout` and `batch_timeout` configuration settings
 
 ## [0.5.0] - 2025-03-21
 
 ### Added
-- Add `to_a` alias on array of hashes serializers
-- Add `state`, `status`, `outcome`, and `runtime` to run serializer
-- Add `on_[state]` and `on_[status]` based result callback handlers
-- Add `on_executed` state task hook
-- Add `on_good` and `on_bad` status task hook
+- Added `on_[state]` and `on_[status]` based result callback handlers
+- Added `on_executed` state hook for task completion tracking
+- Added `on_good` and `on_bad` status hooks for success/failure handling
+- Added `state`, `status`, `outcome`, and `runtime` fields to run serializer
+- Added `to_a` alias for array of hashes serializers
+
 ### Changed
-- Changed status and state hook order
+- Reordered status and state hook execution for more predictable behavior
 
 ## [0.4.0] - 2025-03-17
 
 ### Added
-- Add ANSI util
-- Add string to json parsing in hash coercion
-- Add string to json parsing in array coercion
+- Added ANSI color utility for enhanced terminal output
+- Added JSON string parsing support in array coercion
+- Added JSON string parsing support in hash coercion
+
 ### Changed
-- Skip assigning log settings if logger is nil
-- Improve ANSI escape sequence
-- Improve run inspector output
+- Improved ANSI escape sequence handling
+- Improved run inspector output formatting
+
+### Fixed
+- Fixed log settings assignment when logger is nil to prevent errors
 
 ## [0.3.0] - 2025-03-14
 
 ### Added
-- Add `progname` to logger instances
-- Add `LoggerSerializer` to standardize log output
+- Added `LoggerSerializer` for standardized log output formatting
+- Added `progname` support for logger instances
+
 ### Changed
-- Revert default log formatter to `Line`
-- Removed `pid` from result serializer
-- Fix serialization of frozen run
-- Fix `call!` not marking state of failure as interrupted
+- Removed `pid` (process ID) from result serializer output
+- Reverted default log formatter from `PrettyLine` back to `Line`
+
+### Fixed
+- Fixed `call!` method not properly marking failure state as interrupted
+- Fixed serialization issues with frozen run objects
 
 ## [0.2.0] - 2025-03-12
 
 ### Added
-- Add `PrettyJson` log formatter
-- Add `PrettyKeyValue` log formatter
-- Add `PrettyLine` log formatter
+- Added `PrettyJson` log formatter for structured JSON output
+- Added `PrettyKeyValue` log formatter for key-value pair output
+- Added `PrettyLine` log formatter for enhanced line-based output
+
 ### Changed
-- Make `PrettyLine` the default log formatter
-- Rename `MethodName` util to `NameAffix`
-- Rename `DatetimeFormatter` util to `LogTimestamp`
-- Rename `Runtime` util to `MonotonicRuntime`
-- Fix logging non hash values from raising an error
-- Fix bubbling of faults with nested halted calls
-- Wrap result logger in a `Logger#with_logger` block
+- Renamed `DatetimeFormatter` utility to `LogTimestamp` for better clarity
+- Renamed `MethodName` utility to `NameAffix` for better clarity
+- Renamed `Runtime` utility to `MonotonicRuntime` for better clarity
+- Updated `PrettyLine` to be the default log formatter
+- Updated result logger to be wrapped in `Logger#with_logger` block for better context
+
+### Fixed
+- Fixed error when logging non-hash values
+- Fixed fault bubbling behavior with nested halted calls
 
 ## [0.1.0] - 2025-03-07
 

data/README.md

@@ -31,7 +31,7 @@ Or install it yourself as:
 ```ruby
 # Setup task
 class SendWelcomeEmailTask < CMDx::Task
-  use CMDx::Middlewares::Timeout, seconds: 5
+  use :middleware, CMDx::Middlewares::Timeout, seconds: 5
 
   on_success :track_email_delivery!
 
@@ -100,6 +100,7 @@ end
 - [Middlewares](docs/middlewares.md)
 - [Workflows](docs/workflows.md)
 - [Logging](docs/logging.md)
+- [Internationalization (i18n)](docs/internationalization.md)
 - [Testing](docs/testing.md)
 - [AI Prompts](docs/ai_prompts.md)
 - [Tips & Tricks](docs/tips_and_tricks.md)

data/docs/ai_prompts.md

@@ -4,12 +4,22 @@ This guide provides AI prompt templates for building CMDx Task and Workflow obje
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Framework Context Template](#framework-context-template)
 - [Task Generation Templates](#task-generation-templates)
 - [Workflow Generation Templates](#workflow-generation-templates)
 - [Testing Templates](#testing-templates)
 - [Best Practices for AI Prompts](#best-practices-for-ai-prompts)
 
+## TLDR
+
+- **Purpose** - Pre-written prompts to help AI assistants generate production-ready CMDx code
+- **Templates** - Framework context, task generation, workflow generation, and testing templates
+- **Framework context** - Essential CMDx concepts and coding standards for AI understanding
+- **Task templates** - Structured prompts for generating tasks with parameters, validations, and tests
+- **Workflow templates** - Prompts for orchestrating multi-step business processes
+- **Testing templates** - Comprehensive RSpec test generation with CMDx matchers
+
 ## Framework Context Template
 
 Use this context in your AI conversations to ensure proper CMDx code generation:

data/docs/basics/call.md

@@ -4,6 +4,7 @@ Calling a task executes the business logic within it. Tasks provide two executio
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Execution Methods Overview](#execution-methods-overview)
 - [Non-bang Call (`call`)](#non-bang-call-call)
 - [Bang Call (`call!`)](#bang-call-call)
@@ -14,6 +15,14 @@ Calling a task executes the business logic within it. Tasks provide two executio
 - [Task State Lifecycle](#task-state-lifecycle)
 - [Return Value Details](#return-value-details)
 
+## TLDR
+
+- **`call`** - Always returns `CMDx::Result`, never raises exceptions (preferred)
+- **`call!`** - Returns `CMDx::Result` on success, raises `CMDx::Fault` on failure/skip
+- **Results** - Check status with `result.success?`, `result.failed?`, `result.skipped?`
+- **Callbacks** - Chain results with `.on_success`, `.on_failed`, `.on_skipped`
+- **Propagation** - Use `throw!(other_result)` to bubble up failures from subtasks
+
 ## Execution Methods Overview
 
 | Method | Returns | Exceptions | Use Case |
@@ -94,7 +103,7 @@ task.context.notify_customer #=> true
 task.result.state            #=> "initialized"
 
 # Manual execution
-task.perform
+task.process
 task.result.success?         #=> true/false
 ```
 
@@ -104,7 +113,7 @@ task.result.success?         #=> true/false
 |----------|----------|----------|
 | `TaskClass.call(...)` | Standard execution | Simple, handles full lifecycle |
 | `TaskClass.call!(...)` | Exception-based flow | Automatic fault raising |
-| `TaskClass.new(...).perform` | Advanced scenarios | Full control, testing flexibility |
+| `TaskClass.new(...).process` | Advanced scenarios | Full control, testing flexibility |
 
 > [!NOTE]
 > Direct instantiation gives you access to the task instance before and after execution, but you must call the execution method manually.

data/docs/basics/chain.md

@@ -4,6 +4,7 @@ A chain represents a collection of related task executions that share a common e
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Thread-Local Chain Management](#thread-local-chain-management)
 - [Automatic Chain Creation](#automatic-chain-creation)
 - [Chain Inheritance](#chain-inheritance)
@@ -12,6 +13,14 @@ A chain represents a collection of related task executions that share a common e
 - [State Delegation](#state-delegation)
 - [Serialization and Logging](#serialization-and-logging)
 
+## TLDR
+
+- **Chains** - Automatically group related task executions within the same thread
+- **Thread-local** - Each thread gets its own chain, no manual coordination needed
+- **Inheritance** - Subtasks automatically join the current thread's chain
+- **Correlation** - Chain IDs serve as correlation identifiers for tracing
+- **Access** - Use `result.chain.id` and `result.chain.results` to inspect execution trails
+
 ## Thread-Local Chain Management
 
 Chains use thread-local storage to automatically group related task executions within the same thread while maintaining isolation across different threads:
@@ -186,7 +195,7 @@ The `CMDx::Middlewares::Correlate` middleware automatically manages correlation
 ```ruby
 class ProcessOrderTask < CMDx::Task
   # Apply correlate middleware globally or per-task
-  use CMDx::Middlewares::Correlate
+  use :middleware, CMDx::Middlewares::Correlate
 
   def call
     # Correlation is automatically managed

data/docs/basics/context.md

@@ -6,6 +6,7 @@ validation, and seamless data flow between related tasks.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Loading Parameters](#loading-parameters)
 - [Accessing Data](#accessing-data)
 - [Modifying Context](#modifying-context)
@@ -14,6 +15,14 @@ validation, and seamless data flow between related tasks.
 - [Result Object Context Passing](#result-object-context-passing)
 - [Context Inspection](#context-inspection)
 
+## TLDR
+
+- **Dynamic attributes** - Access data with `context.user_id` or `context[:user_id]`
+- **Automatic loading** - Parameters become context attributes automatically
+- **Modification** - Assign data with `context.user = User.find(id)`
+- **Sharing** - Pass context between tasks with `SomeTask.call(context)`
+- **Nil safety** - Missing attributes return `nil` instead of raising errors
+
 ## Loading Parameters
 
 Context is automatically populated when calling tasks with parameters. All

data/docs/basics/setup.md

@@ -7,12 +7,21 @@ only a `call` method is required to create a functional task.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Basic Task Structure](#basic-task-structure)
 - [Task Execution](#task-execution)
 - [Inheritance and Application Tasks](#inheritance-and-application-tasks)
 - [Generator](#generator)
 - [Task Lifecycle](#task-lifecycle)
 
+## TLDR
+
+- **Tasks** - Ruby classes that inherit from `CMDx::Task` with a `call` method
+- **Structure** - Only `call` method required, everything else is optional
+- **Execution** - Run with `MyTask.call(params)` to get a `CMDx::Result`
+- **Generator** - Use `rails g cmdx:task MyTask` to create task templates
+- **Single-use** - Tasks are frozen after execution, create new instances for each run
+
 ## Basic Task Structure
 
 ```ruby

data/docs/callbacks.md

@@ -6,6 +6,7 @@ as the `call` method, enabling rich integration patterns.
 
 ## Table of Contents
 
+- [TLDR](#tldr)
 - [Overview](#overview)
 - [Callback Declaration](#callback-declaration)
 - [Callback Classes](#callback-classes)
@@ -19,10 +20,19 @@ as the `call` method, enabling rich integration patterns.
 - [Conditional Execution](#conditional-execution)
 - [Callback Inheritance](#callback-inheritance)
 
+## TLDR
+
+- **Purpose** - Execute custom logic at specific points in task lifecycle
+- **Declaration** - Use method names, procs, class instances, or blocks
+- **Callback types** - Validation, execution, state, status, and outcome callbacks
+- **Execution order** - Runs in precise lifecycle order (before_execution → validation → call → status → after_execution)
+- **Conditional** - Support `:if` and `:unless` options for conditional execution
+- **Inheritance** - Callbacks are inherited, perfect for global patterns
+
 > [!TIP]
 > Callbacks are inheritable, making them perfect for setting up global logic execution patterns like tracking markers, account plan checks, or logging standards.
 
-## Callback Declaration
+## Overview
 
 Callbacks can be declared in multiple ways: method names, procs/lambdas, Callback class instances, or blocks.
 
@@ -69,9 +79,7 @@ end
 
 ## Callback Classes
 
-For complex callback logic or reusable patterns, you can create Callback classes similar to Middleware classes. Callback classes inherit from `CMDx::Callback` and implement the `call(task, callback_type)` method.
-
-### Creating Callback Classes
+For complex callback logic or reusable patterns, you can create Callback classes similar to Middleware classes. Callback classes inherit from `CMDx::Callback` and implement the `call(task, type)` method.
 
 ```ruby
 class NotificationCallback < CMDx::Callback
@@ -79,8 +87,8 @@ class NotificationCallback < CMDx::Callback
     @channels = Array(channels)
   end
 
-  def call(task, callback_type)
-    return unless callback_type == :on_success
+  def call(task, type)
+    return unless type == :on_success
 
     @channels.each do |channel|
       NotificationService.send(channel, "Task #{task.class.name} completed")
@@ -89,37 +97,6 @@ class NotificationCallback < CMDx::Callback
 end
 ```
 
-### Registering Callback Classes
-
-Callback classes can be registered using the `register` class method (recommended) or by directly calling the CallbackRegistry:
-
-```ruby
-class ProcessOrderTask < CMDx::Task
-  # Recommended: Use the register class method
-  register :before_execution, LoggingCallback.new(:debug)
-  register :on_success, NotificationCallback.new([:email, :slack])
-  register :on_failure, :alert_admin, if: :critical?
-
-  # Alternative: Direct CallbackRegistry access (less common)
-  # cmd_callbacks.register(:after_execution, CleanupCallback.new)
-
-  # Traditional callback definitions still work alongside Callback classes
-  before_validation :validate_order_data
-  on_success :update_metrics
-
-  def call
-    context.order = Order.find(order_id)
-    context.order.process!
-  end
-
-  private
-
-  def critical?
-    context.order.value > 10_000
-  end
-end
-```
-
 ## Available Callbacks
 
 ### Validation Callbacks