mu-action 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5765a5a8a0a0af6628f4b36d5e7dde4337eb44ed1e44275208b151276d4de412
-  data.tar.gz: 6c906cf41b59a6fde0b7b4482d3029fca4a48f2767a4958f0d9d54a9ed661d79
+  metadata.gz: 261d73076a857c43d7c68e5c3585cb3e96d693d54ed104b33abd6a6e897272fd
+  data.tar.gz: 9a0ac5c6592b3a2715918da63f88d8fec4b45dc6111547e1a545d6a26553e47e
 SHA512:
-  metadata.gz: 9c6f9145debfaee371e5330f8922d8739489358e5aaf7aa6d6d4f5ab1c445a880725a9314d3bf1d7ceddc1b9209a41ac68638dc9aba40985280d295f08250468
-  data.tar.gz: 6a5b5a71d34add535fcb0672963a99c8414e8038776d376cc04bb81c8bc9d7fbe68561a7c2f7ef5ab10740ddaf02b6348bd85e9c8f8fedd7afd32e4e2126bd14
+  metadata.gz: ef960929df4e5a7daa07544be3af52a5a952185959fbcc3a21329145e7e465c3f798ff46c0c382f4c63310fbfd3aa611e3e742f506fcbec949b80ebd1463adc4
+  data.tar.gz: 75a8de3adbc5dbaf4302f233c9314bedf009c5aebd4b12b32422a790a989e75073aaffc8303bc124e2c058b36ae88cd63b1bf37b7ed6edc84cda42fc5ab02b55

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [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

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.
 
@@ -199,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:
@@ -212,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.2.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: -> { {} } # 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
@@ -72,7 +104,7 @@ module Mu
 
     # 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,10 +134,75 @@ 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
 
@@ -122,20 +220,57 @@ 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)
@@ -143,6 +278,17 @@ module Mu
 
       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:)
@@ -177,23 +323,33 @@ module Mu
     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

data/sig/mu/action.rbs

@@ -3,10 +3,26 @@ module Mu
     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
@@ -17,6 +33,10 @@ module Mu
       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
@@ -39,13 +59,17 @@ module Mu
       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 meta: ::Hash[untyped, untyped]
+      attr_reader details: ::Hash[Symbol, untyped]
+      attr_reader failure: Failure?
 
-      def initialize: (untyped error, ?meta: ::Hash[untyped, untyped]) -> void
+      def initialize: (untyped error, ?details: ::Hash[Symbol, untyped], ?failure: Failure?) -> void
     end
 
     class Result < Literal::Struct
@@ -64,17 +88,26 @@ module Mu
 
     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
+    module Initializer : _ActionInstance
+      @meta: ::Hash[untyped, untyped]
+
       def initialize: (*untyped, **untyped) -> void
       def initialize_meta: () -> void
-      def meta: () -> ::Hash[untyped, untyped]
-      def self.literal_properties: () -> ::Array[untyped]
+      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
@@ -89,6 +122,14 @@ module Mu
       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
@@ -97,11 +138,13 @@ module Mu
       def new: (*untyped, **untyped) -> _ActionInstance
     end
 
-    def Success: (untyped value) -> Success
+    def Success: (?untyped value) -> Success
     def Failure: (untyped error, **untyped) -> bot
     def run: () -> Result
     def run!: () -> Result
-    def result_class: () -> ::Class
+    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]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mu-action
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nicolas Buduroi
@@ -31,29 +31,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
-- AGENTS.md
 - CHANGELOG.md
-- CLAUDE.md
-- CODE_OF_CONDUCT.md
-- Guardfile
 - LICENSE.txt
 - README.md
-- Rakefile
-- Steepfile
-- lib/guard/steep.rb
 - lib/mu/action.rb
 - lib/mu/action/version.rb
-- sig/kernel.rbs
-- sig/literal.rbs
 - sig/mu/action.rbs
 homepage: https://github.com/budu/mu-action
 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'
@@ -64,14 +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.7.2
+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/AGENTS.md

