mu-action 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e178de7158d182e1527dd7b23ede20e67f9010e4bc588869fe433ebd4f2d1c85
-  data.tar.gz: 424feef48df8a60bd7c9aaf5ea755744d804f818e54fe2dd6d9a2ec4aea70595
+  metadata.gz: 261d73076a857c43d7c68e5c3585cb3e96d693d54ed104b33abd6a6e897272fd
+  data.tar.gz: 9a0ac5c6592b3a2715918da63f88d8fec4b45dc6111547e1a545d6a26553e47e
 SHA512:
-  metadata.gz: 7776bdf1fbb430638cb882abf2558d397b8dea4d7ea69c237ab9c3d9f0d3ddd5f05f4c66bb2cad79e16f02d2fb6b8a0b14d99bcba2bac01c99b5e8249763cc8d
-  data.tar.gz: aa9b022415a7905aa29ab543fed97763842e2b6ccf18e08e4b91b62479bf38651eb2dc518c9c5b7f49f3413f80de896886e534ac03473fabaaf6d82c1c250ccd
+  metadata.gz: ef960929df4e5a7daa07544be3af52a5a952185959fbcc3a21329145e7e465c3f798ff46c0c382f4c63310fbfd3aa611e3e742f506fcbec949b80ebd1463adc4
+  data.tar.gz: 75a8de3adbc5dbaf4302f233c9314bedf009c5aebd4b12b32422a790a989e75073aaffc8303bc124e2c058b36ae88cd63b1bf37b7ed6edc84cda42fc5ab02b55

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-11-14
+
+### Breaking
+- Keyword arguments to `Failure` now go to the new `Failure#details` instead of being merged into `meta`. Read `result.details[:errors]` where you used `result.meta[:errors]`.
+- `FailureError#meta` is replaced by `#details` and `#failure` (the `Failure` result, set when raised by `call!`).
+- `call!` raises a new `FailureError` whose `cause` is the original one.
+
+### Added
+- `failure` class method to declare an action's failures and the types of their details, plus `failures` to list them. `failure from: OtherAction` accepts the failures of another action.
+- `Mu::Action.on_undeclared_failure`: `:raise` (default) or a callable receiving the action, error and details.
+- A failure raised by a nested `call!` becomes the outer action's failure, with the inner `Failure` in `meta[:cause]`.
+- `context:` keyword: caller information (actor, account, channel...) available as `context` in hooks and `call`, recorded in `meta[:context]`, and inherited by nested actions. `context` is now a reserved prop name.
+- `record_props` class method: record every prop (default), none (`record_props false`), `only:` some or all `except:` some in `meta[:props]`.
+
+### Changed
+- An action without a `result` type accepts `nil` as its success value, and `Success()` can be called without a value. Typed results still reject `nil` unless declared with `_Nilable`.
+- Minimum Ruby version raised to 3.2 (3.1 is end-of-life).
+- CI now tests Ruby 3.2, 3.3, 3.4 and 4.0.
+- Development lockfile updated to Literal 1.9.0, RuboCop 1.92, Steep 2.0 and RBS 4.1. This fixes the Ruby 4.0 CI job (ffi) and the `tsort` warnings on Ruby 4.0.
+- CI uses `actions/checkout@v7`, which runs on Node.js 24.
+
+### Removed
+- The unused protected `result_class` method.
+- Development files from the packaged gem, which now only contains `lib/mu/`, `sig/mu/` and the docs. `lib/guard/steep.rb` and the local RBS stubs for Kernel and Literal were shipped by mistake.
+
+### Fixed
+- A `meta:` hash passed by a caller is no longer modified.
+- `bin/test_readme_examples` now requires `fileutils`, which is no longer loaded indirectly on Ruby 3.4+.
+
+## [0.2.0] - 2025-10-30
+
+### Added
+- Support registering `before`, `after`, and `around` hooks by method name.
+- Steep type-checking infrastructure: Steepfile, comprehensive RBS signatures for `Mu::Action`.
+- Guard plugin for steep type checking.
+
+### Changed
+- `bin/check` now runs `bundle exec steep check` as part of the default contributor workflow.
+- Guard automation reorganized to load the new Steep guard explicitly.
+- Updated Bundler metadata to 2.7.2.
+
+### Documentation
+- Added `AGENTS.md` with contributor and workflow guidelines.
+
 ## [0.1.0] - 2025-07-23
 
 ### Added

data/README.md

