yes-core 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3e28057d0c8b0fd6c0bc4f4692c55609b353258637320027efe1d2bcbb02841
-  data.tar.gz: fdb462463528fdbecf3df473f5c0f98601a8d301ec7e4d52f98ec0b2aabdc0f3
+  metadata.gz: 684a9c20dfd17ba779b196a7b294b93e04bf531bcc3d31a2adc9f8a4d645b7dd
+  data.tar.gz: 43e482658ce60a8c7fe4eb5f73f3bf084169857bd06a57a01aadf5ab7cf98e76
 SHA512:
-  metadata.gz: 415e51919c284f2207fbd6ee6dfd9a9427830a6f20ab88986a69b94c14c62b15a75d0fe19360d58088a3d4de8beec953fa78e69c180458874c1d639d677fd9e0
-  data.tar.gz: 85a8557a897a3c2d02b315bf1e637f2bd6837300bf65b71430c314d9a047b9663cf8d33cfaeb7a681ea2bb5eaaf645a4297e351c3304abd56c8026a03d978792
+  metadata.gz: 335785676b2baef08117225b60c3a3b170bb39b0c3fe8ffdfa2781c158944b562f53d00884f409fb0c07c15ace4b513c02bd042973da57118ec325701a258acb
+  data.tar.gz: 72bc5b16b03b00ddc6211806d2566ad5213a25e452836e1ffd09f1e89c10154e98e47edb5ac75573092b1c21ea13cc38f5f49f379f418c2e08c2532d2e498670

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.2.0] - 2026-04-30
+
+- See root CHANGELOG.md for details.
+
 ## [1.1.0] - 2026-04-28
 
 - See root CHANGELOG.md for details.

data/lib/yes/core/aggregate/dsl/command_data.rb

@@ -12,7 +12,7 @@ module Yes
         class CommandData
           attr_reader :name, :context_name, :aggregate_name, :aggregate_class
           attr_accessor :event_name, :payload_attributes, :update_state_block, :guard_names, :authorizer_block,
-                        :encrypted_attributes
+                        :encrypted_attributes, :skip_default_guards
 
           # @param name [Symbol] The name of the command
           # @param aggregate_class [Class] The aggregate class this command belongs to
@@ -21,6 +21,7 @@ module Yes
           # @option options [String] :aggregate The aggregate name
           # @option options [String] :event_name The event name for the command
           # @option options [Hash] :payload_attributes The payload attributes for the command
+          # @option options [Array<Symbol>] :skip_default_guards Default guards (e.g. :not_removed) that should not be auto-applied
           def initialize(name, aggregate_class, options = {})
             @name = name
             @aggregate_class = aggregate_class
@@ -38,6 +39,9 @@ module Yes
 
             # Track encrypted attributes for event schema generation
             @encrypted_attributes = []
+
+            # Default guards to opt out of (e.g. :not_removed for the :remove command itself)
+            @skip_default_guards = options.delete(:skip_default_guards) || []
           end
 
           # Add a guard name to the list of guards

data/lib/yes/core/aggregate.rb

@@ -76,8 +76,15 @@ module Yes
         #
         # @param name [Symbol] The name of the parent.
         # @param options [Hash] Options for configuring the parent.
+        # @option options [Boolean] :command (true) When false, skips defining the `assign_<name>` command.
+        # @option options [Array<Symbol>] :skip_default_guards ([]) Default guards (e.g. `:not_removed`)
+        #   that should not be auto-applied to the generated `assign_<name>` command. See
+        #   {.removable} for context on the `:not_removed` auto-block.
         # @yield Block for defining guards and other attribute configurations.
         # @return [void]
+        #
+        # @example Skip the auto-injected :not_removed guard on a parent's assign command
+        #   parent :tenant, skip_default_guards: %i[not_removed]
         def parent(name, **options, &)
           parent_aggregates[name] = options
 
@@ -85,7 +92,9 @@ module Yes
 
           return unless options.fetch(:command, true)
 
-          command :"assign_#{name}" do
+          skip_default_guards = options[:skip_default_guards] || []
+
+          command :"assign_#{name}", skip_default_guards: do
             payload "#{name}_id": :uuid
 
             guard(:no_change) { public_send(:"#{name}_id") != payload.public_send(:"#{name}_id") }
