spree_core 6.0.2 → 6.0.3

data/lib/spree/agent_tool.rb

@@ -21,6 +21,12 @@ module Spree
   #     end
   #   end
 class AgentTool
+    # The parameter every generic resource tool takes for a resource that
+    # lives under another record, such as an order's items.
+    PARENT_ID_DESCRIPTION = 'For a resource reached through another record (describe_resource names ' \
+                            'it as parent, e.g. an order for its items, discounts and fees): that ' \
+                            'record\'s id as shown in search results'.freeze
+
     # 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
@@ -85,6 +91,26 @@ class AgentTool
         declared_mutating == true
       end
 
+      # Declares that this tool only adds — it creates a record or a file and
+      # never overwrites, removes or changes the state of one that exists.
+      # Every other mutating tool counts as destructive, so a tool that
+      # forgets to say is warned about more, never less.
+      #
+      # Unlike the declarations above, this one is not inherited: a subclass
+      # that overrides `call` may well change existing data, so it is
+      # destructive until it says otherwise itself.
+      #
+      # @return [void]
+      def additive!
+        @additive = true
+      end
+
+      # @return [Boolean] whether the tool may overwrite, remove or change
+      #   the state of existing data
+      def destructive?
+        mutating? && @additive != true
+      end
+
       # @param name [Symbol]
       # @param type [Symbol] JSON schema type
       # @param description [String]
@@ -105,6 +131,44 @@ class AgentTool
       def params
         declared_params
       end
+
+      # The declared params as JSON Schema, which is what an adapter hands a
+      # client. A tool built from an OpenAPI operation overrides this with the
+      # operation's own schema, nested properties included.
+      #
+      # @return [Hash]
+      def input_schema
+        properties = params.to_h do |name, options|
+          property = { 'type' => json_type(options[:type]) }
+          property['description'] = options[:description] if options[:description].present?
+          # An array must say what it holds: a client validating arguments
+          # against the schema refuses the call otherwise.
+          property['items'] = { 'type' => json_type(options[:items] || :string) } if property['type'] == 'array'
+
+          [name.to_s, property]
+        end
+
+        {
+          'type' => 'object',
+          'properties' => properties,
+          'required' => params.select { |_name, options| options[:required] }.keys.map(&:to_s)
+        }
+      end
+
+      private
+
+      # A tool declares Ruby-ish types; JSON Schema wants its own names, and
+      # anything unrecognised is a string, which every client can render.
+      def json_type(type)
+        case type&.to_sym
+        when :boolean then 'boolean'
+        when :integer then 'integer'
+        when :number, :float, :decimal then 'number'
+        when :object, :hash then 'object'
+        when :array then 'array'
+        else 'string'
+        end
+      end
     end
 
     # @return [Spree::AgentTools::Context] who is asking, and where
@@ -115,7 +179,7 @@ class AgentTool
       @context = context
     end
 
-    delegate :tool_name, :description, :permission, :mutating?, :params, to: :class
+    delegate :tool_name, :description, :permission, :mutating?, :destructive?, :params, to: :class
 
     # Runs the tool. Subclasses implement this with keyword arguments matching
     # their declared params.
@@ -167,6 +231,46 @@ class AgentTool
 
     protected
 
