spree_dev_tools 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d98eca486deeaa49bf1e00fd2d0094c9267a26ddbfd7a350b24ea45e47165394
-  data.tar.gz: ece1af112d885a728edcbe54c99adb4c2aafe19a87a25fe04e4ad823698a46ee
+  metadata.gz: a9f59a38b25829ca79a59e8bbc0268da32d59a249fd5f2539d7f09b93fbf82be
+  data.tar.gz: 45c0b758b4bce3ab91e4cf0da4c2835a69bfee006e9b59e93fa73039d2e1215d
 SHA512:
-  metadata.gz: 62197f4fb2be0134fd7243e7f41612594136f2ab05271560a23f6fdfc216e373d2670e11965a72a18606234f90f3539d54849cbe70c0d84147035b9da4e103b6
-  data.tar.gz: 54b7cdb1e26feed235a1f54e79212ef386956986c3228253da3d24ebdca3b2a91aef429df888383bc334b62d9cea44fea832d81295ec2ca75bd4a8c3a74a8a2f
+  metadata.gz: a0156248f9e0e46a45ee64a6feca697a11acf39ef7e2e852cf0e56ebe0f6df559862bc82efe7b1da06465054c9d2849c2b4cb4685297a13407f2c452f47d33ca
+  data.tar.gz: 94c2522857aef5457f62be18b38b05ac1993b5d23e782902ee60ae10dfb973aa3765a797082e32a89e1bb2556edfa53a0d384b1972042170539109a3aa1c5a89

data/README.md