@@ -62,7 +62,7 @@ end
 
 ### Results
 
-A `Success` result contains the `value` returned by the interactor, while a `Failure` result contains an `error` value. Both result types respond to `#success?` and `#failure?` methods to check their status. They also provide a `#meta` method to access metadata about the execution, such as the class name, properties.
+A `Success` result contains the `value` returned by the interactor, while a `Failure` result contains an `error` value, usually a symbol, and a `details` hash built from the keyword arguments given to `Failure`. Both result types respond to `#success?` and `#failure?` methods to check their status. They also provide a `#meta` method to access metadata about the execution, such as the class name and properties. Metadata is for diagnostics; anything a caller needs belongs in `details`. An interactor with nothing to return can call `Success()` without a value.
 
 A failure will return immediately.
 
@@ -124,6 +124,41 @@ result = ProcessPayment.call(amount: 100.0, card_token: "tok_123")
 assert result.value[:payment_id] == "pay_123"
 ```
 
+Hooks can also be registered by method name if you prefer keeping the logic in dedicated instance methods:
+
+```ruby
+class ProcessPayment
+  include Mu::Action
+
+  prop :amount, Float
+  prop :card_token, String
+
+  before :prepare_logging
+  after :finalize_logging
+  around :wrap_in_transaction
+
+  def prepare_logging
+    meta[:started_at] = Time.now
+    Rails.logger.info "Processing payment for $#{@amount}"
+  end
+
+  def finalize_logging
+    meta[:completed_at] = Time.now
+    Rails.logger.info "Payment processing completed"
+  end
+
+  def wrap_in_transaction(chain)
+    ActiveRecord::Base.transaction { chain.call }
+  end
+
+  def call
+    Success(payment_id: "pay_123")
+  end
+end
+```
+
+Around hook methods may also receive no arguments and use `yield`, or accept two arguments `(action, chain)` to mirror the block-based signature.
+
 ### Custom Result Types
 
 Define typed results for better API contracts:
@@ -164,6 +199,81 @@ assert (1..6).cover? result
 
 You can refer to the [Literal documentation](https://literal.fun/docs) for more details on the [built-in types](https://literal.fun/docs/built-in-types.html) or see some [example types](https://literal.fun/docs/example-types.html).
 
+### Failures
+
+`Failure` takes an error code and, optionally, details as keyword arguments:
+
+```ruby
+class RenameProject
+  include Mu::Action
+
+  prop :name, String
+
+  def call
+    Failure(:invalid, errors: ["name can't be blank"]) if @name.empty?
+    Success(@name)
+  end
+end
+
+case RenameProject.call(name: "")
+in Mu::Action::Failure(error: :invalid, details: { errors: })
+  assert errors == ["name can't be blank"]
+end
+```
+
+An interactor can declare the failures it returns, with the types of their details. Once it declares any, an undeclared failure or a detail of the wrong type raises an `ArgumentError`. Interactors without declarations accept any failure.
+
+```ruby
+class PublishArticle
+  include Mu::Action
+
+  failure :already_published
+  failure :invalid, errors: _Array(String)
+
+  prop :title, String
+
+  def call
+    Failure(:invalid, errors: ["title is missing"]) if @title.empty?
+    Success(@title)
+  end
+end
+
+assert PublishArticle.failures.keys == %i[already_published invalid]
+```
+
+To report undeclared failures instead of raising, give `Mu::Action.on_undeclared_failure` a callable. It receives the interactor, the error code and the details, and the failure goes through:
+
+```ruby
+Mu::Action.on_undeclared_failure = lambda do |action, error, details|
+  Rails.logger.info "#{action.class} returned undeclared failure #{error.inspect}"
+end
+
+Mu::Action.on_undeclared_failure = :raise # the default
+```
+
+To compose interactors, call the inner one with `call!`. Its failure becomes the outer interactor's failure, with the same error and details, and the inner `Failure` is kept in `meta[:cause]`. Use `failure from:` to accept every failure of the inner interactor:
+
+```ruby
+class PublishFeaturedArticle
+  include Mu::Action
+
+  failure from: PublishArticle
+
+  prop :title, String
+
+  def call
+    title = PublishArticle.call!(title: @title)
+    Success("Featured: #{title}")
+  end
+end
+
+result = PublishFeaturedArticle.call(title: "")
+assert result.error == :invalid
+assert result.meta[:cause].meta[:class] == PublishArticle
+```
+
+Because the inner failure is raised as an exception, around hooks such as transactions see it and can roll back.
+
 ### Metadata Tracking
 
 Every interactor automatically tracks metadata including class information and property values:
@@ -177,6 +287,46 @@ assert result.meta == {
 }
 ```
 