+    # A resource that lives under a parent — a promotion's rules, an order's
+    # payments — has no path of its own to dispatch to, so every tool refuses
+    # it the same way: naming the parent and, where the parent carries the
+    # rows as an attribute, how to write and read them there. The old answer
+    # was the endpoint's 404 for a parent id nobody supplied.
+    #
+    # @param entry [Spree::AgentTools::ResourceMap::Entry]
+    # @param verb [String] 'searched', 'fetched', 'created'…
+    # @param action [Symbol] the operation whose path runs under the parent
+    # @return [Hash]
+    def nested_resource_error(entry, verb, action)
+      # A top-level path left unfilled is missing its own id, not a parent.
+      return { error: "Pass the id of the #{entry.key.singularize.tr('_', ' ')} to use." } unless entry.nested?(action)
+
+      parent = entry.parent_key(action)
+      parent_entry = Spree::AgentTools::ResourceMap.find(parent)
+      attribute = parent_entry&.nested_typed_families&.key(entry.model_class)
+
+      owner = parent.singularize.tr('_', ' ')
+      sentences = ["#{entry.key} belong to #{owner.match?(/\A[aeiou]/) ? 'an' : 'a'} #{owner} and cannot be #{verb} on their own."]
+      # Offered only where one parent id fills the path; a resource nested
+      # twice has no generic route.
+      reachable = entry.path_for(action, id: 'id', parent_id: 'parent').present?
+      sentences << "Pass the #{owner}'s id as parent_id to reach them under it." if reachable
+      # Each suggested call is one this caller may actually make; a hint
+      # that leads straight to a permission refusal is worse than none.
+      readable = parent_entry && context.permitted?(parent_entry.permission)
+      writable = parent_entry&.write_permission.present? && context.permitted?(parent_entry.write_permission)
+      if attribute && writable
+        sentences << "Write them in the #{attribute} attribute of #{parent} — describe_resource #{parent} shows the shape and the accepted types."
+      end
+      if attribute && readable && parent_entry.expandable_associations.include?(attribute)
+        sentences << "Read them with get_resource on #{parent} and expand: [\"#{attribute}\"]."
+      elsif readable && !attribute
+        sentences << "Start from #{parent}: get_resource with expand lists what it carries (describe_resource #{parent} names the options)."
+      end
+
+      { error: sentences.join(' '), parent: parent }
+    end
+
     # Refuses unless this admin may take `action` on `record`.
     #
     # Holding `write_products` says an admin may edit products; it does not

data/lib/spree/agent_tools/default_catalog.rb

@@ -1,15 +1,11 @@
 module Spree
   module AgentTools
-    # The tools Spree ships: the generic read tools, and the workflows exposed
-    # as write tools.
+    # The hand-written tools Spree ships: the generic reads and writes,
+    # reporting, imports, files and stock.
     #
-    # The write allowlist is the whole catalog of back-office writes an agent
-    # may make. Every entry names a `Spree::Dependencies` key, so a host app
-    # that swaps in its own workflow class keeps the tool and gets the
-    # replacement's schema; and a permission, which must equal the write scope
-    # of the admin controller that invokes the same workflow — a contract spec
-    # in `spree_api` fails when the two disagree, or when a controller gains a
-    # workflow that is neither listed here nor excluded below.
+    # Back-office actions are not listed here. Every Admin API action is a
+    # tool built from its OpenAPI operation ({OperationCatalog}); an action
+    # that should not be one is marked in its rswag spec, with the reason.
     module DefaultCatalog
       # Read tools, and the writes that are not workflows.
       TOOLS = %w[
@@ -33,15 +29,11 @@ module Spree
       ].freeze
 
 
-      # Workflow key => permission, or => {permission:, except:, summary:}.
+      # @deprecated The 6.0.0 workflow allowlist, kept only so a reference to
+      #   it does not break through 6.0.x. Nothing reads it: Admin API
+      #   operations are tools on their own. Removed in 6.1.
       WORKFLOWS = {
         # Catalog
-        #
-        # The three status moves below run in this process rather than through
-        # an endpoint, because the Admin API has none for them: `PATCH` writes
-        # the column and the bulk action uses `update_all`, so neither
-        # publishes the status event nor withdraws an open seller submission.
-        # They dispatch as soon as an admin status endpoint exists.
         product_activate_workflow: 'write_products',
         product_draft_workflow: 'write_products',
         product_archive_workflow: 'write_products',
@@ -59,8 +51,10 @@ module Spree
 
         # Orders. `restock_items` is hidden: it is deprecated and ignored, so
         # offering it would invite a model to set something that does nothing.
+        # `validated` is for callers that already ran their own veto; offered
+        # to a model it would be a way around orders.complete.validate.
         order_cancel_workflow: { permission: 'write_orders', except: %i[restock_items] },
-        order_complete_workflow: 'write_orders',
+        order_complete_workflow: { permission: 'write_orders', except: %i[validated] },
 
         # Fulfillment
         fulfillment_create_workflow: 'write_fulfillments',
@@ -103,9 +97,9 @@ module Spree
         tax_exemption_certificate_verify_workflow: 'write_customers'
       }.freeze
 
-      # Workflows an admin controller invokes that are deliberately NOT tools,
-      # each with the reason. The contract spec reads this list, so a workflow
-      # can never be quietly dropped: it is exposed, or it is here.
+      # @deprecated The 6.0.0 exclusion list, kept like {WORKFLOWS}. Its
+      #   reasons now travel as `agent_tool false, reason:` on the operation's
+      #   rswag spec. Removed in 6.1.
       # The email template editor is a draft-and-publish surface: its steps
       # move a draft through revisions against a live preview, and they mean
       # nothing outside that screen. Publishing one sends real mail in the