@@ -22,6 +22,42 @@ And finally run the generator:
 bundle exec rails g spree_dev_tools:install
 ```
 
+## Documenting your Admin API endpoints
+
+Spree builds an agent tool (MCP server and dashboard assistant) for every Admin API action it finds documented in an OpenAPI document. Core documents its own endpoints. Your application, and each extension, documents its own in an `openapi/admin.yaml`, and Spree merges that file in.
+
+In a Spree application (a new `create-spree-app` project ships both files already):
+
+```bash
+spree generate spree_dev_tools:openapi
+spree task openapi:generate
+```
+
+In an extension, which runs against its dummy app:
+
+```bash
+bundle exec rails g spree_dev_tools:openapi
+bundle exec rake spree:openapi:generate
+```
+
+The generator writes three things:
+
+- `spec/swagger_helper.rb`, which configures rswag for your app or engine. That means the document path, the admin security schemes, `admin_operation`, `request_body_for` and `agent_tool`, and reproducible output.
+- `spec/agent_tools_spec.rb`, the contract that fails when an admin action has no documented operation, an opt-out gives no reason, or two actions would derive one tool name.
+- A skeleton rswag spec for every admin action your controllers serve that isn't documented yet, under `spec/integration/admin/`. Each skeleton is skipped until you fill in two things:
+  - its description, which agents read to decide whether to call it;
+  - the records its response is tested against.
+
+Run the generator again after adding endpoints; it only writes what is missing. The task then writes `openapi/admin.yaml`: commit it. An extension's gemspec that ships `git ls-files` includes it already.
+
+The app or engine is found from the directory the specs run in. An extension with more than one engine, or a different document title, sets them in `spec/swagger_helper.rb` before the require:
+
+```ruby
+SpreeDevTools::Openapi.engine = MyExtension::Engine
+SpreeDevTools::Openapi.title = 'My Extension Admin API'
+require 'spree_dev_tools/rspec/openapi'
+```
+
 ## Configuring
 
 If you want to disable Simplecov set the `SPREE_DEV_TOOLS_DISABLE_SIMPLECOV` ENV variable to any value.

data/lib/spree_dev_tools/generators/openapi/openapi_generator.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'spree_dev_tools/openapi'
+
+module SpreeDevTools
+  # Sets an extension, or a Spree application, up to document its Admin API
+  # endpoints, which makes each documented action an agent tool. In a Spree
+  # project:
+  #
+  #   spree generate spree_dev_tools:openapi
+  #
+  # Writes spec/swagger_helper.rb and the agent-tool contract spec, then a
+  # skeleton rswag spec for every admin action the extension's controllers
+  # serve that its document does not describe yet. The skeletons are skipped
+  # until filled in: each needs a description, which agents read, and the
+  # records its response is tested against. Run it again after adding
+  # endpoints; it writes only what is missing.
+  class OpenapiGenerator < Rails::Generators::Base
+    desc "Sets the extension up to generate openapi/admin.yaml and scaffolds rswag specs for undocumented admin actions"
+
+    class_option :engine, type: :string, desc: 'The extension engine, e.g. MyExtension::Engine (detected when omitted)'
+
+    CRUD_SUMMARIES = {
+      'index' => 'List %<plural>s',
+      'show' => 'Get a %<singular>s',
+      'create' => 'Create a %<singular>s',
+      'update' => 'Update a %<singular>s',
+      'destroy' => 'Delete a %<singular>s'
+    }.freeze
+
+    RESPONSE_CODES = { 'create' => '201', 'destroy' => '204' }.freeze
+
+    def set_destination
+      self.destination_root = engine.root.to_s
+    end
+
+    def create_swagger_helper
+      create_file 'spec/swagger_helper.rb', <<~RUBY, skip: true
+        # frozen_string_literal: true
+
+        # Integration specs that document the Admin API endpoints added here.
+        # `spree task openapi:generate` (in an extension, `bundle exec rake
+        # spree:openapi:generate`) writes them into openapi/admin.yaml, which
+        # Spree reads to build an agent tool for each documented action.
+        require '#{spec_helper}'
+        require 'spree_dev_tools/rspec/openapi'
+      RUBY
+    end
+
+    def create_contract_spec
+      create_file 'spec/agent_tools_spec.rb', <<~RUBY, skip: true
+        # frozen_string_literal: true
+
+        require '#{spec_helper}'
+        require 'spree/api/testing_support/agent_tools_contract'
+
+        # Fails when an admin action has no documented operation, an opt-out has
+        # no reason, or two actions would derive the same agent tool name.
+        RSpec.describe 'agent tools' do
+          it_behaves_like 'an engine whose admin writes are agent tools', #{reference}
+        end
+      RUBY
+    end
+
+    def scaffold_undocumented_operations
+      missing = undocumented_routes
+      if missing.empty?
+        say_status :ok, 'every admin action is documented', :green
+        return
+      end
+
+      missing.group_by { |route| route[:controller] }.each do |controller, routes|
+        # Mirrors the controller's namespace under admin, so two controllers
+        # with one name (an order's fulfillments and a seller's) never share
+        # a file.
+        relative = controller.controller_path.sub(%r{\Aspree/api/v3/admin/}, '')
+        path = File.join('spec', 'integration', 'admin', "#{relative}_spec.rb")
+        if File.exist?(File.join(destination_root, path))
+          say_status :exists, "#{path}: add #{routes.map { |route| "#{route[:verb].upcase} #{route[:path]}" }.join(', ')}", :yellow
+          next
+        end
+
+        create_file path, spec_for(controller, routes)
+      end
+    end
+
+    private
+
+    def reference
+      options[:engine] || SpreeDevTools::Openapi.reference
+    end
+
+    # An application boots Rails from rails_helper; an extension's
+    # spec_helper loads its dummy app.
+    def spec_helper
+      engine.is_a?(Rails::Application) ? 'rails_helper' : 'spec_helper'
+    end
+
+    def engine
+      @engine ||= if options[:engine]
+                    options[:engine].constantize
+                  else
+                    SpreeDevTools::Openapi.engine
+                  end
+    end
+
+    # The engine's admin routes whose operation no document describes.
+    def undocumented_routes
+      Spree::Api::AdminDocument.reset!
+      paths = Spree::Api::AdminDocument.document['paths'] || {}
+      root = File.expand_path(engine.root.to_s)
+
+      operations = Spree::Api::AgentOperations
+
+      # What the contract spec requires: the actions that become tools. CRUD
+      # reaches agents through the generic tools and needs no spec here.
+      operations.admin_routes.select do |route|
+        next false unless operations::WRITE_VERBS.include?(route[:verb]) && !operations::CRUD_ACTIONS.include?(route[:action])
+
+        controller = route[:controller]
+        location = controller && Object.const_source_location(controller.name)&.first
+        location&.start_with?(root) && paths.dig(route[:path], route[:verb]).nil?
+      end.uniq { |route| [route[:verb], route[:path]] }
+    end
+
+    def spec_for(controller, routes)
+      model = model_for(controller)
+      tag = model ? model.model_name.human.pluralize.titleize : controller.controller_name.titleize
+
+      blocks = routes.group_by { |route| route[:path] }.map do |path, path_routes|
+        operations = path_routes.map { |route| operation_for(controller, model, tag, route) }.join("\n\n")
+        segments = path.scan(/\{([a-z_]+)\}/).flatten.map do |segment|
+          named = segment == 'id' && model ? model.model_name.human : segment.delete_suffix('_id').humanize
+          "    parameter name: :#{segment}, in: :path, type: :string, required: true, description: '#{named} ID'"
+        end
+
+        ["  path '#{path}' do", *segments, '', operations, '  end'].join("\n")
+      end
+
+      <<~RUBY
+        # frozen_string_literal: true
+
+        require 'swagger_helper'
+
+        RSpec.describe '#{tag} Admin API', type: :request, swagger_doc: 'openapi/admin.yaml' do
+          include_context 'API v3 Admin'
+
+        #{blocks.join("\n\n")}
+        end
+      RUBY
+    end
+
+    def operation_for(controller, model, tag, route)
+      action = route[:action]
+      read = read_action?(controller, action)
+      body = controller.respond_to?(:request_params_schema) && controller.request_params_schema(action)
+      segments = route[:path].scan(/\{([a-z_]+)\}/).flatten
+
+      lines = []
+      lines << "    # TODO: check the summary; agents see it as the tool's name in words."
+      lines << "    #{route[:verb]} '#{summary_for(action, model)}' do"
+      lines << "      tags '#{tag}'"
+      lines << "      admin_operation :#{read ? 'read' : 'write'}, :#{controller._scoped_resource || 'TODO'}, description: <<~DESC"
+      lines << '        TODO: What this does and when to use it, for someone choosing the operation.'
+      lines << '        Agents read this to decide whether to call it.'
+      lines << '      DESC'
+      lines << '      request_body_for' if body
+      lines << ''
+      lines << "      response '#{RESPONSE_CODES.fetch(action, '200')}', 'TODO' do"
+      segments.each do |segment|
+        lines << "        let(:#{segment}) { skip('TODO: the record this operation acts on') }"
+      end
+      lines << "        let(:body) { skip('TODO: a valid request body') }" if body
+      # Nothing above defers the request, so skip it outright until the
+      # example is written: run_test! would otherwise send it unfinished.
+      lines << "        before { skip('TODO: the records this operation is tested against') }" if segments.empty? && !body
+      lines << ''
+      lines << '        run_test!'
+      lines << '      end'
+      lines << '    end'
+      lines.join("\n")
+    end
+
+    def summary_for(action, model)
+      singular = model ? model.model_name.human.downcase : 'record'
+      template = CRUD_SUMMARIES[action]
+      return format(template, singular: singular, plural: singular.pluralize) if template
+
+      "#{action.humanize} a #{singular}"
+    end
+
+    def model_for(controller)
+      Spree::Api::AgentResourceMap.model_for(controller)
+    end
+
+    # The scope kind the endpoint demands, by the controller's own rule.
+    def read_action?(controller, action)
+      instance = controller.allocate
+      reads = instance.respond_to?(:read_actions, true) ? instance.send(:read_actions) : %w[index show]
+      Array(reads).map(&:to_s).include?(action)
+    rescue StandardError, NotImplementedError
+      false
+    end
+  end
+end

