spree_core 6.0.0.rc2 → 6.0.0.rc4

data/lib/spree/agent_tools/registry.rb

@@ -0,0 +1,131 @@
+module Spree
+  module AgentTools
+    # The agent-tool registry. One per surface, the way the authentication
+    # strategies are split — {Spree.admin_agent_tools} for the back office,
+    # {Spree.store_agent_tools} for the storefront. Extensions append their
+    # own tool classes the same way they register tax or delivery-rate
+    # providers:
+    #
+    #   Spree.admin_agent_tools << MyApp::AgentTools::SyncSupplier
+    #
+    # Registration is by class, so one registry serves every adapter on its
+    # surface: the MCP server and the dashboard assistant both read the admin
+    # one.
+    #
+    # A tool also declares the surface it belongs to, so filing one in the
+    # wrong registry is refused rather than discovered when a storefront
+    # visitor is offered the back office. Ten admin tools carry no permission
+    # of their own — they are gated per resource instead — so the registry
+    # cannot be the only thing keeping them apart.
+    #
+    # Writes are not registered as classes. A back-office write already is a
+    # workflow, so the registry exposes workflows by their `Spree::Dependencies`
+    # key and derives each tool from the workflow's own `perform` signature —
+    # see {#expose_workflows}.
+    class Registry
+      include Enumerable
+
+      # @return [Symbol] the surface this registry serves
+      attr_reader :audience
+
+      def initialize(tool_names = [], audience: :admin)
+        @tool_names = tool_names.map(&:to_s)
+        @exposed_workflows = {}
+        @audience = audience.to_sym
+      end
+
+      # Registered by name, resolved on use.
+      #
+      # Holding the class itself would pin the copy loaded at boot, so in
+      # development every edit to a tool's description, params or permission
+      # needed a restart to take effect — and tuning those descriptions is how
+      # an agent's behaviour is shaped. Names survive reloading, which is the
+      # same reason `Spree.integrations` stores strings.
+      #
+      # @param tool_class [Class<Spree::AgentTool>, String]
+      # @return [self]
+      def <<(tool_class)
+        name = tool_class.to_s
+        declared = tool_class.try(:audience)
+        if declared && declared != audience
+          raise ArgumentError,
+                "#{name} belongs to the #{declared} surface and cannot be registered on the #{audience} one"
+        end
+
+        @tool_names << name unless @tool_names.include?(name)
+        self
+      end
+      alias add <<
+
+      def each(&)
+        to_a.each(&)
+      end
+
+      # Exposes workflows as write tools, keyed by `Spree::Dependencies` key so
+      # the tool follows whatever class the host app has registered:
+      #
+      #   Spree.admin_agent_tools.expose_workflows(
+      #     order_cancel_workflow: 'write_orders',
+      #     product_activate_workflow: 'write_products'
+      #   )
+      #
+      # A value may be the permission key on its own, or a hash carrying it
+      # alongside `except:` (parameters to hide, such as a deprecated one) and
+      # `summary:` (a callable overriding the generated confirmation line).
+      #
+      # @param exposures [Hash{Symbol => String, Hash}]
+      # @return [self]
+      def expose_workflows(**exposures)
+        exposures.each do |dependency_key, options|
+          options = { permission: options } if options.is_a?(String) || options.is_a?(Symbol)
+          @exposed_workflows[dependency_key.to_sym] = {
+            permission: options.fetch(:permission).to_s,
+            except: Array(options[:except]).map(&:to_sym),
+            summary: options[:summary]
+          }
+        end
+        self
+      end
+
+      # @return [Hash{Symbol => Hash}] every exposed workflow, by dependency key
+      attr_reader :exposed_workflows
+
+      # @return [Array<Class<Spree::AgentTool>>]
+      def to_a
+        registered_classes + workflow_tool_classes
+      end
+
+      # Tools this caller may actually use, instantiated for their context.
+      # This is what an adapter offers the model — a caller without
+      # `write_products` never learns that a price-changing tool exists.
+      #
+      # @param context [Spree::AgentTools::Context]
+      # @return [Array<Spree::AgentTool>]
+      def available_for(context)
+        to_a.
+          select { |tool_class| tool_class.try(:audience).nil? || tool_class.audience == audience }.
+          map { |tool_class| tool_class.new(context) }.
+          select(&:permitted?)
+      end
+
+      private
+
+      def registered_classes
+        @tool_names.filter_map do |name|
+          name.safe_constantize.tap do |klass|
+            Rails.logger.warn("[Spree] registered agent tool #{name} does not exist") if klass.nil?
+          end
+        end
+      end
+
+      # One generated tool class per exposed workflow whose dependency key
+      # still resolves. A key an extension removed simply stops being offered
+      # rather than breaking the whole catalog.
+      def workflow_tool_classes
+        @exposed_workflows.filter_map do |dependency_key, options|
+          Spree::AgentTools::WorkflowTool.for(dependency_key, **options)
+        end
+      end
+    end
+  end
+end