+To keep sensitive or bulky props out of the metadata, choose which ones are recorded:
+
+```ruby
+class SignIn
+  include Mu::Action
+
+  record_props except: %i[password]   # or only: [...], or record_props false
+
+  prop :email, String
+  prop :password, String
+
+  def call = Success(@email)
+end
+
+assert SignIn.call(email: "jane@example.com", password: "secret").meta[:props] == { email: "jane@example.com" }
+```
+
+### Context
+
+Information about who is calling and from where, such as the actor, the account or the channel, goes in `context` rather than in props. It's available in hooks and in `call`, and it's recorded in `meta[:context]`. It can be any object.
+
+```ruby
+class ArchiveProject
+  include Mu::Action
+
+  prop :project_id, Integer
+
+  before do
+    meta[:archived_by] = context[:actor]
+  end
+
+  def call = Success(@project_id)
+end
+
+result = ArchiveProject.call(project_id: 42, context: { actor: "jane", channel: :web })
+assert result.meta[:archived_by] == "jane"
+```
+
+Interactors called by another one inherit its context, so a hook in a nested interactor sees the same actor. Pass `context:` explicitly to override it.
+
 ## Differences from the Interactor Gem
 
 The main difference and the motivation for creating `Mu::Action` is to separate the context into inputs, an output, and metadata. This allows for a more structured approach to handling business logic, making it easier to reason about the flow of data and the state of the application.

data/lib/mu/action/version.rb

@@ -2,6 +2,6 @@
 
 module Mu
   module Action
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/mu/action.rb

@@ -7,24 +7,51 @@ module Mu
   # Provides an interactor pattern implementation with hooks, metadata tracking,
   # and result wrapping.
   module Action
+    # Global settings, available as Mu::Action.on_undeclared_failure and so on.
+    module Configuration
+      # How an action handles a failure that its declarations don't allow:
+      # +:raise+ (the default) raises an ArgumentError, while a callable is
+      # called with the action, the error code and the details.
+      attr_reader :on_undeclared_failure
+
+      def on_undeclared_failure=(handler)
+        unless handler == :raise || handler.respond_to?(:call)
+          raise ArgumentError, "on_undeclared_failure must be :raise or respond to #call"
+        end
+
+        @on_undeclared_failure = handler
+      end
+    end
+
+    extend Configuration
+
+    self.on_undeclared_failure = :raise
+
+    # Fiber storage key holding the context of the running action, inherited
+    # by the actions it calls.
+    CONTEXT_KEY = :mu_action_context
+
     def self.included(base)
       base.class_eval do
         extend Literal::Properties
         extend ClassMethods
         include Initializer
+        include FailureChecking
         singleton_class.prepend(MetaPropAdder)
         singleton_class.prepend(HookPropagator)
 
-        attr_reader :meta
+        attr_reader :meta, :context
       end
     end
 
-    # Internal module that automatically adds a meta property to action classes
-    # when they are instantiated. Ensures proper metadata initialization.
+    # Internal module that automatically adds the meta and context properties
+    # to action classes when they are instantiated. Ensures proper metadata
+    # initialization.
     module MetaPropAdder
       def new(...)
         unless @meta_prop_added
-          prop :meta, Hash, default: -> { {} }
+          prop :meta, Hash, default: -> { {} } # steep:ignore UnannotatedEmptyCollection
+          prop :context, _Nilable(_Any), default: -> { Fiber[CONTEXT_KEY] }
           @meta_prop_added = true
         end
         instance = super
@@ -39,25 +66,30 @@ module Mu
       end
     end
 
-    # Internal module that ensures hook arrays are properly duplicated when
-    # action classes are inherited, preventing shared state between classes.
+    # Internal module that ensures hook arrays and failure declarations are
+    # properly duplicated when action classes are inherited, preventing shared
+    # state between classes.
     module HookPropagator
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@before_hooks, before_hooks.dup)
         subclass.instance_variable_set(:@after_hooks, after_hooks.dup)
         subclass.instance_variable_set(:@around_hooks, around_hooks.dup)
+        subclass.instance_variable_set(:@own_failures, own_failures.dup)
+        subclass.instance_variable_set(:@failure_sources, failure_sources.dup)
+        subclass.instance_variable_set(:@props_recording, props_recording)
       end
     end
 