@@ -172,9 +166,10 @@ module Spree
         # @return [void]
         def install(registry)
           TOOLS.each { |tool| registry << tool }
-          registry.expose_workflows(**WORKFLOWS)
         end
       end
+
+      deprecate_constant :WORKFLOWS, :EXCLUDED_WORKFLOWS
     end
   end
 end

data/lib/spree/agent_tools/legacy_tools.rb

@@ -0,0 +1,212 @@
+module Spree
+  module AgentTools
+    # The workflow tools Spree 6.0.0 offered, by the name and parameters a
+    # client saw then, and the operation each now runs.
+    #
+    # 6.0.0 derived a tool from a workflow's `perform` signature, so its
+    # parameters were the workflow's keywords (`order`, `reason`); a tool now
+    # takes the operation's own (`id`, `cancel_reason_id`). This table, written
+    # once from the 6.0.0 schemas, keeps those calls working through 6.0.x. It
+    # is an explicit list, not a rule: nothing here guesses one name from
+    # another.
+    #
+    # A parameter mapped to nil never reached the endpoint in 6.0.0 either; it
+    # is ignored, and the result says so. One mapped to `:merge` was a hash of
+    # fields, merged into the body, which is what 6.0.0 did with it.
+    #
+    # `deliveries_update_tracking` is not here: 6.0.0 sent it to the
+    # mark-delivered endpoint and dropped its tracking fields, so a call meant
+    # to record tracking marked the delivery delivered. No endpoint sets a
+    # carrier status, so the name no longer answers rather than doing that.
+    #
+    # Removed in 6.1, with the names that are no longer listed.
+    # See docs/plans/6.0-agent-tools-from-openapi.md.
+    module LegacyTools
+      # Old tool name => the operation it runs and its renamed parameters.
+      TOOLS = {
+        'catalogs_activate' => {
+          verb: 'patch', path: '/api/v3/admin/catalogs/{id}/activate',
+          parameters: { 'catalog' => 'id' }
+        },
+        'catalogs_deactivate' => {
+          verb: 'patch', path: '/api/v3/admin/catalogs/{id}/deactivate',
+          parameters: { 'catalog' => 'id' }
+        },
+        'fulfillments_create' => {
+          verb: 'post', path: '/api/v3/admin/orders/{order_id}/fulfillments',
+          parameters: {
+            'order' => 'order_id', 'stock_location' => 'stock_location_id',
+            'source_fulfillment' => 'source_fulfillment_id', 'delivery_method' => 'delivery_method_id'
+          }
+        },
+        'fulfillments_mark_delivered' => {
+          verb: 'patch', path: '/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered',
+          parameters: { 'fulfillment' => 'id' }
+        },
+        'orders_cancel' => {
+          verb: 'patch', path: '/api/v3/admin/orders/{id}/cancel',
+          parameters: { 'order' => 'id', 'canceled_at' => nil, 'reason' => 'cancel_reason_id', 'note' => 'cancel_note' }
+        },
+        'orders_complete' => {
+          verb: 'patch', path: '/api/v3/admin/orders/{id}/complete',
+          parameters: { 'order' => 'id' }
+        },
+        'payments_capture' => {
+          verb: 'patch', path: '/api/v3/admin/orders/{order_id}/payments/{id}/capture',
+          parameters: { 'payment' => 'id' }
+        },
+        'payments_void' => {
+          verb: 'patch', path: '/api/v3/admin/orders/{order_id}/payments/{id}/void',
+          parameters: { 'payment' => 'id' }
+        },
+        'price_lists_activate' => {
+          verb: 'patch', path: '/api/v3/admin/price_lists/{id}/activate',
+          parameters: { 'price_list' => 'id' }
+        },
+        'price_lists_deactivate' => {
+          verb: 'patch', path: '/api/v3/admin/price_lists/{id}/deactivate',
+          parameters: { 'price_list' => 'id' }
+        },
+        'products_activate' => {
+          verb: 'patch', path: '/api/v3/admin/products/{id}/activate',
+          parameters: { 'product' => 'id' }
+        },
+        'products_approve' => {
+          verb: 'patch', path: '/api/v3/admin/products/{id}/approve',
+          parameters: { 'product' => 'id' }
+        },
+        'products_archive' => {
+          verb: 'patch', path: '/api/v3/admin/products/{id}/archive',
+          parameters: { 'product' => 'id' }
+        },
+        'products_draft' => {
+          verb: 'patch', path: '/api/v3/admin/products/{id}/draft',
+          parameters: { 'product' => 'id' }
+        },
+        'products_reject' => {
+          verb: 'patch', path: '/api/v3/admin/products/{id}/reject',
+          parameters: { 'product' => 'id' }
+        },
+        'purchase_orders_cancel' => {
+          verb: 'patch', path: '/api/v3/admin/purchase_orders/{id}/cancel',
+          parameters: { 'purchase_order' => 'id' }
+        },
+        'purchase_orders_close' => {
+          verb: 'patch', path: '/api/v3/admin/purchase_orders/{id}/close',
+          parameters: { 'purchase_order' => 'id' }
+        },
+        'purchase_orders_mark_draft' => {
+          verb: 'patch', path: '/api/v3/admin/purchase_orders/{id}/mark_draft',
+          parameters: { 'purchase_order' => 'id' }
+        },
+        'purchase_orders_mark_ordered' => {
+          verb: 'patch', path: '/api/v3/admin/purchase_orders/{id}/mark_ordered',
+          parameters: { 'purchase_order' => 'id' }
+        },
+        'purchase_orders_receive' => {
+          verb: 'post', path: '/api/v3/admin/purchase_orders/{purchase_order_id}/stock_receipts',
+          parameters: { 'purchase_order' => 'purchase_order_id' }
+        },
+        'refunds_create' => {
+          verb: 'post', path: '/api/v3/admin/orders/{order_id}/refunds',
+          parameters: {
+            'payment' => 'payment_id', 'reason' => 'refund_reason_id', 'originator' => nil,
+            'order' => 'order_id', 'tax_amount' => nil
+          }
+        },
+        'seller_requirement_submissions_accept' => {
+          verb: 'patch', path: '/api/v3/admin/sellers/{seller_id}/requirement_submissions/{id}/accept',
+          parameters: { 'submission' => 'id' }
+        },
+        'seller_requirement_submissions_reject' => {
+          verb: 'patch', path: '/api/v3/admin/sellers/{seller_id}/requirement_submissions/{id}/reject',
+          parameters: { 'submission' => 'id' }
+        },
+        'seller_requirement_submissions_waive' => {
+          verb: 'post', path: '/api/v3/admin/sellers/{seller_id}/requirement_submissions',
+          parameters: { 'seller' => 'seller_id', 'requirement' => 'requirement_id' }
+        },
+        'sellers_approve' => {
+          verb: 'patch', path: '/api/v3/admin/sellers/{id}/approve',
+          parameters: { 'seller' => 'id' }
+        },
+        'sellers_invite' => {
+          verb: 'post', path: '/api/v3/admin/sellers/{id}/invite',
+          parameters: { 'seller' => 'id', 'inviter' => nil, 'role' => 'role_id' }
+        },
+        'sellers_reject' => {
+          verb: 'patch', path: '/api/v3/admin/sellers/{id}/reject',
+          parameters: { 'seller' => 'id' }
+        },
+        'sellers_reopen_onboarding' => {
+          verb: 'patch', path: '/api/v3/admin/sellers/{id}/reopen_onboarding',
+          parameters: { 'seller' => 'id' }
+        },
+        'sellers_suspend' => {
+          verb: 'patch', path: '/api/v3/admin/sellers/{id}/suspend',
+          parameters: { 'seller' => 'id' }
+        },
+        'shipping_labels_purchase' => {
+          verb: 'post', path: '/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels',
+          parameters: { 'owner' => 'fulfillment_id' }
+        },
+        'shipping_labels_refund' => {
+          verb: 'patch', path: '/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund',
+          parameters: { 'shipping_label' => 'id' }
+        },
+        'stock_transfers_cancel' => {
+          verb: 'patch', path: '/api/v3/admin/stock_transfers/{id}/cancel',
+          parameters: { 'stock_transfer' => 'id' }
+        },
+        'stock_transfers_close' => {
+          verb: 'patch', path: '/api/v3/admin/stock_transfers/{id}/close',
+          parameters: { 'stock_transfer' => 'id' }
+        },
+        'stock_transfers_mark_draft' => {
+          verb: 'patch', path: '/api/v3/admin/stock_transfers/{id}/mark_draft',
+          parameters: { 'stock_transfer' => 'id' }
+        },
+        'stock_transfers_mark_in_transit' => {
+          verb: 'patch', path: '/api/v3/admin/stock_transfers/{id}/mark_in_transit',
+          parameters: { 'stock_transfer' => 'id' }
+        },
+        'stock_transfers_mark_ready' => {
+          verb: 'patch', path: '/api/v3/admin/stock_transfers/{id}/mark_ready',
+          parameters: { 'stock_transfer' => 'id' }
+        },
+        'stock_transfers_receive' => {
+          verb: 'post', path: '/api/v3/admin/stock_transfers/{stock_transfer_id}/stock_receipts',
+          parameters: { 'stock_transfer' => 'stock_transfer_id' }
+        },
+        'tax_exemption_certificates_verify' => {
+          verb: 'patch', path: '/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify',
+          parameters: { 'certificate' => 'id' }
+        },
+        'variants_create' => {
+          verb: 'post', path: '/api/v3/admin/products/{product_id}/variants',
+          parameters: { 'product' => 'product_id', 'attributes' => :merge }
+        },
+        'variants_update' => {
+          verb: 'patch', path: '/api/v3/admin/products/{product_id}/variants/{id}',
+          parameters: { 'variant' => 'id', 'attributes' => :merge }
+        }
+      }.freeze
+
+      class << self
+        # The 6.0.0 parameters of a tool that keeps its name, when it still
+        # runs the same operation.
+        #
+        # @param name [String]
+        # @param verb [String]
+        # @param path [String] the OpenAPI path
+        # @return [Hash{String => String, Symbol, nil}]
+        def parameters_for(name, verb, path)
+          tool = TOOLS[name.to_s]
+          return {} unless tool && tool[:verb] == verb.to_s && tool[:path] == path
+
+          tool[:parameters]
+        end
+      end
+    end
+  end
+end

