spree_api 6.0.2 → 6.0.4

data/lib/spree/api/agent_resource_map.rb

@@ -71,16 +71,23 @@ module Spree
       # one, because the scope belongs to the resource being imported or
       # exported — creating a product import is a product write, and reading
       # its rows exposes the uploaded data. A single static key cannot say
-      # that, so these are registered read-only under the broadest key the
-      # controller can demand, and the write path stays with the endpoint.
+      # that, so these open to a caller holding the scope of any one type,
+      # in the kind the controller asks for: `read_` for an export, `write_`
+      # for an import. The endpoint then keeps to the types that key covers.
+      #
+      # Creating one stays with create_import and create_export; reading,
+      # listing and deleting go to the endpoint.
       DYNAMIC_SCOPE_RESOURCES = {
-        'imports' => { model_name: 'Spree::Import', permission: 'read_settings',
+        'imports' => { model_name: 'Spree::Import', access_kind: 'write',
                        serializer_name: 'Spree::Api::V3::Admin::ImportSerializer',
                        dashboard_path: '/settings/imports' },
-        'exports' => { model_name: 'Spree::Export', permission: 'read_settings',
+        'exports' => { model_name: 'Spree::Export', access_kind: 'read',
                        serializer_name: 'Spree::Api::V3::Admin::ExportSerializer' }
       }.freeze
 
+      # The operations the generic tools reach on those resources.
+      DYNAMIC_SCOPE_ACTIONS = %i[index show destroy].freeze
+
       class << self
         # Registers this walk as how the core map fills itself, and marks the
         # map stale so the next reader gets a fresh one. Called on every code
@@ -102,7 +109,11 @@ module Spree
           registered = resolve_collisions(controllers.filter_map { |controller| derive(controller) })
           registered.each { |entry| map.register(**entry) }
 
-          DYNAMIC_SCOPE_RESOURCES.each { |key, attributes| map.register(key: key, **attributes) }
+          DYNAMIC_SCOPE_RESOURCES.each do |key, attributes|
+            map.register(key: key, permission: nil, **attributes.except(:access_kind),
+                         api_paths: dynamic_scope_paths(attributes[:model_name]),
+                         access_permissions: type_permissions(attributes[:model_name], attributes[:access_kind]))
+          end
 
           registered.size + DYNAMIC_SCOPE_RESOURCES.size
         end
@@ -142,6 +153,15 @@ module Spree
             transform_values { |pairs| pairs.map(&:last).min_by { |path| [path.count(':'), path.length] } }
         end
 
+        # The controller served at the shallowest path, which is where a tool
+        # dispatches: for a record it is the show path, else the collection.
+        def shallowest_candidate(candidates)
+          candidates.min_by do |entry|
+            path = Array(entry[:api_paths]).to_h.values_at(:show, :index).compact.first.to_s
+            [path.empty? ? Float::INFINITY : path.count(':'), path.length]
+          end
+        end
+
         def api_paths_for(controller)
           candidates = Spree::Core::Engine.routes.routes.filter_map do |route|
             next unless route.defaults[:controller] == controller.controller_path
@@ -174,6 +194,7 @@ module Spree
           create_workflow = workflow_key(instance, :create_workflow)
           update_workflow = workflow_key(instance, :update_workflow)
           writable = AgentWriteSchemas.attribute_names(key)
+          api_paths = api_paths_for(controller)
 
           {
             key: key,
@@ -181,7 +202,8 @@ module Spree
             permission: "read_#{scope}",
             serializer_name: serializer.name,
             dashboard_path: DASHBOARD_PATHS[key],
-            api_paths: api_paths_for(controller),
+            api_paths: api_paths,
+            index_paths: Array(api_paths[:index]),
             write_permission: write_permission_for(model, scope, create_workflow, update_workflow, writable, controller),
             writable_attributes: writable,
             create_workflow_key: create_workflow,
@@ -190,8 +212,45 @@ module Spree
           }
         end
 
+        # The plural the resource is addressed by, taken from the model so two
+        # controllers serving the same model (a nested one and a top-level one)
+        # agree on it. The operation catalog keys its tools the same way.
+        #
+        # @param model [Class]
+        # @return [String]
+        def key_for(model)
+          model.model_name.element.pluralize
+        end
+
+        # The model a controller serves, or nil for one that serves none.
+        #
+        # @param controller [Class]
+        # @return [Class, nil]
+        def model_for(controller)
+          safely(controller.allocate, :model_class)
+        end
+
         private
 
+        # The read and delete paths of the controller serving an import or
+        # export. Without them the generic tools refused every one, though
+        # create_export tells the agent to read the export with get_resource.
+        def dynamic_scope_paths(model_name)
+          controller = controllers.find { |candidate| model_for(candidate)&.name == model_name }
+          return {} if controller.nil?
+
+          api_paths_for(controller).slice(*DYNAMIC_SCOPE_ACTIONS)
+        end
+
+        # The catalog keys that open an import or export of each registered
+        # type. A type with no scope of its own needs `read_all` or
+        # `write_all`, which no catalog key stands for, so it adds none.
+        def type_permissions(model_name, kind)
+          model_name.constantize.available_types.
+            filter_map { |type| type.required_scope.presence && "#{kind}_#{type.required_scope}" }.
+            uniq.select { |key| Spree.permissions.key?(key) }
+        end
+
         # What the controller does with its own collection. A controller that
         # disables DISTINCT has a reason — Postgres refuses it beside an
         # ORDER BY the select list does not carry — and a search tool adding
@@ -228,6 +287,11 @@ module Spree
             # withdrawn, and only when the controllers disagree about the
             # scope guarding it.
             narrowest.merge(
+              # The serializer of the controller the tools actually reach:
+              # the one whose path won below. `narrowest` is chosen on
+              # permission, which left `products` described by the catalog
+              # membership serializer and `expand: ["variants"]` refused.
+              serializer_name: shallowest_candidate(candidates)[:serializer_name],
               create_workflow_key: candidates.filter_map { |entry| entry[:create_workflow_key] }.first,
               update_workflow_key: candidates.filter_map { |entry| entry[:update_workflow_key] }.first,
               write_permission: contested ? nil : narrowest[:write_permission],
@@ -241,7 +305,10 @@ module Spree
               # nothing about depth — so a resource served both at the top
               # level and under a parent kept whichever won on scope, and a
               # tool was handed a path with an unfillable `:parent_id` in it.
-              api_paths: shallowest_paths(candidates)
+              api_paths: shallowest_paths(candidates),
+              # Every collection path, not only the shallowest, so a search
+              # under a parent reaches the controller that lists its records.
+              index_paths: candidates.flat_map { |entry| entry[:index_paths] }.uniq
             )
           end
         end
@@ -299,13 +366,6 @@ module Spree
           false
         end
 
-        # The plural the resource is addressed by, taken from the model so two
-        # controllers serving the same model (a nested one and a top-level one)
-        # agree on it.
-        def key_for(model)
-          model.model_name.element.pluralize
-        end
-
         # `Spree::Base.for_store` falls back to the bare class for a model with
         # no Store association, which would hand this store's agent every
         # store's rows. A model that defines its own `for_store` has made a

data/lib/spree/api/agent_write_schemas.rb

@@ -11,8 +11,8 @@ module Spree
     # fill a form in correctly. Reading it means the generic write tools offer
     # exactly the documented endpoint and nothing else.
     #
-    # Loaded once, lazily: the document is well over a megabyte, and an
-    # installation with no agent client should never pay for parsing it.
+    # Read from {AdminDocument}, so an extension's documented resources
+    # count the same as core's.
     module AgentWriteSchemas
       # A collection endpoint under the admin namespace: `/api/v3/admin/markets`
       # but not `/api/v3/admin/markets/{id}` or a nested child.
@@ -33,29 +33,25 @@ module Spree
           self.for(key).keys
         end
 
-        # Where the generated document lives: `docs/` in a source checkout,
-        # or the copy the release packs into the gem. Resolved lazily: the
-        # engine class does not exist yet while this file loads.
+        # Core's generated document, which the merged one starts from.
         #
         # @return [Pathname]
         def spec_path
-          source = Spree::Api::Engine.root.join('..', '..', 'docs', 'api-reference', 'admin.yaml')
-          source.exist? ? source : Spree::Api::Engine.root.join('openapi', 'admin.yaml')
+          AdminDocument.core_path
         end
 
-        # The parsed document, for a reader that needs more of it than the
-        # write bodies — the workflow endpoint map wants the member actions'
-        # bodies too, and parsing a megabyte of YAML twice is wasteful.
+        # The merged document — core's and every extension's — so an
+        # extension's resources are generically writable the same way core's
+        # are.
         #
         # @return [Hash]
         def document
-          @document ||= begin
-            path = spec_path
-            File.exist?(path) ? (YAML.unsafe_load_file(path) || {}) : {}
-          rescue StandardError => e
-            Rails.logger.warn("[Spree] could not read the admin API document: #{e.class}: #{e.message}")
-            {}
-          end
+          AdminDocument.document
+        end
+
+        # @return [void]
+        def reset!
+          @schemas = nil
         end
 
         private
@@ -64,17 +60,8 @@ module Spree
           @schemas ||= load_schemas
         end
 
-        # A missing or unparseable document is not a boot failure: the generic
-        # write tools simply offer nothing, which is the safe direction.
         def load_schemas
-          path = spec_path
-          return {} unless File.exist?(path)
-
-          document = YAML.unsafe_load_file(path)
           extract(document)
-        rescue StandardError => e
-          Rails.logger.warn("[Spree] could not read admin API write schemas: #{e.class}: #{e.message}")
-          {}
         end
 
         def extract(document)
@@ -98,32 +85,9 @@ module Spree
 
         public
 
-        # A request body is declared once per endpoint and published as a
-        # component, so the operation carries a `$ref` to it rather than the
-        # properties themselves. A body that builds on a shared shape is an
-        # `allOf` of that shape and its own fields, read as one object.
-        # Followed a few hops, which is as deep as the generated document
-        # nests them.
-        #
-        # @param schema [Hash, nil] a schema that may be a reference
-        # @return [Hash, nil] the schema it names
+        # @see AdminDocument.resolve_schema
         def resolve_schema(schema, depth = 0)
-          return unless schema.is_a?(Hash)
-          return if depth > 3
-          return merge_all_of(schema['allOf'], depth) if schema.key?('allOf')
-          return schema unless schema.key?('$ref')
-
-          name = schema['$ref'].to_s.split('/').last
-          resolve_schema(document.dig('components', 'schemas', name), depth + 1)
-        end
-
-        private
-
-        def merge_all_of(parts, depth)
-          parts.filter_map { |part| resolve_schema(part, depth + 1) }.each_with_object({}) do |part, merged|
-            merged['properties'] = (merged['properties'] || {}).merge(part['properties'] || {})
-            merged['required'] = (merged['required'] || []) | Array(part['required'])
-          end
+          AdminDocument.resolve_schema(schema, depth)
         end
       end
     end

data/lib/spree/api/dependencies.rb

@@ -38,7 +38,7 @@ module Spree
            channel order_routing_rule product_publication market delivery_method delivery_method_service
            stock_location stock_reservation delivery_rate freight_summary freight_summary_line payment_method
            credit_card store_credit store_credit_event customer_group payment_source digital_asset digital_link
-           store setup_task update_status api_key oauth_application oauth_access_token oauth_consent_request oauth_redirect
+           store setup_task update_status diagnostics api_key oauth_application oauth_access_token oauth_consent_request oauth_redirect
            oauth_protected_resource allowed_origin webhook_endpoint webhook_event webhook_delivery invitation
            invitation_acceptance_link role permission export saved_report import import_row import_mapping promotion
            maintenance_task_run

data/lib/spree/api/engine.rb

@@ -2,10 +2,11 @@ require 'rails/engine'
 
 require_relative 'dependencies'
 require_relative 'configuration'
+require_relative 'admin_document'
 require_relative 'agent_write_schemas'
 require_relative 'agent_resource_map'
 require_relative 'agent_membership_map'
-require_relative 'agent_workflow_endpoints'
+require_relative 'agent_operations'
 require_relative 'oauth'
 
 module Spree
@@ -14,6 +15,17 @@ module Spree
       isolate_namespace Spree
       engine_name 'spree_api'
 
+      # Typelizer 0.13+ ties two things to TYPELIZER: recording the serializers'
+      # `typelize` declarations, and generating types on a development server's
+      # first request. The rswag specs build the OpenAPI schemas from those
+      # declarations, so tests record them; an app's server must never generate,
+      # or it would write Spree's SDK types into the installed gem.
+      # `rake typelizer:generate` sets TYPELIZER=true itself. Set before
+      # Typelizer reads it when configuring its DSL.
+      initializer 'spree.api.typelizer', before: 'typelizer.configure_dsl' do
+        ENV['TYPELIZER'] ||= Rails.env.test? ? 'true' : 'false'
+      end
+
       initializer 'spree.api.environment', before: :load_config_initializers do |_app|
         Spree::Api::Config = Spree::Api::Configuration.new
         Spree::Api::Dependencies = Spree::Api::ApiDependencies.new
@@ -63,6 +75,7 @@ module Spree
       # not they run an agent client. The first caller pays instead.
       config.to_prepare do
         Spree::Api::AgentResourceMap.stale!
+        Spree::Api::AgentOperations.stale!
       end
 
       # Add API event subscribers

data/lib/spree/api/enum_types.rb

@@ -35,7 +35,10 @@ module Spree
       # @return [Array<Typelizer::Property>] those carrying a named list, nested and inline ones included
       def self.named_properties(properties)
         properties.flat_map do |property|
-          nested = property.nested_properties.to_a
+          # Nested attributes are an inline shape (Typelizer 0.13+); an
+          # inline association is an inline interface.
+          nested = []
+          nested += property.type.properties if property.type.is_a?(Typelizer::Shape)
           nested += property.type.properties if property.type.is_a?(Typelizer::Interface) && property.type.inline?
 
           [property, *named_properties(nested)]

data/lib/spree/api/openapi/schema_helper.rb

@@ -651,11 +651,11 @@ module Spree
         # Typelizer is normally disabled in test/production, but we need it
         # enabled to generate OpenAPI schemas from serializer type hints
         def with_typelizer_enabled
-          original = ENV['DISABLE_TYPELIZER']
-          ENV['DISABLE_TYPELIZER'] = 'false'
+          original = ENV['TYPELIZER']
+          ENV['TYPELIZER'] = 'true'
           yield
         ensure
-          ENV['DISABLE_TYPELIZER'] = original
+          ENV['TYPELIZER'] = original
         end
       end
     end

data/lib/spree/api/sdk_types.rb

@@ -0,0 +1,190 @@
+require 'spree/api/typelizer_generation'
+
+module Spree
+  module Api
+    # Generates the response types for a package that extends Spree's SDKs
+    # (docs/plans/6.0-sdk-extensions.md) from an extension's own serializers,
+    # with Typelizer, the way Spree generates its SDKs' types. Runs in the
+    # extension's test app, through the task in sdk_types_task.rb.
+    #
+    # Writes `<out>/<api>/types/` for each API the extension has
+    # serializers for, sorted by namespace as core's are (`::Admin::`,
+    # `::Seller::`, the rest Store), and `<out>/<api>/spree.ts` beside it. The
+    # generated files import every type they reference from `spree.ts`, which
+    # re-exports the extension's own types and the SDK's, so a `Quote` nesting
+    # an `Order` takes `Order` from `@spree/admin-sdk` instead of a copy.
+    #
+    # Only serializers defined under the engine's `app/serializers` are
+    # written. Named value lists are written into the package, open unless
+    # closed, since `@spree/sdk-core` is private to Spree's SDKs.
+    module SdkTypes
+      SDKS = {
+        store: '@spree/sdk',
+        admin: '@spree/admin-sdk',
+        seller: '@spree/seller-sdk'
+      }.freeze
+
+      HEADER = '// This file is generated from the serializers by `rake spree:sdk:serializer_types`. Do not edit it.'.freeze
+
+      class << self
+        # @param engine [Class<Rails::Engine>] the extension's engine
+        # @param out [String] where to write, relative to the engine's root
+        # @return [Array<Symbol>] the APIs types were written for
+        def generate!(engine:, out:)
+          serializers = engine.root.join('app/serializers')
+          out = engine.root.join(out)
+          configure(serializers, out)
+          refuse_name_collisions!
+          # Typelizer skips a writer with no serializers and leaves its folder
+          # as it was, so an API whose last serializer went away would keep
+          # publishing its old types.
+          SDKS.each_key do |api|
+            FileUtils.rm_rf(out.join(api.to_s, 'types'))
+            FileUtils.rm_f(out.join(api.to_s, 'spree.ts'))
+          end
+          run_typelizer
+
+          SDKS.keys.select do |api|
+            types = out.join(api.to_s, 'types')
+            next false unless types.exist?
+
+            TypelizerGeneration.use_interfaces!(types)
+            File.write(out.join(api.to_s, 'spree.ts'), barrel(api))
+            true
+          end
+        end
+
+        # @param serializer [Class]
+        # @return [Symbol] the API a serializer belongs to, by its namespace
+        def api_of(serializer)
+          name = serializer.name.to_s
+          return :admin if name.include?('::Admin::')
+          return :seller if name.include?('::Seller::')
+
+          :store
+        end
+
+        private
+
+        # Two serializers in one API named alike in different namespaces
+        # (`Orders::ItemSerializer`, `Returns::ItemSerializer`) would write one
+        # file and one type name, and a name the SDK already exports (`Order`)
+        # would make `spree.ts` export two types under it.
+        def refuse_name_collisions!
+          SDKS.each_key do |api|
+            interfaces = Typelizer.interfaces(writer_name: api)
+            clash = interfaces.group_by(&:name).find { |_name, named| named.size > 1 }
+            if clash
+              raise ArgumentError, "#{clash.last.map { |i| i.serializer.name }.join(' and ')} both generate the #{api} type " \
+                                   "#{clash.first}; rename one of the serializers"
+            end
+
+            taken = interfaces.find { |interface| core_type_names(api).include?(interface.name) }
+            if taken
+              raise ArgumentError, "#{taken.serializer.name} generates #{taken.name}, which #{SDKS[api]} already exports; " \
+                                   'rename the serializer'
+            end
+
+            # A value list and a type of one name are both exported from the
+            # generated index, and one the SDK already has would be exported
+            # twice from `spree.ts`.
+            names = interfaces.map(&:name).to_set
+            lists = interfaces.flat_map(&:enum_types)
+            list = lists.find { |property| names.include?(property.enum_type_name) }
+            if list
+              raise ArgumentError, "The value list #{list.enum_type_name} is also the name of a type the #{api} API generates; " \
+                                   'give its enum_type_name another name'
+            end
+
+            list = lists.find { |property| core_list_names(api).include?(property.enum_type_name) }
+            next unless list
+
+            raise ArgumentError, "The value list #{list.enum_type_name}, which #{SDKS[api]} already exports, is declared again; " \
+                                 'give its enum_type_name another name'
+          end
+        end
+
+        # The type names Spree's own serializers give the SDK of one API, read
+        # from their file names and filtered as core's writers filter them.
+        def core_type_names(api)
+          @core_type_names ||= {}
+          @core_type_names[api] ||= begin
+            root = Spree::Api::Engine.root.join('app/serializers/spree/api/v3')
+            names = ->(pattern) { Dir[root.join(pattern)].to_set { |file| File.basename(file, '_serializer.rb').camelize } }
+            case api
+            when :store then names.call('*_serializer.rb') - TypelizerGeneration::STORE_EXCLUDED
+            when :admin then names.call('admin/**/*_serializer.rb')
+            when :seller then names.call('seller/**/*_serializer.rb') | TypelizerGeneration::SELLER_STORE_TYPES
+            end
+          end
+        end
+
+        # The value lists Spree's own serializers give the SDK of one API, read
+        # from their `enum_type_name:` declarations, and the shared code lists
+        # every SDK exports.
+        def core_list_names(api)
+          @core_list_names ||= {}
+          @core_list_names[api] ||= begin
+            root = Spree::Api::Engine.root.join('app/serializers/spree/api/v3')
+            patterns = { store: ['*_serializer.rb'], admin: ['admin/**/*_serializer.rb', '*_serializer.rb'],
+                         seller: ['seller/**/*_serializer.rb', '*_serializer.rb'] }.fetch(api)
+            declared = patterns.flat_map { |pattern| Dir[root.join(pattern)] }
+                               .flat_map { |file| File.read(file).scan(/enum_type_name: ['"](\w+)['"]/).flatten }
+            declared.to_set | Typelizer::OpenEnums::CLOSED_TYPE_NAMES
+          end
+        end
+
+        # Replaces the writers Spree configured for its own SDKs: run in an
+        # extension's app, they would write core's types into the installed gem.
+        def configure(serializers, out)
+          ours = ->(serializer) { Object.const_source_location(serializer.name)&.first.to_s.start_with?("#{serializers}/") }
+
+          Typelizer.configure do |config|
+            config.reset_writers!
+            config.dirs = [serializers]
+            config.listen = false
+            config.comments = true
+            config.plugin_configs = TypelizerGeneration.plugin_configs
+            # The default writer writes nothing; each API has its own below.
+            config.reject_class = ->(serializer:) { true }
+
+            SDKS.each_key do |api|
+              config.writer(api) do |writer|
+                writer.output_dir = out.join(api.to_s, 'types')
+                writer.types_import_path = '../spree'
+                # Named type exports compile whether or not the package sets
+                # `verbatimModuleSyntax`; a default export of a type does not.
+                writer.verbatim_module_syntax = true
+                writer.reject_class = ->(serializer:) { !ours.call(serializer) || api_of(serializer) != api }
+                writer.serializer_name_mapper = ->(serializer) { serializer.name.to_s.demodulize.delete_suffix('Serializer') }
+              end
+            end
+          end
+        end
+
+        def run_typelizer
+          enabled = ENV['TYPELIZER']
+          source = Typelizer::OpenEnums.source
+          ENV['TYPELIZER'] = 'true'
+          Typelizer::OpenEnums.source = nil
+
+          require 'typelizer/generator'
+          Typelizer::Generator.call(force: true)
+        ensure
+          ENV['TYPELIZER'] = enabled
+          Typelizer::OpenEnums.source = source
+        end
+
+        def barrel(api)
+          <<~TS
+            #{HEADER}
+
+            // Every type the generated files reference: the SDK's, and this package's own.
+            export type * from '#{SDKS[api]}'
+            export type * from './types'
+          TS
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/sdk_types_task.rb

@@ -0,0 +1,68 @@
+# `rake spree:sdk:serializer_types`: writes the response types of a package
+# that extends Spree's SDKs from the serializers of the extension or app it
+# runs in (see sdk_types.rb). `spree sdk generate` runs it with OUT set to the
+# package's output folder; nothing else has to be configured.
+#
+# An extension gets the task from `spree/testing_support/extension_rake`, and
+# runs it against its test app (`bundle exec rake test_app` first). A Spree
+# application gets it from spree_api's own tasks, against itself.
+require 'rake'
+
+module Spree
+  module Api
+    class SdkTypesTask
+      include Rake::DSL
+
+      # @param engine [String, nil] the engine class; by default the engine,
+      #   or the application, whose root is the current folder
+      # @param out [String, nil] where to write; by default `ENV['OUT']`
+      # @param dummy [String] an extension's test app environment file
+      def initialize(engine: nil, out: nil, dummy: 'spec/dummy/config/environment.rb')
+        return if Rake::Task.task_defined?('spree:sdk:serializer_types')
+
+        namespace :spree do
+          namespace :sdk do
+            desc "Generate the SDK response types from this extension's or app's serializers (OUT=folder)"
+            task :serializer_types do
+              target = out || ENV['OUT']
+              abort 'Pass OUT, the folder to write the types to, or run `spree sdk generate`.' if target.to_s.empty?
+
+              boot(dummy)
+              require 'spree/api/sdk_types'
+
+              owner = engine ? engine.constantize : self.class.owner_here
+              abort "No engine or application has its root in #{Dir.pwd}" unless owner
+
+              apis = Spree::Api::SdkTypes.generate!(engine: owner, out: File.expand_path(target))
+              puts apis.any? ? "Wrote the #{apis.join(', ')} response types to #{target}" : "No serializers under #{owner.root}/app/serializers"
+            end
+          end
+        end
+      end
+
+      # @return [Class<Rails::Engine>, Rails::Application, nil] the engine or
+      #   application whose root is the current folder
+      def self.owner_here
+        here = File.expand_path(Dir.pwd)
+        Rails::Engine.subclasses.find { |engine| File.expand_path(engine.root.to_s) == here } ||
+          (Rails.application if File.expand_path(Rails.application.root.to_s) == here)
+      end
+
+      private
+
+      # Typelizer records the serializers' `typelize` declarations only when
+      # TYPELIZER is on as the app boots, so it is set first.
+      def boot(dummy)
+        ENV['TYPELIZER'] = 'true'
+        if File.exist?(dummy)
+          ENV['RAILS_ENV'] ||= 'test'
+          require File.expand_path(dummy)
+        elsif Rake::Task.task_defined?(:environment)
+          Rake::Task[:environment].invoke
+        else
+          abort 'Build the test app first: bundle exec rake test_app'
+        end
+      end
+    end
+  end
+end

data/lib/spree/api/testing_support/agent_tools.rb

@@ -0,0 +1,35 @@
+module Spree
+  module Api
+    module TestingSupport
+      # rswag helpers for what an admin operation means to agents. Every
+      # write action an admin key may call is an agent tool built from its
+      # operation; these mark the exceptions in the document itself, where a
+      # reviewer sees them next to the endpoint.
+      #
+      #   patch 'Anonymize a customer' do
+      #     agent_tool false, reason: 'Irreversible erasure under GDPR Art. 17.'
+      #   end
+      #
+      #   get 'List quote statuses' do
+      #     agent_tool true   # a read becomes a tool only when it opts in
+      #   end
+      #
+      # Core and extensions extend their request specs with this module:
+      #
+      #   RSpec.configure { |config| config.extend Spree::Api::TestingSupport::AgentTools, type: :request }
+      #
+      # See docs/plans/6.0-agent-tools-from-openapi.md.
+      module AgentTools
+        # @param enabled [Boolean]
+        # @param reason [String, nil] required to opt a write out
+        # @return [void]
+        def agent_tool(enabled = true, reason: nil)
+          raise ArgumentError, 'an operation opted out of agent tools needs a reason' if !enabled && reason.blank?
+
+          metadata[:operation][Spree::Api::AgentOperations::AGENT_KEY.to_sym] = enabled
+          metadata[:operation][Spree::Api::AgentOperations::REASON_KEY.to_sym] = reason if reason
+        end
+      end
+    end
+  end
+end