-    # Exception class for action failures. Wraps the original error
-    # and includes metadata for debugging and logging purposes.
+    # Exception class for action failures. Carries the error code and its
+    # details. When raised by +call!+, it also carries the Failure result.
     class FailureError < StandardError
-      attr_reader :error, :meta
+      attr_reader :error, :details, :failure
 
-      def initialize(error, meta: {})
+      def initialize(error, details: {}, failure: nil)
         @error = error
-        @meta = meta
+        @details = details
+        @failure = failure
         super(error)
       end
     end
@@ -65,14 +97,14 @@ module Mu
     # Base result class that wraps action outcomes with success/failure state
     # and metadata. Extended by Success and Failure classes for pattern matching.
     class Result < Literal::Struct
-      prop :meta, Hash, default: -> { {} }
+      prop :meta, Hash, default: -> { {} } # steep:ignore UnannotatedEmptyCollection
 
       attr_reader :meta
     end
 
     # Success result class for pattern matching
     class Success < Result
-      prop :value, _Any, :positional, default: nil
+      prop :value, _Nilable(_Any), :positional
 
       attr_reader :value
 
@@ -82,9 +114,10 @@ module Mu
 
     # Failure result class for pattern matching
     class Failure < Result
-      prop :error, _Any, :positional, default: nil
+      prop :error, _Any, :positional
+      prop :details, Hash, default: -> { {} } # steep:ignore UnannotatedEmptyCollection
 
-      attr_reader :error
+      attr_reader :error, :details
 
       def success? = false
       def failure? = true
@@ -101,19 +134,84 @@ module Mu
       private
 
       def initialize_meta
+        @meta = meta.dup
         meta[:class] = self.class
-        meta[:props] = self.class.literal_properties.to_h do |prop|
-          [prop.name, instance_variable_get(:"@#{prop.name}")]
-        end.except(:meta)
+        props = recorded_props
+        meta[:props] = props if props
+        meta[:context] = context unless context.nil?
+      end
+
+      def recorded_props
+        recording = self.class.props_recording
+        return if recording == false
+
+        props = self.class.literal_properties.to_h do |prop|
+          [prop.name, instance_variable_get(:"@#{prop.name}")] #: [Symbol, untyped]
+        end.except(:meta, :context)
+
+        case recording
+        in { only: } then props.slice(*only)
+        in { except: } then props.except(*except)
+        else props
+        end
+      end
+    end
+
+    # Internal module that builds Failure results and checks failures against
+    # the action's declarations.
+    module FailureChecking
+      private
+
+      def failure_from(exception)
+        cause = exception.failure
+        check_failure(exception.error, exception.details, origin: cause.meta[:class]) if cause
+        # @type var failure_meta: ::Hash[Symbol, untyped]
+        failure_meta = { **meta, failure_error: exception }
+        failure_meta[:cause] = cause if cause
+        Failure.new(exception.error, details: exception.details, meta: failure_meta)
+      end
+
+      def check_failure(error, details, origin: nil)
+        return unless self.class.declares_failures?
+        return if origin && self.class.failure_sources.any? { origin <= _1 }
+
+        problem = failure_problem(error, details)
+        return unless problem
+
+        case (handler = Mu::Action.on_undeclared_failure)
+        when :raise then raise ArgumentError, "#{self.class}: #{problem}"
+        else handler.call(self, error, details)
+        end
+      end
+
+      def failure_problem(error, details)
+        failures = self.class.failures
+        return "undeclared failure #{error.inspect}" unless failures.key?(error)
+
+        types = failures[error]
+        unexpected = details.keys - types.keys
+        return "unexpected details #{unexpected.inspect} for failure #{error.inspect}" if unexpected.any?
+
+        detail_problem(error, types, details)
+      end
+
+      def detail_problem(error, types, details)
+        types.each do |key, type|
+          value = details[key]
+          next if type === value # rubocop:disable Style/CaseEquality
+
+          return "detail #{key.inspect} of failure #{error.inspect} must be #{type.inspect}, got #{value.inspect}"
+        end
+        nil
       end
     end
 
     # Class methods added to action classes when including Mu::Action.
     # Provides hook registration, execution methods, and result type definition.
     module ClassMethods