data/lib/spree/agent_tools/resource_map.rb

@@ -0,0 +1,352 @@
+module Spree
+  module AgentTools
+    # What the generic tools are allowed to look at.
+    #
+    # Not a hand-written list: the Admin API's controllers already declare
+    # their model, serializer and permission scope, so the map is derived from
+    # them — `spree_api` registers one entry per admin resource controller
+    # after the classes load. Core owns the structure and the refusal below;
+    # a resource no controller serves is not reachable by any agent.
+    #
+    # Permissions therefore mirror the controllers by construction rather than
+    # by convention: the catalog has no `read_price_lists`, and the price-lists
+    # controller rides `read_products`, so the derived entry does too.
+    class ResourceMap
+      # A registered resource whose model has no store scoping. Raised rather
+      # than quietly leaking another store's records.
+      UnscopedResourceError = Class.new(StandardError)
+
+      Entry = Struct.new(:key, :model_name, :permission, :serializer_name,
+                         :dashboard_path, :scope_name, :write_permission,
+                         :writable_attributes, :create_workflow_key, :update_workflow_key,
+                         :distinct, :api_paths, keyword_init: true) do
+        # The Admin API path for one of this resource's operations, which is
+        # how a tool reaches it.
+        #
+        # @param action [Symbol] :index, :show, :create, :update, :destroy
+        # @return [String, nil]
+        def api_path(action)
+          Array(api_paths).to_h[action.to_sym]
+        end
+
+        # @return [Boolean] whether a tool can dispatch to this resource
+        def dispatchable?
+          api_path(:index).present?
+        end
+
+        # Whether a search may add DISTINCT.
+        #
+        # Postgres rejects SELECT DISTINCT beside an ORDER BY the select list
+        # does not carry, which is why some controllers turn it off. Carried
+        # from the controller rather than decided here, so a resource that
+        # changes its mind is followed without a second list to maintain.
+        #
+        # @return [Boolean]
+        def distinct?
+          distinct.nil? ? true : distinct
+        end
+
+        # Whether the generic write tools may touch this resource.
+        #
+        # A declared workflow no longer excludes it: the generic writes
+        # dispatch to the controller, which runs its own workflow, so there
+        # is still exactly one way to write each thing and this is it.
+        # What is left to answer is whether the endpoint accepts a body at
+        # all.
+        #
+        # @return [Boolean]
+        def generic_writes?
+          write_permission.present?
+        end
+
+        # The attributes the Admin API would accept on a write, so the generic
+        # tools offer exactly the same surface as the endpoint.
+        #
+        # @return [Array<String>]
+        def writable_attribute_names
+          Array(writable_attributes).map(&:to_s).sort
+        end
+
+        # The associations the show operation will include when asked, read
+        # from the serializer that renders it.
+        #
+        # A record's associations are left out by default because a full
+        # admin payload is more than a model's context should hold. Without
+        # knowing the names, a model cannot ask for the one it needs — it
+        # fetched a product and saw no variants at all.
+        #
+        # @return [Array<String>]
+        def expandable_associations
+          @expandable_associations ||= begin
+            # Walked up the chain rather than read off one file: a serializer
+            # inherits most of its conditional associations from the Store
+            # API one it extends.
+            classes = Array(serializer_class&.ancestors).select do |ancestor|
+              ancestor.is_a?(Class) && ancestor.name.to_s.include?('Serializer')
+            end
+
+            classes.flat_map { |klass| expand_names_in(klass) }.uniq.sort
+          rescue StandardError
+            []
+          end
+        end
+
+        def expand_names_in(klass)
+          file = Object.const_source_location(klass.name)&.first
+          return [] if file.nil? || !File.exist?(file)
+
+          File.read(file).scan(/expand\?\('([a-z_]+)'\)/).flatten
+        rescue StandardError
+          []
+        end
+
+        # The shape of each attribute that carries a list of records — a
+        # product's `variants`, an order's `items`.
+        #
+        # A model that is only told the key exists sends the records one at a
+        # time to their own endpoints instead, which costs several round trips
+        # and, where the parent reconciles its list, leaves behind whatever
+        # the first write created.
+        #
+        # @return [Hash{String => Array<String>}] attribute => the keys of one row
+        def nested_collection_shapes
+          return {} unless defined?(Spree::Api::AgentWriteSchemas)
+
+          Spree::Api::AgentWriteSchemas.for(key).each_with_object({}) do |(name, schema), shapes|
+            next unless schema.is_a?(Hash) && schema['type'] == 'array'
+
+            # A row's shape is published as a component too, so the array
+            # points at one rather than describing its items inline.
+            row = Spree::Api::AgentWriteSchemas.resolve_schema(schema['items'])
+            properties = row&.dig('properties')
+            next unless properties.is_a?(Hash) && properties.any?
+
+            # Names alone left an agent to guess: it sent a number where the
+            # endpoint wanted a decimal string, and omitted a field the model
+            # requires, learning both from a 422. The type and the
+            # requirement are already in the published schema.
+            required = Array(row['required'])
+            shapes[name.to_s] = properties.keys.sort.map do |field|
+              { 'name' => field,
+                'type' => properties.dig(field, 'type'),
+                'required' => required.include?(field) }
+            end
+          end
+        rescue StandardError
+          {}
+        end
+        # Where this record lives in the dashboard, so an answer links to it
+        # rather than describing where to look. Store-relative — the panel
+        # prefixes the current store segment.
+        #
+        # @param record [ActiveRecord::Base]
+        # @return [String, nil]
+        def dashboard_path_for(record)
+          return if dashboard_path.blank?
+
+          format(dashboard_path, id: record.prefixed_id)
+        end
+
+        # @return [Class]
+        def model_class
+          model_name.constantize
+        end
+
+        # Records of this kind the asking admin may see.
+        #
+        # Takes the context rather than the store so the ability filter cannot
+        # be skipped by forgetting to apply it: store scoping answers tenancy,
+        # `accessible` answers which records within that tenant — the same two
+        # steps an Admin API controller takes.
+        #
+        # @param context [Spree::AgentTools::Context]
+        # @param action [Symbol]
+        # @return [ActiveRecord::Relation]
+        def scope_for(context, action = :show)
+          relation = model_class.for_store(context.store)
+
+          # `Spree::Base.for_store` falls back to the bare class when a model
+          # has no matching Store association, returning EVERY store's rows.
+          # A model that defines its own `for_store` has made a deliberate
+          # choice (customers are global by design, and Spree::Customer says
+          # so); inheriting the fallback is an accident. Only the accident is
+          # refused, because serving another store's records to an assistant
+          # that reads them aloud is worse than a missing resource.
+          if model_class.method(:for_store).owner == Spree::Base.singleton_class && relation.equal?(model_class)
+            raise UnscopedResourceError, key
+          end
+
+          # A resource that is a slice of a model rather than the whole of it
+          # (draft orders among orders) narrows further.
+          relation = relation.public_send(scope_name) if scope_name.present?
+
+          context.accessible(relation, action)
+        end
+
+        # Whether this resource's scoping is deliberate — either a real
+        # store relation, or a model that owns its `for_store` and has decided
+        # it is global.
+        #
+        # @return [Boolean]
+        def store_scoped?
+          model_class.method(:for_store).owner != Spree::Base.singleton_class ||
+            !model_class.for_store(Spree::Store.new).equal?(model_class)
+        rescue StandardError
+          false
+        end
+
+        # @return [Class] the admin serializer for this resource
+        def serializer_class
+          serializer_name.constantize
+        end
+
+        # Fields the model actually allows filtering and sorting on. Reused from
+        # the model's own Ransack allowlist so the assistant can never query a
+        # field the API would refuse.
+        #
+        # @return [Array<String>]
+        def filterable_fields
+          model_class.ransackable_attributes.sort
+        end
+
+        # Named queries the model exposes — `in_stock`, `out_of_stock`,
+        # `price_lte` and so on. These answer the questions merchants actually
+        # ask ("what's out of stock?") and cannot be expressed as an attribute
+        # filter, because the answer lives across stock levels rather than in a
+        # column. Passed as bare keys rather than `field_predicate` pairs.
+        #
+        # @return [Array<String>]
+        def filterable_scopes
+          model_class.ransackable_scopes.map(&:to_s).sort
+        end
+      end
+
+
+      class << self
+        # How the map fills itself the first time it is read. `spree_api` sets
+        # this to its controller walk; core owns only the structure, so an
+        # installation without the API engine simply has an empty map.
+        #
+        # @return [#call, nil]
+        attr_accessor :deriver
+
+        # @return [Array<Entry>] every registered resource, in registration order
+        def all
+          derive!
+          entries.values
+        end
+
+        # Registers one resource. Called by `spree_api` for each admin resource
+        # controller; an extension with its own admin controller is picked up
+        # by the same walk, so nothing registers by hand.
+        #
+        # Re-registering a key replaces it, because the walk runs again on every
+        # code reload in development.
+        #
+        # @param key [String, Symbol] the resource key agents address it by
+        # @param model_name [String]
+        # @param permission [String] the `read_*` key gating it
+        # @param serializer_name [String]
+        # @param dashboard_path [String, nil] a `%<id>s` format string
+        # @param scope_name [Symbol, nil] narrows the model to a slice of itself
+        # @param write_permission [String, nil] the `write_*` key, absent when
+        #   the controller offers no writes
+        # @param writable_attributes [Array<Symbol>] what a write may set
+        # @param create_workflow_key [String, nil] set when the controller
+        #   declares a create workflow, which the generic write defers to
+        # @param update_workflow_key [String, nil] likewise for updates
+        # @param distinct [Boolean, nil] false where the controller disables
+        #   DISTINCT on its own collection, which Postgres requires when the
+        #   sort column is not in the select list
+        # @return [Entry]
+        def register(key:, model_name:, permission:, serializer_name:, dashboard_path: nil, scope_name: nil,
+                     write_permission: nil, writable_attributes: [], create_workflow_key: nil,
+                     update_workflow_key: nil, distinct: nil, api_paths: nil)
+          entry = Entry.new(key: key.to_s, model_name: model_name, permission: permission,
+                            serializer_name: serializer_name, dashboard_path: dashboard_path,
+                            scope_name: scope_name, write_permission: write_permission,
+                            writable_attributes: writable_attributes,
+                            create_workflow_key: create_workflow_key,
+                            update_workflow_key: update_workflow_key,
+                            distinct: distinct,
+                            api_paths: api_paths&.to_a)
+          entries[entry.key] = entry
+        end
+
+        # Forgets every registration, so the derivation can run again from
+        # scratch on a code reload.
+        #
+        # @return [void]
+        def reset!
+          @entries = {}
+        end
+
+        # @param key [String]
+        # @return [Entry, nil]
+        def find(key)
+          derive!
+          entries[key.to_s]
+        end
+
+        # Marks the map for rebuilding on its next read. Called on every code
+        # reload, because a controller edited in development changes what the
+        # map should say — but the rebuild itself waits for a reader.
+        #
+        # @return [void]
+        def stale!
+          @derived = false
+        end
+
+        # Fills the map once, from whatever `deriver` was registered.
+        #
+        # Under a mutex, because the deriver rebuilds in place — it clears the
+        # map and registers each entry — so a second thread reading between
+        # those two moments would see an empty map and report every resource
+        # as unknown.
+        #
+        # The flag is cleared again if the deriver raises: the map is empty by
+        # then, and leaving it marked derived would answer "unknown resource"
+        # for the rest of the process, since `stale!` only runs at boot and on
+        # reload. A failed derivation is retried by the next caller instead.
+        #
+        # @return [void]
+        def derive!
+          return if @derived || deriver.nil?
+
+          derive_mutex.synchronize do
+            return if @derived
+
+            # Set before calling, so a deriver that reads the map while filling
+            # it does not recurse.
+            @derived = true
+            begin
+              deriver.call
+            rescue StandardError
+              @derived = false
+              raise
+            end
+          end
+        end
+
+        # Resources this caller may read, so a tool description lists only what
+        # they can actually ask about.
+        #
+        # @param context [Spree::AgentTools::Context]
+        # @return [Array<Entry>]
+        def available_for(context)
+          all.select { |entry| context.permitted?(entry.permission) }
+        end
+
+        private
+
+        def entries
+          @entries ||= {}
+        end
+
+        def derive_mutex
+          @derive_mutex ||= Mutex.new
+        end
+      end
+    end
+  end
+end