@@ -103,7 +112,26 @@ module Yes
 
         # Defines a default removal behavior for the aggregate.
         #
+        # In addition to defining the `:remove` command, `removable` records aggregate-level
+        # configuration that the {Yes::Core::CommandHandling::GuardEvaluator} reads at runtime
+        # to **auto-block every other command on the aggregate** while the removal attribute is
+        # set. The auto-block fires before any registered guard (including the auto-injected
+        # `:no_change`), so post-remove mutations consistently raise
+        # `GuardEvaluator::InvalidTransition` with the i18n message under
+        # `aggregates.<context>.<aggregate>.commands.<command>.guards.not_removed.error`.
+        # The `:remove` command itself is exempt and remains gated only by `:no_change`.
+        #
+        # The auto-block is order-independent: `removable` may be declared before or after the
+        # other commands on the aggregate.
+        #
+        # `attr_name` must correspond to an attribute readable on the aggregate (the macro
+        # auto-defines it as `:datetime` when missing).
+        #
         # @param attr_name [Symbol] the attribute name to use for marking removal
+        # @param not_removed_guards [Boolean] when true (default), every non-`:remove` command on
+        #   the aggregate auto-blocks while `attr_name` is set. Pass `false` to disable the
+        #   auto-block aggregate-wide; individual commands can still opt in by defining their
+        #   own `guard(:not_removed)`.
         # @yield Block for defining additional guards and other removal configurations
         # @return [void]
         #
@@ -124,16 +152,30 @@ module Yes
         #     removable(attr_name: :deleted_at)
         #   end
         #
-        def removable(attr_name: :removed_at, &)
+        # @example Disable the :not_removed auto-block aggregate-wide
+        #   class UserAggregate < Yes::Core::Aggregate
+        #     removable(not_removed_guards: false)
+        #   end
+        #
+        def removable(attr_name: :removed_at, not_removed_guards: true, &)
           attribute attr_name, :datetime unless attributes.key?(attr_name)
+          @removable_config = { attr_name:, not_removed_guards: }
 
-          command :remove do
+          command :remove, skip_default_guards: %i[not_removed] do
             guard(:no_change) { !public_send(attr_name) }
             update_state { method(attr_name).call { Time.current } }
             instance_eval(&) if block_given?
           end
         end
 
+        # Returns the removable configuration for the aggregate, or nil if {.removable} was
+        # never called.
+        #
+        # @return [Hash{Symbol => Object}, nil] hash with two keys when set:
+        #   * `:attr_name` [Symbol] — the attribute that marks removal (default `:removed_at`).
+        #   * `:not_removed_guards` [Boolean] — whether the auto-block is enabled.
+        attr_reader :removable_config
+
         # Sets the primary context for the aggregate.
         #
         # @param context [String] The primary context to set.
@@ -239,12 +281,24 @@ module Yes
         # @example Define publish command an published attribute
         #   command :publish
         #
-        def command(*args, **, &)
-          return handle_command_shortcut(*args, **, &) unless Dsl::CommandShortcutExpander.base_case?(*args, **, &)
+        # @example Skip the auto-injected :not_removed guard for a single command
+        #   command :restore, skip_default_guards: %i[not_removed] do
+        #     guard(:no_change) { removed_at.present? }
+        #     update_state { removed_at { nil } }
+        #   end
+        #
+        # All overloads accept a `skip_default_guards:` keyword argument carrying an array of
+        # default-guard symbols (currently only `:not_removed` — see {.removable}) that should
+        # not be auto-applied to the command. Defaults to `[]`.
+        #
+        def command(*args, **kwargs, &)
+          skip_default_guards = kwargs.delete(:skip_default_guards) || []
+          base_case = Dsl::CommandShortcutExpander.base_case?(*args, **kwargs, &)
+          return handle_command_shortcut(*args, skip_default_guards:, **kwargs, &) unless base_case
 
           name = args.first
           @commands ||= {}
-          command_data = Dsl::CommandData.new(name, self, { context:, aggregate: })
+          command_data = Dsl::CommandData.new(name, self, { context:, aggregate:, skip_default_guards: })
           @commands[name] = command_data
 
           Dsl::CommandDefiner.new(command_data).call(&)
@@ -295,8 +349,8 @@ module Yes
         #
         # @return [void]
         #