-      def around(&block) = around_hooks << block
-      def before(&block) = before_hooks << block
-      def after(&block) = after_hooks << block
+      def around(*method_names, &block) = register_hook(around_hooks, method_names, block, name: :around)
+      def before(*method_names, &block) = register_hook(before_hooks, method_names, block, name: :before)
+      def after(*method_names, &block) = register_hook(after_hooks, method_names, block, name: :after)
 
       def around_hooks = (@around_hooks ||= [])
       def before_hooks = (@before_hooks ||= [])
@@ -122,44 +220,136 @@ module Mu
       def call(...) = new(...).run
 
       def call!(...)
-        result = new(...).run!
+        result = new(...).run
         case result
         in Success(value:)
           value
-        in Failure(meta: { failure_error: })
-          raise failure_error
+        in Failure(error:, details:, meta:)
+          raise FailureError.new(error, details:, failure: result), cause: meta[:failure_error]
         else
           result
         end
       end
 
+      # Chooses which props are recorded in meta[:props]: all of them (the
+      # default), none, or a subset.
+      #
+      #   record_props false
+      #   record_props only: %i[site_id]
+      #   record_props except: %i[payload]
+      def record_props(enabled = true, only: nil, except: nil) # rubocop:disable Style/OptionalBooleanParameter
+        @props_recording = build_props_recording(enabled, only, except)
+      end
+
+      def props_recording = (defined?(@props_recording) ? @props_recording : true)
+
+      # Declares the failures this action can return. Once an action declares
+      # any, other failures are handled by Mu::Action.on_undeclared_failure.
+      #
+      #   failure :site_disabled
+      #   failure :invalid, errors: ActiveModel::Errors
+      #   failure from: OtherAction
+      def failure(*codes, from: nil, **details)
+        raise ArgumentError, "failure requires a code or from:" if codes.empty? && !from
+        raise ArgumentError, "details can only be declared for a single failure" if codes.size > 1 && details.any?
+
+        codes.each { own_failures[_1] = details }
+        failure_sources.concat(Array(from))
+      end
+
+      # The declared failures, including those of the +from:+ actions,
+      # as a hash of error code to details types.
+      def failures
+        failure_sources.map(&:failures).reduce({}, :merge).merge(own_failures)
+      end
+
+      def declares_failures? = own_failures.any? || failure_sources.any?
+      def own_failures = (@own_failures ||= {})
+      def failure_sources = (@failure_sources ||= [])
+
       def result(type)
         success_class = Class.new(::Mu::Action::Success) do
-          prop :value, type, :positional, default: nil
+          # @type self: singleton(::Mu::Action::Success)
+          prop :value, type, :positional
         end
 
         const_set(:Success, success_class)
       end
+
+      private
+
+      def build_props_recording(enabled, only, except)
+        raise ArgumentError, "record_props accepts only: or except:, not both" if only && except
+
+        # @type var filter: ::Hash[Symbol, ::Array[Symbol]]
+        filter = { only:, except: }.compact.transform_values { Array(_1) }
+        return filter.empty? || filter if enabled
+        raise ArgumentError, "record_props false accepts no only: or except:" if filter.any?
+
+        false
+      end
+
+      def register_hook(collection, method_names, block, name:)
+        ensure_valid_hook_inputs(method_names, block, name:)
+        additions = normalize_hook_inputs(method_names, block, name:)
+        collection.concat(additions)
+      end
+
+      def normalize_hook_inputs(method_names, block, name:)
+        if block
+          [block]
+        else
+          symbolize_hook_names(method_names, name:)
+        end
+      end
+
+      def ensure_valid_hook_inputs(method_names, block, name:)
+        return unless block && method_names.any?
+
+        raise ArgumentError, "#{name} hooks accept either a block or method names, not both"
+      end
+
+      def symbolize_hook_names(method_names, name:)
+        raise ArgumentError, "#{name} hook requires a block or method name" if method_names.empty?
+
+        method_names.map do |method_name|
+          unless method_name.respond_to?(:to_sym)
+            raise ArgumentError, "Invalid #{name} hook identifier: #{method_name.inspect}"
+          end
+
+          method_name.to_sym
+        end
+      end
     end
 
     # rubocop:disable Naming/MethodName
-    def Success(value) = self.class.const_get(:Success).new(value, meta:)
-    def Failure(error, **meta) = raise FailureError.new(error, meta:)
+    def Success(value = nil) = self.class.const_get(:Success).new(value, meta:)
+
+    def Failure(error, **details)
+      check_failure(error, details)
+      raise FailureError.new(error, details:)
+    end
     # rubocop:enable Naming/MethodName
 
     def run
       run!
     rescue FailureError => e
