cmdx 1.13.0 → 1.14.0

data/mkdocs.yml

@@ -54,6 +54,8 @@ theme:
     - navigation.expand
     - navigation.path
     - navigation.sections
+    - navigation.tabs
+    - navigation.tabs.sticky
     - navigation.top
     - navigation.tracking
     - search.highlight
@@ -81,9 +83,25 @@ markdown_extensions:
   - tables
   - toc:
       permalink: true
+      title: On this page
 
 plugins:
   - search
+  - rss:
+      match_path: blog/posts/.*
+      date_from_meta:
+        as_creation: date
+      categories:
+        - categories
+  - blog:
+      blog_dir: blog
+      blog_toc: true
+      post_date_format: long
+      post_url_format: "{slug}"
+      archive_date_format: MMMM yyyy
+      categories_allowed:
+        - Tutorials
+        - Updates
   - llmstxt:
       markdown_description: >-
         CMDx is a Ruby framework for building maintainable, observable business logic through composable command/service objects.
@@ -124,51 +142,59 @@ plugins:
           - workflows.md: Composing multiple tasks into sequential pipelines with conditional execution
         More:
           - tips_and_tricks.md: Best practices, patterns, and techniques for maintainable CMDx applications
+        Ecosystem:
+          - cmdx-rspec: RSpec test matchers (https://github.com/drexed/cmdx-rspec)
 
 nav:
   - Home: index.md
-  - Getting Started: getting_started.md
-  - Configuration: configuration.md
-  - Basics:
-    - Setup: basics/setup.md
-    - Execution: basics/execution.md
-    - Context: basics/context.md
-    - Chain: basics/chain.md
-  - Interruptions:
-    - Halt: interruptions/halt.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
-  - Features:
-    - Callbacks: callbacks.md
-    - Middlewares: middlewares.md
-    - Logging: logging.md
-    - Internationalization: internationalization.md
-    - Retries: retries.md
-    - Deprecation: deprecation.md
-    - Workflows: workflows.md
-  - More:
-    - Tips and Tricks: tips_and_tricks.md
-  - References:
-    - API Documentation: https://drexed.github.io/cmdx/api/index.html
-    - llms.txt: https://drexed.github.io/cmdx/llms.txt
-    - llms-full.txt: https://drexed.github.io/cmdx/llms-full.txt
+  - Documentation:
+    - Getting Started: getting_started.md
+    - Configuration: configuration.md
+    - Basics:
+      - Setup: basics/setup.md
+      - Execution: basics/execution.md
+      - Context: basics/context.md
+      - Chain: basics/chain.md
+    - Interruptions:
+      - Halt: interruptions/halt.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
+    - Features:
+      - Callbacks: callbacks.md
+      - Middlewares: middlewares.md
+      - Logging: logging.md
+      - Internationalization: internationalization.md
+      - Retries: retries.md
+      - Deprecation: deprecation.md
+      - Workflows: workflows.md
+    - More:
+      - Tips and Tricks: tips_and_tricks.md
+    - References:
+      - API Documentation: https://drexed.github.io/cmdx/api/index.html
+      - llms.txt: https://drexed.github.io/cmdx/llms.txt
+      - llms-full.txt: https://drexed.github.io/cmdx/llms-full.txt
+    - Ecosystem:
+      - cmdx-rspec: https://github.com/drexed/cmdx-rspec
+  - Blog: blog/index.md
 
 extra:
   generator: false
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/drexed/cmdx
+    - icon: fontawesome/solid/rss
+      link: https://drexed.github.io/cmdx/feed_rss_created.xml
 
 extra_css:
   - stylesheets/extra.css

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 1.13.0
+  version: 1.14.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -227,61 +227,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".DS_Store"
-- ".cursor/prompts/docs.md"
-- ".cursor/prompts/llms.md"
-- ".cursor/prompts/rspec.md"
-- ".cursor/prompts/yardoc.md"
-- ".cursor/rules/cursor-instructions.mdc"
-- ".irbrc"
-- ".rspec"
-- ".rubocop.yml"
-- ".ruby-version"
-- ".yard-lint.yml"
-- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- docs/.DS_Store
-- docs/assets/favicon.ico
-- docs/assets/favicon.svg
-- docs/attributes/coercions.md
-- docs/attributes/defaults.md
-- docs/attributes/definitions.md
-- docs/attributes/naming.md
-- docs/attributes/transformations.md
-- docs/attributes/validations.md
-- docs/basics/chain.md
-- docs/basics/context.md
-- docs/basics/execution.md
-- docs/basics/setup.md
-- docs/callbacks.md
-- docs/configuration.md
-- docs/deprecation.md
-- docs/getting_started.md
-- docs/index.md
-- docs/internationalization.md
-- docs/interruptions/exceptions.md
-- docs/interruptions/faults.md
-- docs/interruptions/halt.md
-- docs/logging.md
-- docs/middlewares.md
-- docs/outcomes/result.md
-- docs/outcomes/states.md
-- docs/outcomes/statuses.md
-- docs/retries.md
-- docs/stylesheets/extra.css
-- docs/tips_and_tricks.md
-- docs/workflows.md
-- examples/active_record_database_transaction.md
-- examples/active_record_query_tagging.md
-- examples/flipper_feature_flags.md
-- examples/paper_trail_whatdunnit.md
-- examples/redis_idempotency.md
-- examples/sentry_error_tracking.md
-- examples/sidekiq_async_execution.md
-- examples/stoplight_circuit_breaker.md
 - lib/cmdx.rb
 - lib/cmdx/.DS_Store
 - lib/cmdx/attribute.rb
@@ -431,13 +381,9 @@ files:
 - lib/locales/zh-TW.yml
 - lib/locales/zh-YUE.yml
 - mkdocs.yml
-- src/cmdx-dark-logo.png
-- src/cmdx-favicon.svg
-- src/cmdx-light-logo.png
-- src/cmdx-logo.svg
 homepage: https://github.com/drexed/cmdx
 licenses:
-- MIT
+- LGPL-3.0
 metadata:
   homepage_uri: https://github.com/drexed/cmdx
   source_code_uri: https://github.com/drexed/cmdx
@@ -459,7 +405,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: CMDx is a framework for building maintainable business processes.
 test_files: []

data/.cursor/prompts/docs.md

@@ -1,12 +0,0 @@
-You are a senior Ruby developer with expert knowledge of CMDx and writing documentation.
-
-Update the active tab using the following guidelines:
-
-- Follow best practices and implementation
-- Use a consistent warm, friendly and professional voice
-- Examples should be concise, non-repetitive, and realistic
-- Update any pre-existing documentation to match stated rules
-- Examples should not cross boundaries or focus
-- Docs must cover both typical use cases, including invalid and error conditions
-- Use mkdocs Admonitions to emphasize critical information (https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
-- Optimize for LLM's including coding and AI agents

data/.cursor/prompts/llms.md

@@ -1,8 +0,0 @@
-Process the following instructions in the order given:
-
-1. Create an `LLM.md` file
-2. Append all files within `docs/**/*.md` into @LLM.md
-  2a. Use order outlined under the nav key in @mkdocs.yml
-  2b. Process one file at a time faster performance and improved accuracy
-  2c. Exclude @index.md and @LLM.md files
-  2d. All URLs should be absolute

data/.cursor/prompts/rspec.md

@@ -1,24 +0,0 @@
-You are a senior Ruby developer with expert knowledge of RSpec.
-
-Add tests for the active tab using the following guidelines:
-
-- 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 and error conditions
-- Consider all possible scenarios for each method or behavior and ensure they are tested
-- Do NOT include integration or real world examples
-- Verify all specs are passing

data/.cursor/prompts/yardoc.md

@@ -1,15 +0,0 @@
-You are a senior Ruby developer with expert knowledge of YARDoc.
-
-Add yardoc to the active tab using the following guidelines:
-
-- Follow best practices and implementation
-- New documentation should be consistent with current `lib/cmdx` documentation
-- Examples should be concise, non-repetitive, and realistic
-- Avoid unnecessary complexity or duplication
-- Update any pre-existing documentation to match stated rules
-- Do NOT include `CMDx` module level docs
-- Module level docs description should NOT include `@example`
-- Method level docs should include `@example`, `param`, `@options`, `@return`, and any `@raise`
-- Hash `@params` should expand with possible `@option`
-- Module and method level docs should NOT include `@since`
-- Add RBS inline comments after YARDoc block

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

@@ -1,68 +0,0 @@
----
-description:
-globs:
-alwaysApply: true
----
-
-# Ruby Coding Standards
-
-Follow the official Ruby gem guides for best practices.
-Reference the guides outlined in https://guides.rubygems.org
-
-## Project Context
-CMDx provides a framework for designing and executing complex business logic within service/command objects.
-Reference the CMDx documentation in https://github.com/drexed/cmdx/blob/main/LLM.md
-
-## Technology Stack
-- Ruby 3.4+
-- RSpec 3.1+
-
-## Development Guidelines
-- Performance is critical - benchmark any changes that could affect speed
-- Follow existing code patterns and conventions
-- Maintain backward compatibility for public API
-
-## Code Style and Structure
-- Write concise, idiomatic Ruby code with accurate examples
-- Follow Ruby conventions and best practices
-- Use object-oriented and functional programming patterns as appropriate
-- Prefer iteration and modularization over code duplication
-- Use descriptive variable and method names (e.g., user_signed_in?, calculate_total)
-- Write comprehensive code documentation using the Yardoc format
-- Minimize object allocations in hot paths
-
-## Naming Conventions
-- Use snake_case for file names, method names, and variables
-- Use CamelCase for class and module names
-
-## Syntax and Formatting
-- Follow the Ruby Style Guide (https://rubystyle.guide/)
-- Follow Ruby style conventions (2-space indentation, snake_case methods)
-- Use Ruby's expressive syntax (e.g., unless, ||=, &.)
-- Prefer double quotes for strings
-- Respect my Rubocop options
-- Run `bundle exec rubocop .` before finalizing any code changes
-
-## Performance Optimization
-- Use memoization for expensive operations
-
-## Testing
-- Follow the RSpec Style Guide (https://rspec.rubystyle.guide/)
-- Write comprehensive tests using RSpec
-- It's ok to put multiple assertions in the same example
-- Include both BDD and TDD based tests
-- Create test objects to share across tests
-- Do NOT make tests for obvious or reflective expectations
-- Prefer real objects over mocks. Use `instance_double` if necessary; never `double`
-- Don't test declarative configuration
-- Use appropriate matchers
-- Update tests and update Yardocs after you write code
-- Run `bundle rspec .` before finalizing any code changes
-
-## Documentation
-- Utilize the YARDoc format when documenting Ruby code
-- Follow these best practices:
-  - Avoid redundant comments that merely restate the code
-  - Keep comments up-to-date with code changes
-  - Keep documentation consistent
-- Update CHANGELOG.md with any changes

data/.irbrc

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-require "pp"
-
-# rubocop:disable Style/MixinUsage
-unless defined?(CMDx)
-  require_relative "lib/cmdx"
-
-  require_relative "spec/support/helpers/task_builders"
-  require_relative "spec/support/helpers/workflow_builders"
-  include CMDx::Testing::TaskBuilders
-  include CMDx::Testing::WorkflowBuilders
-end
-# rubocop:enable Style/MixinUsage
-
-def reload!
-  exec("irb")
-end

data/.rspec

@@ -1,4 +0,0 @@
---backtrace
---color
---format progress
---order random

data/.rubocop.yml

@@ -1,95 +0,0 @@
-plugins:
-  - rubocop-performance
-  - rubocop-rake
-  - rubocop-rspec
-AllCops:
-  NewCops: enable
-  DisplayCopNames: true
-  DisplayStyleGuide: true
-  TargetRubyVersion: 3.1
-Gemspec/DevelopmentDependencies:
-  EnforcedStyle: gemspec
-Layout/EmptyLinesAroundAttributeAccessor:
-  Enabled: true
-Layout/EmptyLinesAroundClassBody:
-  EnforcedStyle: empty_lines_except_namespace
-Layout/EmptyLinesAroundModuleBody:
-  EnforcedStyle: empty_lines_except_namespace
-Layout/FirstHashElementIndentation:
-  EnforcedStyle: consistent
-Layout/LineLength:
-  Enabled: false
-Lint/MissingSuper:
-  Exclude:
-    - 'spec/**/**/*'
-Lint/ShadowedException:
-  Enabled: false
-Lint/UnusedMethodArgument:
-  Exclude:
-    - 'lib/cmdx/coercions/**/*'
-    - 'lib/cmdx/log_formatters/**/*'
-    - 'lib/cmdx/middlewares/**/*'
-    - 'lib/cmdx/validators/**/*'
-Metrics/AbcSize:
-  Enabled: false
-Metrics/BlockLength:
-  Enabled: false
-Metrics/ClassLength:
-  Enabled: false
-Metrics/CyclomaticComplexity:
-  Enabled: false
-Metrics/MethodLength:
-  Enabled: false
-Metrics/ModuleLength:
-  Enabled: false
-Metrics/PerceivedComplexity:
-  Enabled: false
-Naming/MethodParameterName:
-  Enabled: false
-RSpec/DescribeClass:
-  Exclude:
-    - 'spec/integrations/**/*'
-RSpec/ExampleLength:
-  Enabled: false
-RSpec/IndexedLet:
-  Enabled: false
-RSpec/MessageSpies:
-  EnforcedStyle: receive
-RSpec/MultipleExpectations:
-  Enabled: false
-RSpec/MultipleMemoizedHelpers:
-  Enabled: false
-RSpec/NestedGroups:
-  Enabled: false
-RSpec/SpecFilePathFormat:
-  CustomTransform:
-    CMDx: cmdx
-RSpec/SubjectStub:
-  Enabled: false
-RSpec/StubbedMock:
-  Enabled: false
-RSpec/VerifiedDoubleReference:
-  Enabled: false
-Style/ArgumentsForwarding:
-  Exclude:
-    - 'lib/cmdx/utils/call.rb'
-Style/CaseEquality:
-  Enabled: false
-Style/DocumentDynamicEvalDefinition:
-  Enabled: false
-Style/Documentation:
-  Enabled: false
-Style/DoubleNegation:
-  Enabled: false
-Style/FrozenStringLiteralComment:
-  Enabled: true
-  EnforcedStyle: always_true
-  SafeAutoCorrect: true
-Style/ModuleFunction:
-  EnforcedStyle: extend_self
-Style/OptionalBooleanParameter:
-  Enabled: false
-Style/StringConcatenation:
-  Enabled: false
-Style/StringLiterals:
-  EnforcedStyle: double_quotes

data/.ruby-version

@@ -1 +0,0 @@
-3.4.5

data/.yard-lint.yml

@@ -1,174 +0,0 @@
-# YARD-Lint Configuration
-# See https://github.com/mensfeld/yard-lint for documentation
-
-# Global settings for all validators
-AllValidators:
-  # YARD command-line options (applied to all validators by default)
-  YardOptions:
-    - --private
-    - --protected
-
-  # Global file exclusion patterns
-  Exclude:
-    - '\.git'
-    - 'vendor/**/*'
-    - 'node_modules/**/*'
-    - 'spec/**/*'
-    - 'test/**/*'
-
-  # Exit code behavior (error, warning, convention, never)
-  FailOnSeverity: warning
-
-  # Minimum documentation coverage percentage (0-100)
-  # Fails if coverage is below this threshold
-  # MinCoverage: 80.0
-
-  # Diff mode settings
-  DiffMode:
-    # Default base ref for --diff (auto-detects main/master if not specified)
-    DefaultBaseRef: ~
-
-# Documentation validators
-Documentation/UndocumentedObjects:
-  Description: 'Checks for classes, modules, and methods without documentation.'
-  Enabled: false
-  Severity: warning
-  ExcludedMethods:
-    - 'initialize/0'  # Exclude parameter-less initialize
-    - '/^_/'          # Exclude private methods (by convention)
-
-Documentation/UndocumentedMethodArguments:
-  Description: 'Checks for method parameters without @param tags.'
-  Enabled: true
-  Severity: warning
-
-Documentation/UndocumentedBooleanMethods:
-  Description: 'Checks that question mark methods document their boolean return.'
-  Enabled: true
-  Severity: warning
-
-Documentation/UndocumentedOptions:
-  Description: 'Detects methods with options hash parameters but no @option tags.'
-  Enabled: true
-  Severity: warning
-
-Documentation/MarkdownSyntax:
-  Description: 'Detects common markdown syntax errors in documentation.'
-  Enabled: true
-  Severity: warning
-
-# Tags validators
-Tags/Order:
-  Description: 'Enforces consistent ordering of YARD tags.'
-  Enabled: true
-  Severity: convention
-  EnforcedOrder:
-    - param
-    - option
-    - return
-    - raise
-    - example
-
-Tags/InvalidTypes:
-  Description: 'Validates type definitions in @param, @return, @option tags.'
-  Enabled: true
-  Severity: warning
-  ValidatedTags:
-    - param
-    - option
-    - return
-
-Tags/TypeSyntax:
-  Description: 'Validates YARD type syntax using YARD parser.'
-  Enabled: true
-  Severity: warning
-  ValidatedTags:
-    - param
-    - option
-    - return
-    - yieldreturn
-
-Tags/MeaninglessTag:
-  Description: 'Detects @param/@option tags on classes, modules, or constants.'
-  Enabled: true
-  Severity: warning
-  CheckedTags:
-    - param
-    - option
-  InvalidObjectTypes:
-    - class
-    - module
-    - constant
-
-Tags/CollectionType:
-  Description: 'Validates Hash collection syntax consistency.'
-  Enabled: true
-  Severity: convention
-  EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
-  ValidatedTags:
-    - param
-    - option
-    - return
-    - yieldreturn
-
-Tags/TagTypePosition:
-  Description: 'Validates type annotation position in tags.'
-  Enabled: true
-  Severity: convention
-  CheckedTags:
-    - param
-    - option
-  # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
-  #                or 'type_first' (@param [Type] name)
-  EnforcedStyle: type_after_name
-
-Tags/ApiTags:
-  Description: 'Enforces @api tags on public objects.'
-  Enabled: false  # Opt-in validator
-  Severity: warning
-  AllowedApis:
-    - public
-    - private
-    - internal
-
-Tags/OptionTags:
-  Description: 'Requires @option tags for methods with options parameters.'
-  Enabled: true
-  Severity: warning
-
-# Warnings validators - catches YARD parser errors
-Warnings/UnknownTag:
-  Description: 'Detects unknown YARD tags.'
-  Enabled: false
-  Severity: error
-
-Warnings/UnknownDirective:
-  Description: 'Detects unknown YARD directives.'
-  Enabled: true
-  Severity: error
-
-Warnings/InvalidTagFormat:
-  Description: 'Detects malformed tag syntax.'
-  Enabled: true
-  Severity: error
-
-Warnings/InvalidDirectiveFormat:
-  Description: 'Detects malformed directive syntax.'
-  Enabled: true
-  Severity: error
-
-Warnings/DuplicatedParameterName:
-  Description: 'Detects duplicate @param tags.'
-  Enabled: true
-  Severity: error
-
-Warnings/UnknownParameterName:
-  Description: 'Detects @param tags for non-existent parameters.'
-  Enabled: true
-  Severity: error
-
-# Semantic validators
-Semantic/AbstractMethods:
-  Description: 'Ensures @abstract methods do not have real implementations.'
-  Enabled: true
-  Severity: warning

data/.yardopts

@@ -1,7 +0,0 @@
---no-private
---output-dir
-docs/api
---exclude
-lib/generators/**/*.rb
-lib/cmdx/railtie.rb
-lib/**/*.rb

data/docs/assets/favicon.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="1000" height="1000"><g clip-path="url(#SvgjsClipPath1038)"><rect width="1000" height="1000" fill="#ffffff"></rect><g transform="matrix(6.235191420376605,0,0,6.235191420376605,175.46452176081812,150)"><svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="104.098" height="112.266"><svg width="104.098" height="112.266" viewBox="0 0 60 64.708" xmlns="http://www.w3.org/2000/svg"><path d="M29.907 17.723 26.4 23.17 13.384 3.323h3.507l9.508 14.77 1.938-3.139L18.737 0H7.291L26.4 29.262 45.045 0h-3.97L30 17.54zM9.23 61.293H6.091l18.646-29.447L4.43.093H.46l20.308 31.846L0 64.708l10.985-.092 39.138-61.2h3.323L31.57 37.754l13.662 21.415h3.97L35.445 37.754 59.537.093H48.37zm29.63-23.262 15.047 23.262H43.384l-13.662-20.77-15.508 24.093h3.97l11.63-18 11.723 18H60L41.17 35.354l-.278-.461z" fill="#000"></path></svg></svg></g></g><defs><clipPath id="SvgjsClipPath1038"><rect width="1000" height="1000" x="0" y="0" rx="150" ry="150"></rect></clipPath></defs></svg>