@@ -1,32 +0,0 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- `lib/mu/action` holds the core interactor implementation; mirror this layout when adding new components so `lib/mu/action/foo.rb` pairs with `Mu::Action::Foo`.
-- `spec/` mirrors the library structure with RSpec examples; add a matching `_spec.rb` file for every public entry point.
-- `sig/` provides RBS signatures that keep types honest—update them alongside code changes.
-- `bin/` hosts contributor tooling (`check`, `console`, `test_readme_examples`); treat `readme_examples.rb` as generated output.
-
-## Build, Test, and Development Commands
-- `bin/check` aggregates lint, spec, and README example runs for a pre-PR smoke test. Use this instead of `rake`.
-- `bundle exec rspec spec/mu/action/hook_spec.rb` executes targeted tests; leave focused specs checked in only when necessary.
-- `bundle exec rubocop` enforces style; let it guide formatting instead of manual tweaks.
-- `bundle exec steep check` validates Steep signatures against implementation.
-- `bin/test_readme_examples --extract-only` regenerates `readme_examples.rb` after documentation updates.
-
-## Coding Style & Naming Conventions
-- Target Ruby 3.1 with two-space indentation and trailing commas only when required.
-- RuboCop enforces double-quoted strings and general style—prefer fixes via `bundle exec rubocop -A` over manual edits.
-- Match class and module names to their file paths (e.g., `Mu::Action::Result` lives in `lib/mu/action/result.rb`), and keep method names snake_case verbs.
-- Favor small, composable interactors with explicit `prop` declarations and `Success`/`Failure` returns to stay idiomatic.
-
-## Testing Guidelines
-- Write RSpec examples that describe observable behavior; structure files as `describe Mu::Action::Feature` with nested `context` blocks.
-- Cover both success and failure branches, including metadata expectations when hooks mutate state.
-- Keep factories lightweight—inline doubles or `let` helpers beat global fixtures for clarity.
-- Run `bundle exec rspec` locally and ensure README examples still execute via `bin/check` whenever documentation changes.
-
-## Commit & Pull Request Guidelines
-- Follow the existing Conventional Commit style (`feat:`, `chore:`, `docs:`) visible in `git log --oneline`.
-- Keep commits scoped to a single concern and include any signature or README updates in the same change.
-- Open pull requests with a brief summary, linked issues (if any), and mention any developer-facing changes or new scripts.
-- State that `bin/check` passes; add screenshots or console snippets only when behavior changes are user-visible.

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,34 +0,0 @@
-# frozen_string_literal: true
-
-require "guard/steep"
-
-guard :rubocop, cli: "--format progress" do
-  watch(/.+\.rb$/)
-  watch(%r{(?:.+/)?\.rubocop(?:_todo)?\.yml$}) { File.dirname(_1[0]) }
-end
-
-guard :steep, command: "bundle exec steep check" do
-  watch("Steepfile")
-  watch(%r{^sig/.+\.rbs$})
-  watch(%r{^lib/.+\.rb$})
-end
-
-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

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]

data/Steepfile

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-target :lib do
-  signature "sig"
-  check "lib"
-
-  configure_code_diagnostics(Steep::Diagnostic::Ruby.default)
-end

data/lib/guard/steep.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-require "guard/plugin"
-
-# steep:ignore:start
-module Guard
-  # Guard plugin that runs Steep type checking whenever files change.
-  class Steep < Plugin
-    def initialize(options = {})
-      super
-      @command = options.fetch(:command, "bundle exec steep check")
-    end
-
-    def start = run_steep
-    def run_all = run_steep
-    def run_on_additions(_paths) = run_steep
-    def run_on_modifications(_paths) = run_steep
-    def run_on_removals(_paths) = run_steep
-
-    private
-
-    def run_steep
-      UI.info "📐 Running Steep..."
-      success = system(@command)
-      UI.error "Steep check failed" unless success
-    end
-  end
-end
-# steep:ignore:end

data/sig/kernel.rbs

@@ -1,3 +0,0 @@
-module Kernel
-  def instance_exec: (*untyped) { (*untyped) -> untyped } -> untyped
-end

data/sig/literal.rbs

@@ -1,13 +0,0 @@
-module Literal
-  module Properties
-    def prop: (Symbol, untyped, *untyped, ?default: untyped) -> untyped
-    def _Any: () -> untyped
-  end
-
-  class Struct
-    extend Properties
-
-    def self.prop: (Symbol, untyped, *untyped, ?default: untyped) -> untyped
-    def self.literal_properties: () -> ::Array[untyped]
-  end
-end