data/lib/spree_dev_tools/openapi.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module SpreeDevTools
+  # Sets an extension's rswag specs up to generate the `openapi/admin.yaml`
+  # its gem ships. Spree merges that file into the Admin API document its
+  # agent tools are built from, so every action the extension documents is
+  # a tool (see Spree's "MCP Server Custom Tools" guide).
+  #
+  # The same for a Spree application documenting admin endpoints of its own:
+  # Spree reads the app's `openapi/admin.yaml` as it reads an extension's.
+  #
+  # In the extension's (or the app's) `spec/swagger_helper.rb`:
+  #
+  #   require 'spec_helper'
+  #   require 'spree_dev_tools/rspec/openapi'
+  #
+  # The extension's engine is found from the directory the specs run in, and
+  # in an application, where no engine's root is that directory, it is the
+  # application itself. An extension with more than one engine, or a
+  # different title, sets them before the require:
+  #
+  #   SpreeDevTools::Openapi.engine = MyExtension::Engine
+  #   SpreeDevTools::Openapi.title = 'My Extension Admin API'
+  module Openapi
+    class << self
+      attr_writer :engine, :title
+
+      # @return [Rails::Engine, Rails::Application]
+      def engine
+        @engine ||= detect_engine || detect_application || raise(
+          'spree_dev_tools could not tell which engine these specs document. ' \
+          'Set SpreeDevTools::Openapi.engine = MyExtension::Engine before requiring spree_dev_tools/rspec/openapi.'
+        )
+      end
+
+      # @return [String]
+      def title
+        @title ||= "#{name_of(engine).titleize} Admin API"
+      end
+
+      # How generated code refers to the engine: its class, or the
+      # application, which is reached as Rails.application.
+      #
+      # @return [String]
+      def reference
+        engine.is_a?(Rails::Application) ? 'Rails.application' : engine.name
+      end
+
+      private
+
+      def name_of(engine)
+        engine.is_a?(Rails::Application) ? engine.class.module_parent_name.to_s : engine.engine_name.to_s
+      end
+
+      def detect_application
+        root = File.expand_path(Dir.pwd)
+        Rails.application if Rails.application && File.expand_path(Rails.application.root.to_s) == root
+      end
+
+      # The engine whose gem the specs run from.
+      def detect_engine
+        root = File.expand_path(Dir.pwd)
+        Rails::Engine.descendants.reject { |klass| klass <= Rails::Application }.find do |klass|
+          klass.root && File.expand_path(klass.root.to_s) == root
+        end
+      end
+    end
+  end
+end

