cmdx 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00e2b2067ace8ed3afdb75bc07e3f3c5ec3ed40233a63cc3a9abc495c3a3199c
-  data.tar.gz: 053c7a3a6e3c70808b4dba6d916a35419ee0c858145dbace0d83d89e0583d05a
+  metadata.gz: 15c3343ebbc1be1654e955561dacc79a9a27f398005bb6aa890e2167de87855a
+  data.tar.gz: 3c3e4f9d6e8d86f89e0bea6cf5573734345ea10608a7ea499f3c5ea00426d8a2
 SHA512:
-  metadata.gz: 2de61e9b7e43d9e1187b4c6c925c930ae55163a5075ac624f4a9c29595588b10aacd007d64654397dc458a9c704d9175dd884eadafbef614bb8f01182f022cf0
-  data.tar.gz: 52dcb48c2e9538d33fea460946fde8f25814127aa490895fc4a676f865423d0b915ad1e7c5daae88ebe46e4bff01a36f850fa704bff312fa938ed5e3a7ea879a
+  metadata.gz: a9fbc22f9d725f8798fd4efbecab466ca5baaad04ba3a4ece97a1ed878d40813b315cfaab1d2173fd220241904c061aa7b3604e34d7fa2aaa719b48df7d723b9
+  data.tar.gz: 7b2b7532835041a91867d2f0fc7f83c092f247de39d4668b33301008d847af43d352e0c8bf0820911290176af48cf396f351e651a04b126e0aebec42f415a2e9

data/.cursor/rules/cursor-instructions.mdc

@@ -0,0 +1,6 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+Use instructions found in [copilot-instructions.md](mdc:.github/copilot-instructions.md)

data/.rubocop.yml

@@ -6,7 +6,6 @@ AllCops:
   NewCops: enable
   DisplayCopNames: true
   DisplayStyleGuide: true
-  TargetRubyVersion: 3.1.0
 Gemspec/DevelopmentDependencies:
   EnforcedStyle: gemspec
 Layout/EmptyLinesAroundAttributeAccessor:
@@ -17,10 +16,15 @@ Layout/EmptyLinesAroundModuleBody:
   EnforcedStyle: empty_lines_except_namespace
 Layout/LineLength:
   Enabled: false
+Lint/MissingSuper:
+  Exclude:
+    - 'lib/cmdx/middlewares/**/*'
+    - 'spec/**/**/*'
 Metrics/AbcSize:
   Enabled: false
 Metrics/BlockLength:
   Exclude:
+    - 'lib/cmdx/rspec/**/*'
     - 'spec/**/**/*'
     - '*.gemspec'
 Metrics/ClassLength:
@@ -37,8 +41,15 @@ Naming/MethodParameterName:
   Enabled: false
 RSpec/AnyInstance:
   Enabled: false
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/integrations/**/*'
 RSpec/ExampleLength:
   Enabled: false
+RSpec/MessageSpies:
+  Enabled: false
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
 RSpec/MultipleExpectations:
   Enabled: false
 RSpec/NestedGroups:
@@ -46,6 +57,10 @@ RSpec/NestedGroups:
 RSpec/SpecFilePathFormat:
   CustomTransform:
     CMDx: cmdx
+RSpec/StubbedMock:
+  Enabled: false
+RSpec/VerifiedDoubles:
+  Enabled: false
 RSpec/VerifiedDoubleReference:
   Enabled: false
 Style/Documentation:

data/.ruby-version

@@ -1 +1 @@
-3.4.2
+3.4.4

data/CHANGELOG.md

@@ -1,9 +1,47 @@
 ## [Unreleased]
 
+## [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
+### 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`
+### Removed
+- Removed configuration `task_timeout` and `batch_timeout`
+
+## [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
+### Changed
+- Changed status and state hook order
+
 ## [0.4.0] - 2025-03-17
 
 ### Added
-- Add ansi util
+- Add ANSI util
 - Add string to json parsing in hash coercion
 - Add string to json parsing in array coercion
 ### Changed
@@ -12,6 +50,7 @@
 - Improve run inspector output
 
 ## [0.3.0] - 2025-03-14
+
 ### Added
 - Add `progname` to logger instances
 - Add `LoggerSerializer` to standardize log output
@@ -22,6 +61,7 @@
 - Fix `call!` not marking state of failure as interrupted
 
 ## [0.2.0] - 2025-03-12
+
 ### Added
 - Add `PrettyJson` log formatter
 - Add `PrettyKeyValue` log formatter
@@ -36,5 +76,6 @@
 - Wrap result logger in a `Logger#with_logger` block
 
 ## [0.1.0] - 2025-03-07
+
 ### Added
 - Initial release

data/README.md