-        def handle_command_shortcut(...)
-          expanded = Dsl::CommandShortcutExpander.new(...).call
+        def handle_command_shortcut(*, skip_default_guards: [], **, &)
+          expanded = Dsl::CommandShortcutExpander.new(*, **, &).call
 
           expanded.attributes.each do |specification|
             next if attributes.key?(specification.name)
@@ -305,7 +359,7 @@ module Yes
           end
 
           expanded.commands.each do |specification|
-            command(specification.name, &specification.block)
+            command(specification.name, skip_default_guards:, &specification.block)
           end
         end
       end

data/lib/yes/core/command_handling/guard_evaluator.rb

@@ -52,6 +52,7 @@ module Yes
         # @raise [InvalidTransition] When a guard fails with an invalid transition
         # @raise [NoChangeTransition] When a guard fails with a no change transition
         def call
+          check_not_removed!
           self.class.guards.each do |name, guard_data|
             evaluate_guard(name, error_extra: guard_data[:error_extra], block: guard_data[:block])
           end
@@ -64,6 +65,28 @@ module Yes
 
         attr_reader :raw_payload, :raw_metadata, :payload, :aggregate, :aggregate_tracker, :command_name
 
+        # Pre-check that fires before any registered guard. Blocks every command on a removable
+        # aggregate once `removed_at` (or the configured attr) has been set, except where the
+        # command opts out via `skip_default_guards: %i[not_removed]`.
+        #
+        # The check runs ahead of the user-defined guards (including the auto-injected `:no_change`)
+        # so post-remove mutations consistently surface "X has been removed" instead of misleading
+        # downstream errors like "X does not change".
+        #
+        # @return [void]
+        # @raise [InvalidTransition] When the aggregate has been removed and the command is not opted out.
+        def check_not_removed!
+          config = aggregate.class.respond_to?(:removable_config) ? aggregate.class.removable_config : nil
+          return unless config && config[:not_removed_guards]
+
+          command_data = aggregate.class.commands[command_name]
+          return if command_data&.skip_default_guards&.include?(:not_removed)
+
+          return if aggregate.public_send(config[:attr_name]).blank?
+
+          raise InvalidTransition, error_message(:not_removed)
+        end
+
         # Evaluates a single guard and raises appropriate error if it fails
         #
         # @param name [Symbol] The name of the guard

data/lib/yes/core/utils/aggregate_shortcuts.rb

@@ -38,26 +38,35 @@ module Yes
             results
           end
 
-          # Display shortcuts in a formatted table
+          # Display shortcuts in a formatted table.
+          #
+          # Writes directly to STDOUT (via Kernel#puts) rather than the Rails logger
+          # so the output is readable in any environment — Rails consoles in
+          # production typically configure structured / JSON loggers that would
+          # otherwise wrap each line in a JSON envelope.
+          #
           # @param filter [String, nil] Optional filter
+          # rubocop:disable Rails/Output
           def display(filter = nil)
             shortcuts = list(filter)
 
             if shortcuts.empty?
-              Rails.logger.debug { "No shortcuts found#{" for '#{filter}'" if filter}." }
+              puts "No shortcuts found#{" for '#{filter}'" if filter}."
               return
             end
 
             max_shortcut_length = shortcuts.keys.map(&:length).max
+            separator = '=' * (max_shortcut_length + 70)
 
-            Rails.logger.debug "\nAvailable Aggregate Shortcuts:"
-            Rails.logger.debug '=' * (max_shortcut_length + 70)
+            puts "\nAvailable Aggregate Shortcuts:"
+            puts separator
             shortcuts.sort.each do |shortcut, full_path|
-              Rails.logger.debug "#{shortcut.ljust(max_shortcut_length)} → #{full_path}"
+              puts "#{shortcut.ljust(max_shortcut_length)} → #{full_path}"
             end
-            Rails.logger.debug '=' * (max_shortcut_length + 70)
-            Rails.logger.debug { "\nUsage: #{shortcuts.keys.first}.new(id)" } if shortcuts.any?
+            puts separator
+            puts "\nUsage: #{shortcuts.keys.first}.new(id)"
           end
+          # rubocop:enable Rails/Output
 
           private
 

data/lib/yes/core/version.rb

@@ -2,6 +2,6 @@
 
 module Yes
   module Core
-    VERSION = '1.1.0'
+    VERSION = '1.2.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yes-core
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Nico Ritsche