data/lib/spree_dev_tools/rspec/openapi.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Sets an extension's or an application's rswag specs up to generate the
+# `openapi/admin.yaml` it ships; see SpreeDevTools::Openapi. In
+# `spec/swagger_helper.rb` (an application requires rails_helper instead):
+#
+#   require 'spec_helper'
+#   require 'spree_dev_tools/rspec/openapi'
+require 'rswag/specs'
+begin
+  require 'spree/api/testing_support/openapi'
+rescue LoadError
+  raise LoadError, 'spree_dev_tools/rspec/openapi needs a Spree whose spree_api ships ' \
+                   'Spree::Api::TestingSupport::Openapi (the 6.0 patch release with agent tools from the Admin API document).'
+end
+require 'spree/api/testing_support/deterministic_openapi'
+require 'spree_dev_tools/openapi'
+
+RSpec.configure do |config|
+  Spree::Api::TestingSupport::Openapi.configure(
+    config, engine: SpreeDevTools::Openapi.engine, title: SpreeDevTools::Openapi.title
+  )
+end

data/lib/spree_dev_tools/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SpreeDevTools
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 
   # Returns the version of the currently loaded SpreeDevTools as a
   # <tt>Gem::Version</tt>.

data/lib/spree_dev_tools.rb

@@ -3,3 +3,4 @@ require 'spree_api'
 require 'spree_dev_tools/engine'
 require 'spree_dev_tools/version'
 require 'spree_dev_tools/generators/install/install_generator'
+require 'spree_dev_tools/generators/openapi/openapi_generator'

data/spree_dev_tools.gemspec

@@ -38,6 +38,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'rails-controller-testing'
   s.add_dependency 'rspec-activemodel-mocks'
   s.add_dependency 'rspec_junit_formatter'
+  s.add_dependency 'rswag-specs'
   s.add_dependency 'rspec-rails'
   s.add_dependency 'rspec-retry'
   s.add_dependency 'ruby-lsp', '>= 0.23.0'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree_dev_tools
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Vendo Connect Inc., Vendo Sp. z o.o.
@@ -233,6 +233,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rswag-specs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -335,6 +349,9 @@ files:
 - lib/spree_dev_tools/engine.rb
 - lib/spree_dev_tools/generators/install/install_generator.rb
 - lib/spree_dev_tools/generators/install/templates/spree_dev_tools.rb
+- lib/spree_dev_tools/generators/openapi/openapi_generator.rb
+- lib/spree_dev_tools/openapi.rb
+- lib/spree_dev_tools/rspec/openapi.rb
 - lib/spree_dev_tools/rspec/spec_helper.rb
 - lib/spree_dev_tools/rspec/support/active_job.rb
 - lib/spree_dev_tools/rspec/support/database_cleaner.rb