spree_core 6.0.0.rc2 → 6.0.0.rc4

data/db/migrate/20261005120000_create_spree_oauth_tables.rb

@@ -0,0 +1,67 @@
+# OAuth 2.1 authorization server tables. Separate from any OAuth Spree
+# carried before 5.4: those served password and client-credentials grants for
+# the legacy API, and nothing migrates forward.
+class CreateSpreeOauthTables < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_oauth_applications do |t|
+      t.string :name, null: false
+      t.string :uid, null: false
+      # Null for a public client, which is every MCP client: they run in a
+      # browser or on a vendor's server and cannot hold a secret, which is
+      # why PKCE is mandatory rather than optional here.
+      t.string :secret
+      t.text :redirect_uri
+      t.string :scopes, null: false, default: ''
+      t.boolean :confidential, null: false, default: false
+      t.references :store, null: false, index: true
+      t.timestamps
+    end
+
+    add_index :spree_oauth_applications, :uid, unique: true
+
+    create_table :spree_oauth_access_grants do |t|
+      t.references :resource_owner, polymorphic: true, null: false, index: true
+      t.references :application, null: false, index: true
+      t.string :token, null: false
+      t.integer :expires_in, null: false
+      t.text :redirect_uri
+      t.string :scopes, null: false, default: ''
+      t.datetime :revoked_at
+      t.string :code_challenge
+      t.string :code_challenge_method
+      # RFC 8707: what the grant was requested for, carried to the token so
+      # the audience can be checked on every call. The column name is
+      # Doorkeeper's — its `resource_indicators_supported?` detects the
+      # feature by this column's presence.
+      t.text :resource
+      t.timestamps
+    end
+
+    add_index :spree_oauth_access_grants, :token, unique: true
+
+    create_table :spree_oauth_access_tokens do |t|
+      t.references :resource_owner, polymorphic: true, index: true
+      t.references :application, index: true
+      # Text rather than string: tokens are hashed, and a hash outgrows 255
+      # characters under some configurations.
+      t.text :token, null: false
+      t.text :refresh_token
+      t.integer :expires_in
+      t.datetime :revoked_at
+      t.string :scopes
+      t.string :previous_refresh_token, null: false, default: ''
+      t.text :resource
+      t.timestamps
+    end
+
+    # Hashed tokens are long, so both lookup indexes cover a prefix on MySQL,
+    # where an index over a full-length text column is rejected outright.
+    if connection.adapter_name.match?(/mysql/i)
+      add_index :spree_oauth_access_tokens, :token, unique: true, length: 255
+      add_index :spree_oauth_access_tokens, :refresh_token, unique: true, length: 255
+    else
+      add_index :spree_oauth_access_tokens, :token, unique: true
+      add_index :spree_oauth_access_tokens, :refresh_token, unique: true
+    end
+  end
+end

data/db/migrate/20261016000001_remove_default_from_spree_tax_rates_included_in_price.rb

@@ -0,0 +1,9 @@
+# Whether tax sits inside a price is the market's setting now, and the column is
+# read once by `spree:markets:backfill_tax_inclusive`. New rates leave it empty,
+# so that step, which every later upgrade runs again, never mistakes one for a
+# rate whose tax was added on top. The column is dropped in 6.1.
+class RemoveDefaultFromSpreeTaxRatesIncludedInPrice < ActiveRecord::Migration[8.1]
+  def change
+    change_column_default :spree_tax_rates, :included_in_price, from: false, to: nil
+  end
+end

data/db/migrate/20261016100001_create_spree_tax_exemption_reasons.rb

@@ -0,0 +1,21 @@
+class CreateSpreeTaxExemptionReasons < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_tax_exemption_reasons do |t|
+      t.references :store, null: false, index: false
+      t.string :name, null: false
+      t.string :code, null: false
+      t.boolean :active, null: false, default: true
+      if t.respond_to?(:jsonb)
+        t.jsonb :metadata
+      else
+        t.json :metadata
+      end
+      t.timestamps
+    end
+
+    add_index :spree_tax_exemption_reasons, [:store_id, :name], unique: true,
+              name: 'idx_tax_exemption_reasons_on_store_and_name'
+    add_index :spree_tax_exemption_reasons, [:store_id, :code], unique: true,
+              name: 'idx_tax_exemption_reasons_on_store_and_code'
+  end
+end