@@ -6,9 +6,7 @@
 [![CI](https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg)](https://github.com/drexed/cmdx/actions/workflows/ci.yml)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=shields)](http://makeapullrequest.com)
 
-`CMDx` is a framework for expressive processing of business logic. Design
-code of varying levels of complexity that is built through branching and
-composition, informative halting, and exhaustive tracing/debugging.
+`CMDx` is a Ruby framework for building maintainable, observable business logic through composable command objects. Design robust workflows with automatic parameter validation, structured error handling, comprehensive logging, and intelligent execution flow control that scales from simple tasks to complex multi-step processes.
 
 ## Installation
 
@@ -28,34 +26,83 @@ Or install it yourself as:
 
     $ gem install cmdx
 
+## Quick Example
+
+```ruby
+# Setup task
+class SendWelcomeEmailTask < CMDx::Task
+  use CMDx::Middlewares::Timeout, seconds: 5
+
+  on_success :track_email_delivery!
+
+  required :user_id, type: :integer, numeric: { min: 1 }
+  optional :template, type: :string, default: "welcome"
+
+  def call
+    if user.nil?
+      fail!(reason: "User not found", code: 404)
+    elsif user.unconfirmed?
+      skip!(reason: "Email not verified")
+    else
+      response = UserMailer.welcome(user, template).deliver_now
+      context.message_id = response.message_id
+    end
+  end
+
+  private
+
+  def user
+    @user ||= User.find_by(id: user_id)
+  end
+
+  def track_email_delivery!
+    user.touch(:welcomed_at)
+  end
+end
+
+# Execute task
+result = SendWelcomeEmailTask.call(user_id: 123, template: "premium_welcome")
+
+# Handle result
+if result.success?
+  puts "Welcome email sent <message_id: #{result.context.message_id}>"
+elsif result.skipped?
+  puts "Skipped: #{result.metadata[:reason]}"
+elsif result.failed?
+  puts "Failed: #{result.metadata[:reason]} with code: #{result.metadata[:code]}"
+end
+```
+
 ## Table of contents
 
-- [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md)
-- [Configuration](https://github.com/drexed/cmdx/blob/main/docs/configuration.md)
+- [Getting Started](docs/getting_started.md)
+- [Configuration](docs/configuration.md)
 - Basics
-  - [Setup](https://github.com/drexed/cmdx/blob/main/docs/basics/setup.md)
-  - [Call](https://github.com/drexed/cmdx/blob/main/docs/basics/call.md)
-  - [Context](https://github.com/drexed/cmdx/blob/main/docs/basics/context.md)
-  - [Run](https://github.com/drexed/cmdx/blob/main/docs/basics/run.md)
+  - [Setup](docs/basics/setup.md)
+  - [Call](docs/basics/call.md)
+  - [Context](docs/basics/context.md)
+  - [Chain](docs/basics/chain.md)
 - Interruptions
-  - [Halt](https://github.com/drexed/cmdx/blob/main/docs/interruptions/halt.md)
-  - [Faults](https://github.com/drexed/cmdx/blob/main/docs/interruptions/faults.md)
-  - [Exceptions](https://github.com/drexed/cmdx/blob/main/docs/interruptions/exceptions.md)
+  - [Halt](docs/interruptions/halt.md)
+  - [Faults](docs/interruptions/faults.md)
+  - [Exceptions](docs/interruptions/exceptions.md)
 - Parameters
-  - [Definitions](https://github.com/drexed/cmdx/blob/main/docs/parameters/definitions.md)
-  - [Namespacing](https://github.com/drexed/cmdx/blob/main/docs/parameters/namespacing.md)
-  - [Coercions](https://github.com/drexed/cmdx/blob/main/docs/parameters/coercions.md)
-  - [Validations](https://github.com/drexed/cmdx/blob/main/docs/parameters/validations.md)
-  - [Defaults](https://github.com/drexed/cmdx/blob/main/docs/parameters/defaults.md)
+  - [Definitions](docs/parameters/definitions.md)
+  - [Namespacing](docs/parameters/namespacing.md)
+  - [Coercions](docs/parameters/coercions.md)
+  - [Validations](docs/parameters/validations.md)
+  - [Defaults](docs/parameters/defaults.md)
 - Outcomes
   - [Result](#results)
-  - [States](https://github.com/drexed/cmdx/blob/main/docs/outcomes/states.md)
-  - [Statuses](https://github.com/drexed/cmdx/blob/main/docs/outcomes/statuses.md)
-- [Hooks](https://github.com/drexed/cmdx/blob/main/docs/hooks.md)
-- [Batch](https://github.com/drexed/cmdx/blob/main/docs/batch.md)
-- [Logging](https://github.com/drexed/cmdx/blob/main/docs/logging.md)
-- [Tips & Tricks](https://github.com/drexed/cmdx/blob/main/docs/tips_and_tricks.md)
-- [Example](https://github.com/drexed/cmdx/blob/main/docs/example.md)
+  - [States](docs/outcomes/states.md)
+  - [Statuses](docs/outcomes/statuses.md)
+- [Callbacks](docs/callbacks.md)
+- [Middlewares](docs/middlewares.md)
+- [Workflows](docs/workflows.md)
+- [Logging](docs/logging.md)
+- [Testing](docs/testing.md)
+- [AI Prompts](docs/ai_prompts.md)
+- [Tips & Tricks](docs/tips_and_tricks.md)
 
 ## Development
 
@@ -73,4 +120,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the CMDx project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/drexed/cmdx/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the CMDx project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).

data/docs/ai_prompts.md

@@ -0,0 +1,309 @@
+# AI Prompt Templates
+
+This guide provides AI prompt templates for building CMDx Task and Workflow objects, helping you leverage AI assistants to generate well-structured, production-ready command objects.
+
+## Table of Contents
+
+- [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)
+
+## Framework Context Template
+
+Use this context in your AI conversations to ensure proper CMDx code generation:
+
+```
+I'm working with CMDx, a Ruby framework for designing and executing business logic within service/command objects.
+
+KEY FRAMEWORK CONCEPTS:
+- Tasks inherit from CMDx::Task and implement business logic in a `call` method
+- Workflows inherit from CMDx::Workflow and orchestrate multiple tasks
+- Parameters are defined with type coercion, validation, and defaults
+- Results contain status (success/failed/skipped), state, context, and metadata
+- Callbacks execute at specific lifecycle points (before_validation, on_success, etc.)
+- Middlewares wrap task execution (authentication, logging, timeouts)
+- Chains link multiple tasks together with shared context
+
+CODING STANDARDS:
+- Use Ruby 3.4+ syntax and conventions
+- Follow snake_case for methods/variables, CamelCase for classes
+- Use double quotes for strings
+- Include comprehensive YARD documentation
+- Write RSpec tests with CMDx custom matchers
+- Name tasks as VerbNounTask (e.g., ProcessOrderTask)
+- Name workflows as NounVerbWorkflow (e.g., OrderProcessingWorkflow)
+
+Generate code that is production-ready with proper error handling, validation, and testing.
+```
+
+## Task Generation Templates
+
+```
+Create a CMDx task that [SPECIFIC_ACTION] with the following requirements:
+
+PARAMETERS:
+- [parameter_name]: [type] - [description] - [required/optional]
+- [parameter_name]: [type] - [description] - [validation_rules]
+
+BUSINESS LOGIC:
+- [Step 1 description]
+- [Step 2 description]
+- [Error conditions to handle]
+
+CONTEXT UPDATES:
+- [What data should be added to context]
+- [What side effects should occur]
+
+TESTING:
+- Generate comprehensive RSpec tests using CMDx matchers
+- Include success, failure, and edge case scenarios
+- Test parameter validation and context updates
+
+Please include:
+- Proper parameter definitions with validations
+- Error handling and metadata
+- YARD documentation
+- RSpec test file
+```
+
+**Example Usage:**
+```
+Create a CMDx task that processes user email preferences with the following requirements:
+
+PARAMETERS:
+- user_id: integer - ID of the user - required, positive
+- email_types: array - Types of emails to enable - required, inclusion in ['marketing', 'notifications', 'alerts']
+- enabled: boolean - Whether to enable or disable - optional, defaults to true
+
+BUSINESS LOGIC:
+- Validate user exists and is active
+- Update user's email preferences in database
+- Send confirmation email if preferences changed
+- Log preference changes for audit trail
+
+CONTEXT UPDATES:
+- Add updated user object to context
+- Add preference_changes hash with before/after values
+- Add confirmation_sent boolean
+
+TESTING:
+- Generate comprehensive RSpec tests using CMDx matchers
+- Include success, failure, and edge case scenarios
+- Test parameter validation and context updates
+```
+
+## Workflow Generation Templates
+
+```
+Create a CMDx workflow that orchestrates [BUSINESS_PROCESS] with the following requirements:
+
+WORKFLOW STEPS:
+1. [Task 1]: [Description and purpose]
+2. [Task 2]: [Description and purpose]
+3. [Task 3]: [Description and purpose]
+
+TASK DEPENDENCIES:
+- [How tasks share data through context]
+- [Which tasks can run in parallel]
+- [Sequential requirements]
+
+ERROR HANDLING:
+- [How to handle individual task failures]
+- [Rollback requirements]
+- [Compensation logic]
+
+CONDITIONAL LOGIC:
+- [When to skip certain tasks]
+- [Branching based on context]
+
+TESTING:
+- Generate workflow integration tests
+- Test success path and various failure scenarios
+- Include individual task unit tests
+```
+
+**Example Usage:**
+```
+Create a CMDx workflow that orchestrates user onboarding with the following requirements:
+
+WORKFLOW STEPS:
+1. ValidateUserDataTask: Validate and sanitize user registration data
+2. CreateUserAccountTask: Create user account in database
+3. SendWelcomeEmailTask: Send personalized welcome email
+4. SetupDefaultPreferencesTask: Configure default user preferences
+5. TrackOnboardingEventTask: Log onboarding completion for analytics
+
+TASK DEPENDENCIES:
+- All tasks run sequentially
+- User data flows through context from validation to account creation
+- Welcome email uses created user object
+- Preferences setup requires user ID
+- Analytics tracking happens last with full context
+
+ERROR HANDLING:
+- If account creation fails, don't send email or setup preferences
+- If email fails, continue with preferences but log the failure
+- If preferences fail, still complete onboarding but flag for followup
+
+CONDITIONAL LOGIC:
+- Skip welcome email if user opted out during registration
+- Skip analytics if user has privacy settings enabled
+
+TESTING:
+- Generate workflow integration tests
+- Test success path and various failure scenarios
+- Include individual task unit tests
+```
+
+## Testing Templates
+
+### Task Testing Template
+
+```
+Generate comprehensive RSpec tests for [TASK_NAME] including:
+
+PARAMETER VALIDATION TESTS:
+- Test all required parameters
+- Test type coercion and validation rules
+- Test default values
+- Test invalid parameter combinations
+
+EXECUTION TESTS:
+- Test successful execution with various inputs
+- Test all error conditions and edge cases
+- Test context updates and side effects
+- Test metadata and timing information
+
+INTEGRATION TESTS:
+- Test external service interactions
+- Test database operations
+- Test file system operations (if applicable)
+
+CALLBACK TESTS:
+- Test lifecycle callbacks execute correctly
+- Test callback order and context
+
+Use CMDx custom matchers like:
+- expect(result).to be_successful_task
+- expect(result).to be_failed_task
+- expect(TaskClass).to handle_exceptions_gracefully
+```
+
+### Workflow Testing Template
+
+```
+Generate comprehensive RSpec tests for [WORKFLOW_NAME] including:
+
+INTEGRATION TESTS:
+- Test complete workflow execution
+- Test various success scenarios
+- Test different failure points
+- Test context flow between tasks
+
+INDIVIDUAL TASK TESTS:
+- Test each task in isolation
+- Test task parameter validation
+- Test task-specific logic
+
+CONDITIONAL LOGIC TESTS:
+- Test all branching paths
+- Test edge cases in decision logic
+- Test context preservation across branches
+
+ERROR HANDLING TESTS:
+- Test failure propagation
+- Test recovery mechanisms
+- Test compensation logic
+```
+
+## Best Practices for AI Prompts
+
+### 1. Be Specific About Requirements
+
+**Good:**
+```
+Create a task that validates credit card information, including:
+- Card number validation with Luhn algorithm
+- Expiry date validation (not expired, reasonable future date)
+- CVV validation (3-4 digits depending on card type)
+- Cardholder name validation (2-50 characters, letters and spaces only)
+```
+
+**Avoid:**
+```
+Create a task that validates credit cards
+```
+
+### 2. Include Context About Data Flow
+
+**Good:**
+```
+The task should receive user_id and payment_amount, validate the payment method,
+charge the card, and update the context with:
+- transaction_id
+- charged_amount
+- payment_method_last_four
+- charge_timestamp
+```
+
+**Avoid:**
+```
+Process a payment
+```
+
+### 3. Specify Error Conditions
+
+**Good:**
+```
+Handle these error conditions:
+- Invalid card number → failed result with metadata { error_code: 'INVALID_CARD' }
+- Expired card → failed result with metadata { error_code: 'EXPIRED_CARD' }
+- Insufficient funds → failed result with metadata { error_code: 'DECLINED', retryable: false }
+- Network timeout → failed result with metadata { error_code: 'TIMEOUT', retryable: true }
+```
+
+**Avoid:**
+```
+Handle payment errors
+```
+
+### 4. Request Complete Examples
+
+**Good:**
+```
+Generate a complete working example including:
+- Task class with full implementation
+- Parameter definitions with validations
+- RSpec test file with success/failure scenarios
+- YARD documentation
+- Usage examples in comments
+```
+
+**Avoid:**
+```
+Show me the basic structure
+```
+
+### 5. Specify Framework Patterns
+
+**Good:**
+```
+Follow CMDx patterns:
+- Use present tense verbs in task names (ProcessPaymentTask, not ProcessingPaymentTask)
+- Include proper error handling with metadata
+- Use callbacks for audit logging
+- Return detailed context updates
+- Include comprehensive parameter validation
+```
+
+**Avoid:**
+```
+Use best practices
+```
+
+---
+
+- **Prev:** [Testing](testing.md)
+- **Next:** [Tips and Tricks](tips_and_tricks.md)