-      Failure.new(e.error, meta: { failure_error: e, **meta, **e.meta })
+      failure_from(e)
     end
 
     def run!
-      with_hooks { call }
+      with_context { with_hooks { call } }
     end
 
     protected
 
-    def result_class = self.class.const_get(:Result)
+    def with_context
+      previous = Fiber[CONTEXT_KEY]
+      Fiber[CONTEXT_KEY] = context
+      yield
+    ensure
+      Fiber[CONTEXT_KEY] = previous
+    end
 
     def with_hooks(&)
       run_before_hooks
@@ -171,18 +361,60 @@ module Mu
 
     private
 
-    def run_before_hooks = self.class.before_hooks.each { instance_exec(&_1) }
-    def run_after_hooks = self.class.after_hooks.each { instance_exec(&_1) }
+    def run_before_hooks = self.class.before_hooks.each { execute_simple_hook(_1) }
+    def run_after_hooks = self.class.after_hooks.each { execute_simple_hook(_1) }
 
     def build_around_chain(&block)
       chain = block
       self.class.around_hooks.reverse_each do |hook|
         previous = chain
-        chain = -> { instance_exec(self, previous, &hook) }
+        chain = build_around_wrapper(hook, previous)
       end
       chain
     end
 
+    def execute_simple_hook(hook)
+      if hook.is_a?(Proc)
+        # @type var hook: ^(*untyped) -> untyped
+        return instance_exec(&hook)
+      end
+
+      send(hook)
+    end
+
+    def build_around_wrapper(hook, previous)
+      case hook
+      when Proc
+        lambda do
+          # @type var hook: ^(*untyped) -> untyped
+          instance_exec(self, previous, &hook)
+        end
+      else
+        -> { invoke_around_method(hook, previous) }
+      end
+    end
+
+    def invoke_around_method(hook, previous)
+      method_name = hook.to_sym
+      method_object = resolve_method(method_name)
+      arguments = around_arguments(method_object, previous)
+      method_object.bind(self).call(*arguments, &previous)
+    end
+
+    def around_arguments(method_object, previous)
+      params = method_object.parameters.reject { _1.first == :block }
+      return [] if params.empty?
+      return [previous] if params.length == 1
+
+      [self, previous]
+    end
+
+    def resolve_method(method_name)
+      self.class.instance_method(method_name)
+    rescue NameError
+      raise NoMethodError, "Undefined hook method ##{method_name} for #{self.class}"
+    end
+
     def call
       raise NotImplementedError, "You must implement the call method"
     end

data/sig/mu/action.rbs

@@ -1,6 +1,159 @@
 module Mu
   module Action