data/db/migrate/20261017100001_add_tax_exemption_reason_to_spree_tax_exemption_certificates.rb

@@ -0,0 +1,9 @@
+class AddTaxExemptionReasonToSpreeTaxExemptionCertificates < ActiveRecord::Migration[8.1]
+  def change
+    # Nullable, and reason_code kept: certificates recorded before reasons
+    # existed are linked by `spree:upgrade:tax_exemption_reasons`, which reads
+    # their reason_code.
+    add_reference :spree_tax_exemption_certificates, :tax_exemption_reason
+    change_column_null :spree_tax_exemption_certificates, :reason_code, true
+  end
+end

data/db/sample_data/orders.rb

@@ -98,7 +98,7 @@ if tax_rate
     ).first_or_create! do |tax_line|
       tax_line.amount = 0
       tax_line.rate = tax_rate.amount
-      tax_line.included = tax_rate.included_in_price
+      tax_line.included = order.tax_inclusive?
       tax_line.provider_id = 'internal'
     end
   end

data/lib/spree/agent_tool.rb

@@ -0,0 +1,188 @@
+module Spree
+  # One entry in the agent-tool registry ({Spree.admin_agent_tools}).
+  #
+  # A tool is a plain Spree object: a name, a description the model reads, a
+  # JSON parameter schema, the permission key that gates it, whether it
+  # mutates the store, and an executor. Nothing here knows which client is
+  # asking — the MCP server and the dashboard assistant are both adapters
+  # over this one registry, so a tool registered once is offered by both.
+  #
+  # Subclasses implement {#call} and declare their metadata with the class-level
+  # DSL:
+  #
+  #   class Spree::AgentTools::SearchResources < Spree::AgentTool
+  #     tool_name 'search_resources'
+  #     description 'Search store records.'
+  #     permission 'read_products'
+  #     param :resource, description: 'What to search', required: true
+  #
+  #     def call(resource:)
+  #       # ...
+  #     end
+  #   end
+class AgentTool
+    # Declarations live in class attributes rather than plain class-level
+    # instance variables so a subclass inherits them. Subclassing a tool to
+    # tweak it is the documented extension path, and with bare ivars the
+    # subclass would come back `mutating? == false` — writing to the store
+    # immediately, with no approval card, no permission gate and no argument
+    # validation. Inheritance here is a safety property, not a convenience.
+    class_attribute :declared_tool_name, instance_accessor: false
+    class_attribute :declared_description, instance_accessor: false
+    class_attribute :declared_permission, instance_accessor: false
+    class_attribute :declared_mutating, instance_accessor: false, default: false
+    class_attribute :declared_audience, instance_accessor: false, default: :admin
+    class_attribute :declared_params, instance_accessor: false, default: {}.freeze
+
+    class << self
+      # @return [String] the name the model calls this tool by
+      def tool_name(value = nil)
+        self.declared_tool_name = value if value
+        declared_tool_name
+      end
+
+      # @return [String] what the tool does, read by the model when choosing
+      def description(value = nil)
+        self.declared_description = value if value
+        declared_description
+      end
+
+      # RBAC permission key required to use this tool. A user without it never
+      # sees the tool in the list handed to the model.
+      #
+      # @return [String]
+      def permission(value = nil)
+        self.declared_permission = value if value
+        declared_permission
+      end
+
+      # Which surface this tool belongs to: `:admin` for the back office,
+      # `:store` for the storefront.
+      #
+      # Declared on the tool rather than inferred from the registry it was
+      # pushed into, so filing one in the wrong place is refused at
+      # registration. It matters most for the tools that carry no permission
+      # of their own — they are gated per resource, and a blank permission
+      # reads as "anyone may see this".
+      #
+      # @param value [Symbol, nil]
+      # @return [Symbol]
+      def audience(value = nil)
+        self.declared_audience = value.to_sym if value
+        declared_audience
+      end
+
+      # Declares that this tool changes store data, so the turn halts for
+      # human approval instead of executing.
+      #
+      # @return [void]
+      def mutating!
+        self.declared_mutating = true
+      end
+
+      # @return [Boolean]
+      def mutating?
+        declared_mutating == true
+      end
+
+      # @param name [Symbol]
+      # @param type [Symbol] JSON schema type
+      # @param description [String]
+      # @param required [Boolean]
+      # @param items [Symbol] what an array holds — a JSON Schema array without
+      #   it is ambiguous, and a client that validates arguments against the
+      #   schema rejects the call before the tool ever runs
+      # @return [void]
+      def param(name, type: :string, description: nil, required: false, items: nil)
+        # Reassigned rather than mutated, so declaring a param on a subclass
+        # does not reach back and change the parent's list.
+        self.declared_params = declared_params.merge(
+          name => { type: type, description: description, required: required, items: items }
+        ).freeze
+      end
+
+      # @return [Hash{Symbol => Hash}]
+      def params
+        declared_params
+      end
+    end
+
+    # @return [Spree::AgentTools::Context] who is asking, and where
+    attr_reader :context
+
+    # @param context [Spree::AgentTools::Context]
+    def initialize(context)
+      @context = context
+    end
+
+    delegate :tool_name, :description, :permission, :mutating?, :params, to: :class
+
+    # Runs the tool. Subclasses implement this with keyword arguments matching
+    # their declared params.
+    #
+    # @return [Hash] the result handed back to the model
+    def call(**)
+      raise NotImplementedError, 'Agent tools must implement #call'
+    end
+
+    # One line saying what approving this call would do. It is the entire
+    # approval card — the merchant decides on this sentence and nothing else,
+    # so every mutating tool should override it with something that reads
+    # like an instruction ("Set Blue Shirt to draft"), naming the record
+    # rather than its id.
+    #
+    # The fallback spells the arguments out rather than dumping JSON, so a
+    # tool that forgets to override is merely terse instead of unreadable.
+    #
+    # @param arguments [Hash]
+    # @return [String]
+    def summary(arguments)
+      described = arguments.map { |key, value| "#{key.to_s.humanize.downcase} #{value}" }.join(', ')
+
+      [tool_name.humanize, described.presence].compact.join(': ')
+    end
+
+    # Whether the asking user may use this tool at all.
+    #
+    # @return [Boolean]
+    def permitted?
+      context.permitted?(permission)
+    end
+
+    # A resource the map does not hold, answered with the ones it does.
+    #
+    # Every tool that takes a resource key refuses the same way: naming what is
+    # available is what lets the model correct itself in one step instead of
+    # guessing again, and a caller only ever sees resources its own credential
+    # may read.
+    #
+    # @param key [String]
+    # @return [Hash]
+    def unknown_resource(key)
+      {
+        error: "Unknown resource #{key.to_s.inspect}. Call describe_resource for the list.",
+        available: Spree::AgentTools::ResourceMap.available_for(context).map(&:key)
+      }
+    end
+
+    protected
+
+    # Refuses unless this admin may take `action` on `record`.
+    #
+    # Holding `write_products` says an admin may edit products; it does not
+    # say they may edit *this* one. A host app can narrow that with a
+    # record-level rule, and the Admin API honours it — so any tool that
+    # changes a record must ask here first. Returns an error the model reads
+    # rather than raising, so the assistant explains itself instead of the
+    # turn dying.
+    #
+    # @param action [Symbol]
+    # @param record [Object]
+    # @return [Hash, nil] an error result to return, or nil when allowed
+    def unauthorized(action, record)
+      return if context.can?(action, record)
+
+      { error: "You do not have permission to #{action} this #{record.class.name.demodulize.underscore.humanize.downcase}." }
+    end
+  end
+end