data/lib/spree/agent_tools/operation_catalog.rb

@@ -0,0 +1,206 @@
+module Spree
+  module AgentTools
+    # Every Admin API operation an agent may call by name, and what it takes.
+    #
+    # A contract like {ResourceMap}: core declares the shape, and `spree_api`
+    # fills it from the Admin API's OpenAPI document — core's and every
+    # extension's — and the routes behind it. An operation that gains an
+    # endpoint is a tool in the same commit, with the summary, description and
+    # request body its rswag spec wrote.
+    #
+    # See docs/plans/6.0-agent-tools-from-openapi.md.
+    module OperationCatalog
+      # @!attribute name
+      #   @return [String] the tool name, `orders_cancel`
+      # @!attribute verb
+      #   @return [String] 'post', 'patch', 'put', 'delete' or 'get'
+      # @!attribute path
+      #   @return [String] the OpenAPI path, with `{name}` segments
+      # @!attribute description
+      #   @return [String] what the model reads when choosing the tool
+      # @!attribute summary
+      #   @return [String] the operation summary, for the confirmation line
+      # @!attribute permission
+      #   @return [String] the scope gating it, from the routed controller
+      # @!attribute resource_key
+      #   @return [String, nil] the resource-map key of the routed controller's
+      #     model, so a parent segment can be read off the record
+      # @!attribute path_params
+      #   @return [Array<String>] the dynamic segments, in path order
+      # @!attribute body_properties
+      #   @return [Hash{String => Hash}] the request body's JSON Schema
+      #     properties, references inlined
+      # @!attribute body_required
+      #   @return [Array<String>]
+      # @!attribute path_descriptions
+      #   @return [Hash{String => String}]
+      # @!attribute listed
+      #   @return [Boolean] false for a 6.0.0 name kept callable through 6.0.x
+      # @!attribute legacy_parameters
+      #   @return [Hash{String => String, nil}] 6.0.0 parameter => its name now
+      Entry = Struct.new(:name, :verb, :path, :description, :summary, :permission, :resource_key,
+                         :path_params, :body_properties, :body_required, :path_descriptions,
+                         :listed, :legacy_parameters, keyword_init: true) do
+        # @return [Boolean] a read opted in to the catalog
+        def read?
+          verb == 'get'
+        end
+
+        # @return [Boolean] whether the call changes the store
+        def mutating
+          !read?
+        end
+
+        # The resource each `{x_id}` segment names, read off the path itself —
+        # `/orders/{order_id}/items` names `orders` — so a renamed nested
+        # route still points at the right resource.
+        #
+        # @return [Hash{String => String}] segment => resource key
+        def segment_keys
+          path.scan(%r{/([a-z_]+)/\{([a-z_]+_id)\}}).to_h { |key, segment| [segment, key] }
+        end
+
+        # The segments a call may leave out, read off the record a later
+        # segment names. The innermost is the record the call is about, never
+        # one to read off another.
+        #
+        # @return [Hash{String => String}] segment => resource key
+        def parent_keys
+          segment_keys.except(path_params.last)
+        end
+
+        # @param values [Hash{String => String}] path segment => value
+        # @return [String, nil] nil while a segment is unfilled
+        def path_for(values)
+          filled = path.gsub(/\{([a-z_]+)\}/) do
+            value = values[Regexp.last_match(1)]
+            value.present? ? ERB::Util.url_encode(value.to_s) : Regexp.last_match(0)
+          end
+          filled unless filled.include?('{')
+        end
+
+        # The tool's arguments as JSON Schema: the path segments and the
+        # request body, side by side.
+        #
+        # A segment or field a 6.0.0 name still reaches is left out of
+        # `required` through 6.0.x — a client validating against the schema
+        # would otherwise refuse the old name before the tool could map it —
+        # and so is a parent segment, which the tool can read off the record
+        # the call names. The tool checks both itself.
+        #
+        # @return [Hash]
+        def input_schema
+          properties = path_params.to_h do |segment|
+            [segment, { 'type' => 'string', 'description' => path_descriptions[segment] }.compact]
+          end.merge(body_properties)
+
+          aliased = legacy_parameters.values.grep(String)
+          parents = parent_keys.keys
+          # A 6.0.0 name no longer listed keeps the 6.0.0 contract, which
+          # required nothing the operation's body now does.
+          required = listed ? (path_params + body_required).uniq - aliased - parents : []
+
+          { 'type' => 'object', 'properties' => properties, 'required' => required }
+        end
+      end
+
+      class << self
+        # How the catalog fills itself the first time it is read. `spree_api`
+        # sets it to its walk over the document; an installation without the
+        # API engine has no operations to offer.
+        #
+        # @return [#call, nil]
+        attr_accessor :deriver
+
+        # @return [Array<Entry>] the operations offered by name
+        def all
+          derive!
+          entries.values
+        end
+
+        # The 6.0.0 names kept callable through 6.0.x, which no listing shows.
+        #
+        # @return [Array<Entry>]
+        def aliases
+          derive!
+          alias_entries.values
+        end
+
+        # A tool by its name, including a 6.0.0 name no longer listed.
+        #
+        # @param name [String]
+        # @return [Entry, nil]
+        def find(name)
+          derive!
+          entries[name.to_s] || alias_entries[name.to_s]
+        end
+
+        # Registers one operation. Re-registering a name replaces it, because
+        # the walk runs again after a code reload.
+        #
+        # @return [Entry]
+        def register(**attributes)
+          entry = build(listed: true, **attributes)
+          entries[entry.name] = entry
+        end
+
+        # Registers a 6.0.0 name for an operation, callable but not listed.
+        # A name an offered operation already has keeps that operation.
+        #
+        # @return [Entry, nil]
+        def register_alias(**attributes)
+          entry = build(**attributes, listed: false)
+          alias_entries[entry.name] = entry unless entries.key?(entry.name)
+        end
+
+        # @return [void]
+        def reset!
+          @entries = {}
+          @alias_entries = {}
+        end
+
+        # Marks the catalog for rebuilding on its next read.
+        #
+        # @return [void]
+        def stale!
+          @derived = false
+        end
+
+        # Fills the catalog once, under a mutex. The flag is set only once the
+        # deriver has finished, so a second reader waits on the mutex instead
+        # of reading a catalog the deriver has just emptied. Nothing the
+        # deriver calls reads the catalog back, so it cannot recurse.
+        #
+        # @return [void]
+        def derive!
+          return if @derived || deriver.nil?
+
+          derive_mutex.synchronize do
+            next if @derived
+
+            deriver.call
+            @derived = true
+          end
+        end
+
+        private
+
+        def build(**attributes)
+          Entry.new(legacy_parameters: {}, body_properties: {}, body_required: [], path_descriptions: {}, **attributes)
+        end
+
+        def entries
+          @entries ||= {}
+        end
+
+        def alias_entries
+          @alias_entries ||= {}
+        end
+
+        def derive_mutex
+          @derive_mutex ||= Mutex.new
+        end
+      end
+    end
+  end
+end