-    VERSION: String
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    include Kernel
+
+    VERSION: ::String
+
+    CONTEXT_KEY: Symbol
+
+    type failure_handler = :raise | ^(untyped action, untyped error, ::Hash[Symbol, untyped] details) -> untyped
+    type props_recording = bool | ::Hash[Symbol, ::Array[Symbol]]
+
+    module Configuration : Kernel
+      @on_undeclared_failure: failure_handler
+
+      def on_undeclared_failure: () -> failure_handler
+      def on_undeclared_failure=: (failure_handler handler) -> failure_handler
+    end
+
+    extend Configuration
+    attr_reader meta: ::Hash[untyped, untyped]
+    attr_reader context: untyped
+
+    interface _ActionInstance
+      def meta: () -> ::Hash[untyped, untyped]
+      def context: () -> untyped
+      def class: () -> _ActionClass
+      def run: () -> ::Mu::Action::Result
+      def run!: () -> ::Mu::Action::Result
+    end
+
+    interface _ActionClass
+      def literal_properties: () -> ::Array[untyped]
+      def before_hooks: () -> ::Array[untyped]
+      def after_hooks: () -> ::Array[untyped]
+      def around_hooks: () -> ::Array[untyped]
+      def declares_failures?: () -> bool
+      def failures: () -> ::Hash[untyped, ::Hash[Symbol, untyped]]
+      def failure_sources: () -> ::Array[_ActionClass]
+      def props_recording: () -> props_recording
+      def const_get: (Symbol) -> ::Class
+      def instance_method: (Symbol) -> UnboundMethod
+      def new: (*untyped, **untyped) -> _ActionInstance
+    end
+
+    def self.included: (untyped base) -> void
+    def self.before_hooks: () -> ::Array[untyped]
+    def self.after_hooks: () -> ::Array[untyped]
+    def self.around_hooks: () -> ::Array[untyped]
+
+    module MetaPropAdder
+      include Literal::Properties
+
+      def new: (*untyped, **untyped) -> untyped
+      def inherited: (untyped subclass) -> void
+    end
+
+    module HookPropagator
+      def inherited: (untyped subclass) -> void
+      def before_hooks: () -> ::Array[untyped]
+      def after_hooks: () -> ::Array[untyped]
+      def around_hooks: () -> ::Array[untyped]
+      def own_failures: () -> ::Hash[untyped, ::Hash[Symbol, untyped]]
+      def failure_sources: () -> ::Array[_ActionClass]
+      def props_recording: () -> props_recording
+    end
+
+    class FailureError < StandardError
+      attr_reader error: untyped
+      attr_reader details: ::Hash[Symbol, untyped]
+      attr_reader failure: Failure?
+
+      def initialize: (untyped error, ?details: ::Hash[Symbol, untyped], ?failure: Failure?) -> void
+    end
+
+    class Result < Literal::Struct
+      attr_reader meta: ::Hash[untyped, untyped]
+
+      def initialize: (*untyped, **untyped) -> void
+    end
+
+    class Success < Result
+      attr_reader value: untyped
+
+      def initialize: (*untyped, **untyped) -> void
+      def success?: () -> true
+      def failure?: () -> false
+    end
+
+    class Failure < Result
+      attr_reader error: untyped
+      attr_reader details: ::Hash[Symbol, untyped]
+
+      def initialize: (*untyped, **untyped) -> void
+      def success?: () -> false
+      def failure?: () -> true
+    end
+
+    module Initializer : _ActionInstance
+      @meta: ::Hash[untyped, untyped]
+
+      def initialize: (*untyped, **untyped) -> void
+      def initialize_meta: () -> void
+      def recorded_props: () -> ::Hash[Symbol, untyped]?
+    end
+
+    module FailureChecking : _ActionInstance
+      def failure_from: (FailureError exception) -> Failure
+      def check_failure: (untyped error, ::Hash[Symbol, untyped] details, ?origin: untyped) -> void
+      def failure_problem: (untyped error, ::Hash[Symbol, untyped] details) -> ::String?
+      def detail_problem: (untyped error, ::Hash[Symbol, untyped] types, ::Hash[Symbol, untyped] details) -> ::String?
+    end
+
+    module ClassMethods
+      include Literal::Properties
+
+      def around: (*Symbol) ?{ (*untyped) -> untyped } -> ::Array[untyped]
+      def before: (*Symbol) ?{ (*untyped) -> untyped } -> ::Array[untyped]
+      def after: (*Symbol) ?{ (*untyped) -> untyped } -> ::Array[untyped]
+      def around_hooks: () -> ::Array[untyped]
+      def before_hooks: () -> ::Array[untyped]
+      def after_hooks: () -> ::Array[untyped]
+      def call: (*untyped, **untyped) -> untyped
+      def call!: (*untyped, **untyped) -> untyped
+      def result: (untyped type) -> ::Class
+      def failure: (*untyped codes, ?from: untyped, **untyped details) -> ::Array[_ActionClass]
+      def failures: () -> ::Hash[untyped, ::Hash[Symbol, untyped]]
+      def declares_failures?: () -> bool
+      def own_failures: () -> ::Hash[untyped, ::Hash[Symbol, untyped]]
+      def failure_sources: () -> ::Array[_ActionClass]
+      def record_props: (?bool enabled, ?only: (Symbol | ::Array[Symbol])?, ?except: (Symbol | ::Array[Symbol])?) -> props_recording
+      def props_recording: () -> props_recording
+      def build_props_recording: (bool enabled, (Symbol | ::Array[Symbol])? only, (Symbol | ::Array[Symbol])? except) -> props_recording
+      def register_hook: (untyped collection, untyped method_names, ::Proc? block, name: Symbol) -> untyped
+      def normalize_hook_inputs: (untyped method_names, ::Proc? block, name: Symbol) -> untyped
+      def ensure_valid_hook_inputs: (untyped method_names, ::Proc? block, name: Symbol) -> void
+      def symbolize_hook_names: (untyped method_names, name: Symbol) -> ::Array[Symbol]
+      def const_set: (Symbol, ::Class) -> ::Class
+      def new: (*untyped, **untyped) -> _ActionInstance
+    end
+
+    def Success: (?untyped value) -> Success
+    def Failure: (untyped error, **untyped) -> bot
+    def run: () -> Result
+    def run!: () -> Result
+    def with_context: [T] () { () -> T } -> T
+    def failure_from: (FailureError exception) -> Failure
+    def check_failure: (untyped error, ::Hash[Symbol, untyped] details, ?origin: untyped) -> void
+    def with_hooks: () { () -> Result } -> Result
+    def run_before_hooks: () -> ::Array[untyped]
+    def run_after_hooks: () -> ::Array[untyped]
+    def build_around_chain: () { () -> Result } -> ::Proc
+    def execute_simple_hook: (::Proc | ::Symbol) -> untyped
+    def build_around_wrapper: ((::Proc | ::Symbol), ::Proc) -> ::Proc
+    def invoke_around_method: (::Symbol, ::Proc) -> untyped
+    def around_arguments: (UnboundMethod, ::Proc) -> ::Array[untyped]
+    def resolve_method: (Symbol) -> UnboundMethod
+    def call: () -> untyped
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mu-action
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nicolas Buduroi
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: literal
@@ -32,15 +31,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
 - CHANGELOG.md