data/lib/spree/agent_tools/workflow_endpoints.rb

@@ -0,0 +1,88 @@
+module Spree
+  module AgentTools
+    # Which Admin API operation runs each workflow an agent may call.
+    #
+    # A contract like {ResourceMap} and {MembershipMap}: core declares the
+    # shape, and `spree_api` fills it by reading its own routes and
+    # controllers, so a workflow that gains an endpoint is dispatched without
+    # anyone editing a list.
+    #
+    # A workflow with no entry runs in this process instead. That is not a
+    # fallback to be relied on — it means the capability has no endpoint yet,
+    # and the tool is the only way to reach it.
+    module WorkflowEndpoints
+      # @!attribute verb
+      #   @return [String] 'POST', 'PATCH'
+      # @!attribute path
+      #   @return [String] with `:name` segments still in it
+      # @!attribute body_keys
+      #   @return [Array<String>] what the operation's request body accepts,
+      #     read from the generated OpenAPI document — which is where the
+      #     renames live (a cancellation's `reason:` keyword is
+      #     `cancel_reason_id` on the wire)
+      Entry = Struct.new(:verb, :path, :body_keys, keyword_init: true) do
+        # The dynamic segments, in the order the path names them.
+        #
+        # @return [Array<String>]
+        def path_params
+          @path_params ||= path.scan(/:([a-z_]+)/).flatten
+        end
+
+        # @param values [Hash] path parameter name => id
+        # @return [String]
+        def path_for(values)
+          path.gsub(/:([a-z_]+)/) { values.fetch(Regexp.last_match(1)).to_s }
+        end
+      end
+
+      class << self
+        # @param key [Symbol] a `Spree::Dependencies` workflow key
+        # @return [Entry, nil]
+        def find(key)
+          derive!
+          entries[key.to_sym]
+        end
+
+        # @return [Hash{Symbol => Entry}]
+        def all
+          derive!
+          entries
+        end
+
+        def register(key:, verb:, path:, body_keys: [])
+          entries[key.to_sym] = Entry.new(verb: verb.to_s.upcase, path: path,
+                                          body_keys: body_keys.map(&:to_s))
+        end
+
+        def reset!
+          @entries = {}
+          @derived = false
+        end
+
+        # What has been registered so far, without deriving — for the
+        # deriver itself, which must not ask for what it is producing.
+        #
+        # @return [Hash{Symbol => Entry}]
+        def registered
+          entries
+        end
+
+        # Filled on first read rather than at boot: deriving it loads every
+        # admin controller, which a developer who never runs an agent should
+        # not pay for on each code reload.
+        def derive!
+          return if @derived
+
+          @derived = true
+          Spree::Api::AgentWorkflowEndpoints.install if defined?(Spree::Api::AgentWorkflowEndpoints)
+        end
+
+        private
+
+        def entries
+          @entries ||= {}
+        end
+      end
+    end
+  end
+end