cmdx 1.12.0 → 1.14.0

data/lib/cmdx/result.rb

@@ -70,7 +70,7 @@ module CMDx
     # @return [Hash{Symbol => Object}] Metadata hash
     #
     # @example
-    #   result.metadata # => { duration: 1.5, retries: 2 }
+    #   result.metadata # => { duration: 1.5, code: 200, message: "Success" }
     #
     # @rbs @metadata: Hash[Symbol, untyped]
     attr_reader :metadata
@@ -95,7 +95,27 @@ module CMDx
     # @rbs @cause: (Exception | nil)
     attr_reader :cause
 
-    def_delegators :task, :context, :chain, :errors
+    # Returns the number of retries attempted.
+    #
+    # @return [Integer] The number of retries attempted
+    #
+    # @example
+    #   result.retries # => 2
+    #
+    # @rbs @retries: Integer
+    attr_accessor :retries
+
+    # Returns whether the result has been rolled back.
+    #
+    # @return [Boolean] Whether the result has been rolled back
+    #
+    # @example
+    #   result.rolled_back? # => true
+    #
+    # @rbs @rolled_back: bool
+    attr_accessor :rolled_back
+
+    def_delegators :task, :context, :chain, :errors, :dry_run?
     alias ctx context
 
     # @param task [CMDx::Task] The task instance this result represents
@@ -118,6 +138,8 @@ module CMDx
       @metadata = {}
       @reason = nil
       @cause = nil
+      @retries = 0
+      @rolled_back = false
     end
 
     STATES.each do |s|
@@ -419,6 +441,26 @@ module CMDx
       failed? && !caused_failure?
     end
 
+    # @return [Boolean] Whether the result has been retried
+    #
+    # @example
+    #   result.retried? # => true
+    #
+    # @rbs () -> bool
+    def retried?
+      retries.positive?
+    end
+
+    # @return [Boolean] Whether the result has been rolled back
+    #
+    # @example
+    #   result.rolled_back? # => true
+    #
+    # @rbs () -> bool
+    def rolled_back?
+      !!@rolled_back
+    end
+
     # @return [Integer] Index of this result in the chain
     #
     # @example
@@ -457,6 +499,7 @@ module CMDx
         if interrupted?
           hash[:reason] = reason
           hash[:cause] = cause
+          hash[:rolled_back] = rolled_back?
         end
 
         if failed?

data/lib/cmdx/task.rb

@@ -71,6 +71,7 @@ module CMDx
     attr_reader :chain
 
     def_delegators :result, :skip!, :fail!, :throw!
+    def_delegators :chain, :dry_run?
 
     # @param context [Hash, Context] The initial context for the task
     #
@@ -94,7 +95,7 @@ module CMDx
       @id = Identifier.generate
       @context = Context.build(context)
       @result = Result.new(self)
-      @chain = Chain.build(@result)
+      @chain = Chain.build(@result, dry_run: @context.delete(:dry_run))
     end
 
     class << self
@@ -216,6 +217,25 @@ module CMDx
       end
       alias remove_attribute remove_attributes
 
+      # @return [Hash] Hash of attribute names to their configurations
+      #
+      # @example
+      #   MyTask.attributes_schema #=> {
+      #     user_id: { name: :user_id, method_name: :user_id, required: true, types: [:integer], options: {}, children: [] },
+      #     email: { name: :email, method_name: :email, required: false, types: [:string], options: { default: nil }, children: [] },
+      #     profile: { name: :profile, method_name: :profile, required: false, types: [:hash], options: {}, children: [
+      #       { name: :bio, method_name: :bio, required: false, types: [:string], options: {}, children: [] },
+      #       { name: :name, method_name: :name, required: true, types: [:string], options: {}, children: [] }
+      #     ] }
+      #   }
+      #
+      # @rbs () -> Hash[Symbol, Hash[Symbol, untyped]]
+      def attributes_schema
+        Array(settings[:attributes]).each_with_object({}) do |attr, schema|
+          schema[attr.method_name] = attr.to_h
+        end
+      end
+
       CallbackRegistry::TYPES.each do |callback|
         # @param callables [Array] Callable objects to register as callbacks
         # @param options [Hash] Options for the callback registration
@@ -341,6 +361,7 @@ module CMDx
         type: self.class.include?(Workflow) ? "Workflow" : "Task",
         tags: self.class.settings[:tags],
         class: self.class.name,
+        dry_run: dry_run?,
         id:
       }
     end

data/lib/cmdx/version.rb

@@ -5,6 +5,6 @@ module CMDx
   # @return [String] the version of the CMDx gem
   #
   # @rbs return: String
-  VERSION = "1.12.0"
+  VERSION = "1.14.0"
 
 end

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
@@ -65,7 +67,11 @@ markdown_extensions:
   - attr_list
   - md_in_html
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
@@ -77,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.
@@ -120,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.12.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