data/lib/spree/agent_tools/api_dispatch.rb

@@ -0,0 +1,204 @@
+module Spree
+  module AgentTools
+    # Runs an Admin API operation for a tool, in this process.
+    #
+    # A tool names an operation; this is what reaches it. The request goes
+    # through the whole stack — routing, authentication, the controller, the
+    # serializer, the error format — so a tool reaches data the way any other
+    # client does, and a guard added to the API protects agents without anyone
+    # copying it here.
+    #
+    # Deliberately not HTTP to itself. A socket back to the same application
+    # holds one web thread waiting on another, so a few concurrent tool calls
+    # on a small pool deadlock the process, and it buys TLS, DNS and timeouts
+    # for nothing.
+    class ApiDispatch
+      # What a dispatched call answers with.
+      Response = Struct.new(:status, :body, :headers, :raw, keyword_init: true) do
+        # What the endpoint actually sent, for an operation whose answer is a
+        # file rather than a record.
+        #
+        # @return [String, nil]
+        def content
+          raw
+        end
+
+        # @return [String, nil]
+        def content_type
+          headers.to_h.find { |name, _| name.to_s.casecmp('content-type').zero? }&.last
+        end
+
+        # @return [Boolean]
+        def success?
+          status.between?(200, 299)
+        end
+
+        # The error the API itself rendered, in its own words. A tool repeats
+        # this rather than inventing a message, so a refusal reads the same
+        # however it was reached.
+        #
+        # @return [String, nil]
+        def error_message
+          return if success?
+
+          error = body.is_a?(Hash) ? body['error'] : nil
+          return error if error.is_a?(String)
+          return error['message'] if error.is_a?(Hash) && error['message'].present?
+
+          "The request failed (#{status})."
+        end
+
+        # @return [Hash, Array, nil]
+        def data
+          body.is_a?(Hash) && body.key?('data') ? body['data'] : body
+        end
+
+        # @return [Hash, nil] pagination, when the operation is a listing
+        def meta
+          body['meta'] if body.is_a?(Hash)
+        end
+      end
+
+      # Only what the Admin API reads. Anything else a client sent is the MCP
+      # request's business, not the operation's.
+      FORWARDED_HEADERS = %w[HTTP_AUTHORIZATION HTTP_X_SPREE_API_KEY HTTP_HOST].freeze
+
+      # @param context [Spree::AgentTools::Context]
+      def initialize(context)
+        @context = context
+      end
+
+      # @param method [Symbol] :get, :post, :patch, :delete
+      # @param path [String] the operation's full path, already interpolated —
+      #   the resource map's paths are absolute (`/api/v3/admin/products`)
+      # @param params [Hash] query parameters for a read
+      # @param body [Hash, nil] the request body for a write. A value that
+      #   responds to `read` makes the request multipart, which is how the
+      #   upload endpoint takes bytes.
+      # @return [Response]
+      def call(method:, path:, params: {}, body: nil)
+        env = build_env(method, path, params, body)
+
+        # `Spree::Current` is an `ActiveSupport::CurrentAttributes`, which does
+        # NOT reset for a request made inside another request — the executor
+        # is re-entrant. Measured on this branch before this class existed: an
+        # inner call left the outer store in place and overwrote its currency.
+        #
+        # So the outer state is copied, cleared so the inner request resolves
+        # its own from its own headers, and put back whatever happened. The
+        # restore has to sit in this method's own `ensure`: wrapped in a
+        # helper that yields, it ran before the executor finished unwinding
+        # and the outer values were lost again.
+        saved = Spree::Current.attributes.to_a
+        # `RequestStore` is per-request too, and the inner request's middleware
+        # clears it on the way out — leaving `RequestStore.store` nil, which
+        # the store scope guard indexes into on the outer request's next
+        # query. Saved unconditionally, including when it is already empty:
+        # restoring an empty hash is what keeps it a hash.
+        saved_request_store = defined?(RequestStore) ? RequestStore.store.to_h.dup : nil
+
+        begin
+          status, headers, rack_body = Rails.application.call(env)
+          text = read(rack_body)
+          Response.new(status: status, headers: headers, body: parse(text), raw: text)
+        ensure
+          # The executor flushes `ActiveSupport::ExecutionContext` as the
+          # inner request unwinds, and that is where `CurrentAttributes` keeps
+          # its per-thread instances — so the outer request's next read of
+          # `Spree::Current` found no registry and raised inside Rails. A
+          # frame has to be pushed back BEFORE the values are written, or the
+          # writes land in a frame that is then replaced and read as nil.
+          ActiveSupport::ExecutionContext.push if defined?(ActiveSupport::ExecutionContext)
+          saved.each { |name, value| Spree::Current.public_send(:"#{name}=", value) }
+          RequestStore.store = saved_request_store unless saved_request_store.nil?
+        end
+      end
+
+      private
+
+      def build_env(method, path, params, body)
+        query = params.present? ? Rack::Utils.build_nested_query(stringify(params)) : nil
+
+        env = Rack::MockRequest.env_for(
+          path,
+          method: method.to_s.upcase,
+          params: query,
+          **payload_env(body)
+        ).compact
+
+        forwarded.each { |name, value| env[name] = value }
+        env['HTTP_ACCEPT'] = 'application/json'
+        env
+      end
+
+      # JSON unless the body carries an IO, in which case the request is
+      # multipart — the shape `POST /files` reads bytes from, and the only
+      # way to hand it a file without a second request from outside.
+      def payload_env(body)
+        return {} if body.blank?
+
+        file = body.find { |_name, value| value.respond_to?(:read) }
+        return { input: JSON.generate(body), 'CONTENT_TYPE' => 'application/json' } if file.nil?
+
+        boundary = "SpreeAgentTools#{SecureRandom.hex(16)}"
+        {
+          input: multipart_body(body, file, boundary),
+          'CONTENT_TYPE' => "multipart/form-data; boundary=#{boundary}"
+        }
+      end
+
+      # Written out rather than taken from `Rack::Test`, which is a test
+      # dependency of neither gem and would be missing from a real install.
+      def multipart_body(body, file, boundary)
+        name, io = file
+        filename = body['filename'].presence || 'file'
+        content_type = body['content_type'].presence || 'application/octet-stream'
+
+        parts = body.except(name).filter_map do |field, value|
+          next if value.nil?
+
+          "--#{boundary}\r\nContent-Disposition: form-data; name=\"#{field}\"\r\n\r\n#{value}\r\n"
+        end
+
+        parts << "--#{boundary}\r\n" \
+                 "Content-Disposition: form-data; name=\"#{name}\"; filename=\"#{filename}\"\r\n" \
+                 "Content-Type: #{content_type}\r\n\r\n"
+
+        # Binary, because the bytes are: joining them into a UTF-8 string
+        # raises on the first image that is not valid UTF-8.
+        parts.join.dup.force_encoding(Encoding::BINARY) +
+          io.read.dup.force_encoding(Encoding::BINARY) +
+          "\r\n--#{boundary}--\r\n".dup.force_encoding(Encoding::BINARY)
+      end
+
+      # The credential the caller authenticated with, repeated verbatim. Never
+      # an internal header that skips authentication: that would rebuild the
+      # second security boundary this class exists to remove.
+      def forwarded
+        @context.request_headers.slice(*FORWARDED_HEADERS)
+      end
+
+      def read(rack_body)
+        text = +''
+        rack_body.each { |chunk| text << chunk }
+        rack_body.close if rack_body.respond_to?(:close)
+        text
+      end
+
+      # A download answers with the file, not a record, so a body that is not
+      # JSON is not an error — it is kept as it came in {Response#content}.
+      def parse(text)
+        return if text.blank?
+
+        JSON.parse(text)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Rack wants strings; a tool passes whatever the model sent.
+      def stringify(params)
+        params.to_h.deep_transform_keys(&:to_s)
+      end
+    end
+  end
+end