-- CLAUDE.md
-- CODE_OF_CONDUCT.md
-- Guardfile
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/mu/action.rb
 - lib/mu/action/version.rb
 - sig/mu/action.rbs
@@ -49,11 +42,9 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/budu/mu-action
   source_code_uri: https://github.com/budu/mu-action
   changelog_uri: https://github.com/budu/mu-action/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -61,15 +52,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Modern interactor pattern with type safety and metadata tracking
 test_files: []

data/.rspec

@@ -1,2 +0,0 @@
---color
---require spec_helper

data/.rubocop.yml

@@ -1,20 +0,0 @@
-AllCops:
-  NewCops: enable
-  TargetRubyVersion: 3.1
-  Exclude:
-    - readme_examples.rb
-
-Metrics/BlockLength:
-  AllowedMethods:
-    - configure
-    - context
-    - define
-    - describe
-    - guard
-    - shared_examples
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes

data/CLAUDE.md

@@ -1,35 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Development Commands
-
-- **Run tests**: `bundle exec rspec`
-- **Run linting**: `bundle exec rubocop`
-- **Run all checks**: `rake` (runs both spec and rubocop)
-- **Interactive console**: `bin/console`
-- **Install gem locally**: `bundle exec rake install`
-- **Setup development environment**: `bin/setup`
-
-## Architecture Overview
-
-This is a Ruby gem that provides an interactor pattern implementation
-using the Literal gem for properties and type checking. The core module
-`Mu::Action` is designed to be included in classes to provide:
-
-### Core Concepts
-
-- Actions are classes that include `Mu::Action` and implement a `call` method
-- Actions can be executed via `MyAction.call(...)` or `MyAction.call!(...)`
-- Results are wrapped in `Result` objects with success/failure state and metadata
-- Hooks allow for cross-cutting concerns and middleware-like behavior
-- Properties are automatically tracked in metadata for debugging/logging
-
-### Dependencies
-
-- **literal**: Core dependency for properties and type system
-- **rspec**: Testing framework
-- **rubocop**: Code linting and style enforcement
-
-The gem follows standard Ruby gem conventions with lib/, spec/, and bin/
-directories.

data/CODE_OF_CONDUCT.md

@@ -1,132 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-  community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
-  without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official email address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations

data/Guardfile

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-guard :rspec, cmd: "bundle exec rspec" do
-  require "guard/rspec/dsl"
-  dsl = Guard::RSpec::Dsl.new(self)
-
-  # Ruby files
-  ruby = dsl.ruby
-  dsl.watch_spec_files_for(ruby.lib_files)
-
-  # RSpec files
-  rspec = dsl.rspec
-  watch(rspec.spec_helper) { rspec.spec_dir }
-  watch(rspec.spec_support) { rspec.spec_dir }
-  watch(rspec.spec_files)
-
-  # Watch lib files
-  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
-  watch(%r{^lib/mu/action/(.+)\.rb$}) { "spec/mu/action_spec.rb" }
-  watch(%r{^lib/mu/action\.rb$}) { Dir["spec/*"] }
-end
-
-guard :rubocop, cli: "--format progress" do
-  watch(/.+\.rb$/)
-  watch(%r{(?:.+/)?\.rubocop(?:_todo)?\.yml$}) { |m| File.dirname(m[0]) }
-end

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]