spree_core 6.0.0.rc6 → 6.0.0

data/lib/generators/spree/api_resource/api_resource_generator.rb

@@ -108,7 +108,7 @@ module Spree
 
     # Override parent: skip if the model existed before this run. Migrations
     # are append-only — schema changes get a separate migration:
-    #   pnpm exec spree rails g migration AddFooToBar foo:string
+    #   pnpm exec spree generate migration AddFooToBar foo:string
     def create_migration_file
       if @model_existed_before_run
         say_status :skip, 'migration (model already exists; add a new migration for schema changes)', :yellow
@@ -295,7 +295,7 @@ module Spree
       end
       say "    4. Add `has_many :#{plural_name}` to Spree::Store" if store_scoped?
       if options[:store] || options[:admin]
-        say "    #{store_scoped? ? 5 : 4}. Run the specs:  pnpm exec spree rspec spec/controllers/spree/api/v3/"
+        say "    #{store_scoped? ? 5 : 4}. Run the specs:  pnpm exec spree test spec/controllers/spree/api/v3/"
       end
       say ''
     end

data/lib/spree/core/configuration.rb

@@ -195,6 +195,12 @@ module Spree
       # imports
       preference :large_import_threshold, :integer, default: 500, env: 'SPREE_LARGE_IMPORT_THRESHOLD' # imports with more rows than this skip per-row UI broadcasts and use bulk processing
 
+      # maintenance tasks
+      # Turn off to run upgrade steps only from the command line: the dashboard
+      # page and its Admin API endpoints are refused. For hosts where the people
+      # holding a store's admin role are not the ones operating the installation,
+      # such as a platform serving many merchants from one database.
+      preference :maintenance_tasks_dashboard_enabled, :boolean, default: true, env: 'SPREE_MAINTENANCE_TASKS_DASHBOARD_ENABLED'
     end
   end
 end

data/lib/spree/core/engine.rb

@@ -46,6 +46,7 @@ module Spree
                                :admin_agent_tools,
                                :store_agent_tools,
                                :integrations,
+                               :maintenance_tasks,
                                :number_generators,
                                :subscribers,
                                :store_authentication_strategies,
@@ -77,7 +78,8 @@ module Spree
         # Core's defaults are concatenated in after_initialize below.
         %i[subscribers actor_classes commission_rules delivery_method_rules seller_requirements
            delivery_rate_providers tax_providers pricing_providers inventory_providers
-           payout_providers digital_asset_providers delivery_profile_types pickup_point_providers].each do |registry|
+           payout_providers digital_asset_providers delivery_profile_types pickup_point_providers
+           maintenance_tasks].each do |registry|
           app.config.spree[registry] = []
         end
         app.config.spree.line_item_comparison_hooks = Set.new
@@ -540,6 +542,13 @@ module Spree
 
         Rails.application.config.spree.integrations = []
 
+        # Upgrade steps backed by a task class are registered from the manifests
+        # that name them, so adding a step never means editing a second list.
+        Rails.application.config.spree.maintenance_tasks.concat [
+          'Spree::MaintenanceTasks::UpgradeStep',
+          *Spree::Upgrade.steps.filter_map { |step| step['task_class'] }
+        ]
+
         Rails.application.config.spree.validators.addresses = [
           Spree::Addresses::PhoneValidator
         ]

data/lib/spree/core/permissions/default_catalog.rb

@@ -201,6 +201,13 @@ module Spree
         })
         catalog.register_scope(:integrations, group: :settings, resources: -> { [Spree::Integration] })
 
+        # Sits with the other sensitive access grants rather than under
+        # settings: a task can rewrite any data in the install, so out of the
+        # box only the admin role holds it (docs/plans/6.0-maintenance-tasks.md).
+        catalog.register_scope(:maintenance_tasks, group: :access, resources: -> {
+          [Spree::MaintenanceTaskRun, :maintenance_task]
+        })
+
         # The CORS allowlist is a credential as much as a key is: an origin on
         # it may call the cookie-authenticated refresh endpoint from a browser
         # and read back any signed-in admin's access token. So it sits with

data/lib/spree/core/version.rb

@@ -1,5 +1,5 @@
 module Spree
-  VERSION = '6.0.0.rc6'.freeze
+  VERSION = '6.0.0'.freeze
 
   def self.version
     VERSION

data/lib/spree/core.rb

@@ -135,7 +135,8 @@ module Spree
       stock_reservations: :default,
       tax_identifiers: :default,
       data_requests: :default,
-      payouts: :default
+      payouts: :default,
+      maintenance_tasks: :default
     ).tap do |queues|
       # @deprecated The taxons queue was renamed to categories in 6.0; removed in 6.1.
       queues.define_singleton_method(:taxons) do
@@ -455,6 +456,19 @@ module Spree
     custom_fields
   end
 
+  # Registered maintenance task class names — the tasks an operator can run
+  # from the dashboard, the Admin API or the CLI
+  # (docs/plans/6.0-maintenance-tasks.md). Extensions append their own from an
+  # initializer:
+  #
+  #   Spree.maintenance_tasks << 'SpreeReviews::MaintenanceTasks::RecountRatings'
+  #
+  # Class names rather than classes, so registration is safe at initializer
+  # time and survives code reloading in development.
+  #
+  # @return [Array<String, Class>]
+  singleton_class.delegate :maintenance_tasks, :maintenance_tasks=, to: :spree_config
+
   # Registry mapping a numbered resource to the generator that produces its
   # document numbers. With no entry, the store's `document_number_format`
   # preference picks between the sequential and random strategies.
@@ -644,6 +658,7 @@ require 'spree/core/version'
 require 'spree/core/number_generator'
 require 'spree/number_generators/registry'
 require 'spree/migrations'
+require 'spree/upgrade'
 require 'spree/validators'
 require 'spree/core/engine'
 

data/lib/spree/testing_support/factories/maintenance_task_run_factory.rb

@@ -0,0 +1,7 @@
+FactoryBot.define do
+  factory :maintenance_task_run, class: 'Spree::MaintenanceTaskRun' do
+    task_name { 'Spree::MaintenanceTasks::BackfillOrderMarkets' }
+    status { 'enqueued' }
+    initiated_via { 'api' }
+  end
+end

data/lib/spree/upgrade.rb

@@ -0,0 +1,189 @@
+module Spree
+  # Reads the upgrade manifests shipped inside spree_core — the list of data
+  # steps an installation must run after `db:migrate` for a given release
+  # boundary (docs/plans/6.0-maintenance-tasks.md).
+  #
+  # Extracted from lib/tasks/upgrade.rake so the dashboard and the maintenance
+  # task runner can read the same manifests the rake walk does; the rake file
+  # keeps the walking and printing.
+  module Upgrade
+    # The first release whose upgrade steps run as maintenance tasks. Nothing
+    # recorded the steps of earlier releases, so the dashboard starts here; the
+    # command line still walks every manifest.
+    FIRST_TRACKED_RELEASE = '6.0'.freeze
+
+    # Two-segment "5.5" form of the installed Spree version.
+    #
+    # @return [String]
+    def self.installed_minor_version
+      Spree.version.split('.').first(2).join('.')
+    end
+
+    # Root directory containing N_M_to_O_P/manifest.yml files inside the
+    # spree_core gem.
+    #
+    # @return [String]
+    def self.manifests_root
+      File.expand_path('upgrades', __dir__)
+    end
+
+    # All available manifest directories, parsed into { from:, to:, dir: }.
+    # Sorted by `to` ascending, with `from` as a tiebreaker (smallest first)
+    # for the rare case where two manifests share a `to` boundary.
+    #
+    # @return [Array<Hash>]
+    def self.available_manifests
+      Dir.glob(File.join(manifests_root, '*_to_*')).filter_map do |dir|
+        name = File.basename(dir)
+        match = name.match(/\A([\d_]+)_to_([\d_]+)\z/)
+        next unless match
+
+        { from: match[1].tr('_', '.'), to: match[2].tr('_', '.'), dir: dir }
+      end.sort_by { |manifest| version_parts(manifest[:to]) + version_parts(manifest[:from]) }
+    end
+
+    # Every manifest with its steps loaded, in walk order. Read once per
+    # process: the files ship inside the gem and change only with a deploy.
+    #
+    # @return [Array<Hash>]
+    def self.manifests
+      @manifests ||= available_manifests.map do |entry|
+        YAML.safe_load_file(File.join(entry[:dir], 'manifest.yml')).freeze
+      end.freeze
+    end
+
+    # Every step of every manifest, in walk order, each carrying the manifest
+    # boundary it belongs to so callers can group without re-reading the files.
+    #
+    # @return [Array<Hash>]
+    def self.steps
+      @steps ||= manifests.flat_map do |manifest|
+        manifest['steps'].map do |step|
+          step.merge('from' => manifest['from'], 'to' => manifest['to'], 'docs' => manifest['docs'])
+        end
+      end.freeze
+    end
+
+    # Whether a step belongs to a release whose runs are recorded, and so has a
+    # place in the dashboard's checklist.
+    #
+    # @param step [Hash] a manifest step
+    # @return [Boolean]
+    def self.tracked?(step)
+      compare(step['to'], FIRST_TRACKED_RELEASE) >= 0
+    end
+
+    # The task a step runs: its own class, or the shared runner for a step
+    # that names a rake task.
+    #
+    # @param step [Hash] a manifest step
+    # @return [String] a task class name
+    def self.task_class_name(step)
+      step['task_class'] || 'Spree::MaintenanceTasks::UpgradeStep'
+    end
+
+    # The arguments that start a step's task: a rake-backed step is named by
+    # its id, so the shared runner knows which rake task to invoke.
+    #
+    # @param step [Hash] a manifest step
+    # @return [Hash]
+    def self.task_arguments(step)
+      step['task_class'] ? {} : { 'step_id' => step['id'] }
+    end
+
+    # @param step_id [String]
+    # @return [Hash, nil]
+    def self.find_step(step_id)
+      return nil if step_id.blank?
+
+      steps.find { |step| step['id'] == step_id.to_s }
+    end
+
+    # The boundary this installation has already completed, and therefore the
+    # point a pending list starts from.
+    #
+    # Falls back to the release before the installed one when nothing has been
+    # stamped: an installation running 6.0 has, by far most often, come from
+    # 5.6, and showing every step of every manifest ever written is worse than
+    # showing the one boundary that is almost certainly right. A store that
+    # skipped releases runs the earlier steps from the command line, which
+    # walks every manifest whatever the boundary.
+    #
+    # @return [String, nil]
+    def self.completed_boundary
+      Spree::UpgradeRecord.current_version || previous_boundary
+    end
+
+    # The `to` of the manifest immediately below the installed version.
+    #
+    # @return [String, nil]
+    def self.previous_boundary
+      boundaries = manifests.map { |manifest| manifest['from'] }.uniq
+      boundaries.select { |version| compare(version, installed_minor_version) < 0 }.
+        max_by { |version| version_parts(version) }
+    end
+
+    # Whether an upgrade applies to this installation at all.
+    #
+    # False for a store installed fresh at its current version: it has no
+    # historical data to convert, so neither the outstanding steps nor the
+    # history of past releases describes anything real for it. True again
+    # once a later release ships steps it has not run.
+    #
+    # @return [Boolean]
+    def self.relevant?
+      !Spree::UpgradeRecord.exists? || Spree::UpgradeRecord.upgraded? || pending_steps.any?
+    end
+
+    # Whether a step can run here. An optional step belongs to a gem that may
+    # not be installed — a payment gateway, for instance — and is skipped
+    # where it is absent rather than offered as work that cannot start.
+    #
+    # @param step [Hash] a manifest step
+    # @return [Boolean]
+    def self.available?(step)
+      return true unless step['optional']
+      return Spree::MaintenanceTask.find_registered(step['task_class']).present? if step['task_class']
+
+      Spree::MaintenanceTask.new.rake_file_defining(step['task']).present?
+    end
+
+    # Steps this installation still has to run: every manifest above the
+    # boundary it has completed, up to and including the installed version.
+    #
+    # @return [Array<Hash>]
+    def self.pending_steps
+      boundary = completed_boundary
+
+      steps.select do |step|
+        next false if compare(step['to'], installed_minor_version) > 0
+        next false unless available?(step)
+        next true if boundary.nil?
+
+        compare(step['from'], boundary) >= 0
+      end
+    end
+
+    # Steps of manifests below the completed boundary — the ones a fresh or
+    # already-upgraded installation does not need. When the boundary was
+    # assumed rather than recorded the dashboard says so, and points a store
+    # that skipped a release at the command line, which still runs them.
+    #
+    # @return [Array<Hash>]
+    def self.superseded_steps
+      boundary = completed_boundary
+      return [] if boundary.nil?
+
+      steps.select { |step| compare(step['from'], boundary) < 0 }
+    end
+
+    def self.version_parts(version)
+      version.split('.').map { |segment| Integer(segment, 10) rescue 0 }
+    end
+
+    # Compare two dotted-version strings (returns -1, 0, +1).
+    def self.compare(first, second)
+      version_parts(first) <=> version_parts(second)
+    end
+  end
+end

data/lib/spree/upgrades/5_6_to_6_0/manifest.yml

@@ -12,8 +12,15 @@
 #     live in the upgrade doc at docs/developer/upgrades/5.6-to-6.0.mdx.
 #
 # This manifest is the machine-runnable shape — what `bin/rake spree:upgrade`
-# (in production) and `spree upgrade` (in dev) execute. Every step must be a
-# rake task and must be idempotent. Re-running the full manifest is safe.
+# (in production) and `spree upgrade` (in dev) execute. Every step must be
+# idempotent; re-running the full manifest is safe.
+#
+# Steps name a `task_class` — a Spree::MaintenanceTask that the walk runs
+# through the maintenance task runner, so a shell walk and a dashboard run
+# leave the same audit record and the same resume behaviour
+# (docs/plans/6.0-maintenance-tasks.md). Released manifests keep their `task`
+# rake names, which have shipped and may be scripted; the walker runs both
+# kinds.
 ---
 from: "5.6"
 to: "6.0"
@@ -151,7 +158,7 @@ steps:
 
   - id: migrate_users_to_customers
     name: "Move users onto the gem-owned Customer/AdminUser models"
-    task: "spree:upgrade:migrate_users_to_customers"
+    task_class: "Spree::MaintenanceTasks::Upgrade::UsersToCustomers"
     notes: |
       Copies the legacy Devise user table (default spree_users) into
       spree_customers, preserving ids so the renamed customer_id foreign keys
@@ -261,7 +268,7 @@ steps:
 
   - id: migrate_deliveries
     name: "Move tracking numbers onto deliveries"
-    task: "spree:migrate_deliveries"
+    task_class: "Spree::MaintenanceTasks::Upgrade::Deliveries"
     notes: |
       Every fulfillment carrying a 5.6 tracking number gets one delivery row
       with that number: the carrier axis (tracking number, carrier, carrier
@@ -322,7 +329,7 @@ steps:
 
   - id: migrate_promotion_option_value_rules
     name: "Rewrite Option Value promotion rules to stable option value ids"
-    task: "spree:upgrade:migrate_promotion_option_value_rules"
+    task_class: "Spree::MaintenanceTasks::Upgrade::PromotionOptionValueRules"
     notes: |
       Spree 6.0 stores Option Value promotion rules against Spree::OptionValue
       ids. Upgrades from 5.6 may still carry join-row ids from
@@ -365,7 +372,7 @@ steps:
 
   - id: migrate_returns
     name: "Move returns onto the new returns models"
-    task: "spree:upgrade:migrate_returns"
+    task_class: "Spree::MaintenanceTasks::Upgrade::Returns"
     notes: |
       Converts each ReturnAuthorization into a Spree::Return, or a
       Spree::Exchange when any of its return items named an exchange variant,
@@ -494,7 +501,7 @@ steps:
 
   - id: backfill_order_coupon_codes
     name: "Backfill coupon codes on placed orders"
-    task: "spree:backfill_order_coupon_codes"
+    task_class: "Spree::MaintenanceTasks::Upgrade::OrderCouponCodes"
     notes: |
       spree_orders gains a coupon_code column in Spree 6, matching carts.
       Historical placed orders applied coupons only through the promotion
@@ -510,7 +517,7 @@ steps:
 
   - id: backfill_order_markets
     name: "Backfill order markets"
-    task: "spree:backfill_order_markets"
+    task_class: "Spree::MaintenanceTasks::Upgrade::BackfillOrderMarkets"
     notes: |
       Market is mandatory in Spree 6. Assigns the store's default market to
       orders that predate markets. Channel needs no step here — the 5.4→5.5
@@ -573,7 +580,7 @@ steps:
 
   - id: migrate_capture_methods
     name: "Convert payment method auto_capture into capture_method"
-    task: "spree:migrate_capture_methods"
+    task_class: "Spree::MaintenanceTasks::Upgrade::CaptureMethods"
     notes: |
       Payment methods say when they charge with a capture_method string
       (checkout, on_dispatch or manual) rather than an auto_capture boolean,
@@ -625,7 +632,7 @@ steps:
 
   - id: migrate_stripe_webhook_keys
     name: "Move Stripe webhook signing secrets onto the gateway"
-    task: "spree:upgrade:migrate_stripe_webhook_keys"
+    task_class: "SpreeStripe::MaintenanceTasks::MigrateWebhookKeys"
     optional: true
     notes: |
       Only runs when spree_stripe is installed; skipped otherwise.

data/lib/tasks/maintenance_tasks.rake

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Command-line entry to the same runner the dashboard drives, so a shell run
+# is audited exactly like an operator's (docs/plans/6.0-maintenance-tasks.md).
+#
+#   bin/rake "spree:maintenance_tasks:perform[backfill_order_markets]"
+#   DRY_RUN=1 bin/rake "spree:maintenance_tasks:perform[capture_methods]"
+#   ARGS='batch_size=200' bin/rake "spree:maintenance_tasks:perform[deliveries]"
+namespace :spree do
+  namespace :maintenance_tasks do
+    desc 'Run a maintenance task synchronously'
+    task :perform, [:task_name] => :environment do |_task, args|
+      task_name = args[:task_name] || ENV['TASK']
+      abort '  Pass a task name: rake "spree:maintenance_tasks:perform[Your::Task]"' if task_name.blank?
+
+      # Either the class name or the short name the dashboard shows.
+      lookup = Spree::MaintenanceTask.find_registered(task_name) ? { task_name: task_name } : { api_type: task_name }
+
+      result = Spree::MaintenanceTasks::Start.call(
+        **lookup,
+        arguments: Spree::MaintenanceTasks::ArgumentParser.parse(ENV['ARGS']),
+        dry_run: ENV['DRY_RUN'] == '1',
+        initiated_via: 'cli',
+        inline: true
+      )
+
+      abort "  #{result.error}" if result.failure?
+
+      run = result.value.reload
+      puts "  #{run.task_name}: #{run.status} — #{run.tick_count} processed#{run.dry_run? ? ' (dry run)' : ''}"
+      (run.tallies || {}).each { |key, value| puts "    #{key}: #{value}" }
+
+      if run.errored?
+        puts "  #{run.error_class}: #{run.error_message}"
+        abort '  The run failed. Fix the cause, then re-run this task.'
+      end
+
+      # A refused duplicate or a cancellation did not do the work either.
+      abort "  The run did not finish (#{run.status})." unless run.succeeded?
+    end
+  end
+end

data/lib/tasks/upgrade.rake

@@ -33,41 +33,10 @@ namespace :spree do
   end
 end
 
+require 'spree/upgrade'
+
 module Spree
   module Upgrade
-    # Two-segment "5.5" form of the installed Spree version.
-    def self.installed_minor_version
-      Spree.version.split('.').first(2).join('.')
-    end
-
-    # Root directory containing N_M_to_O_P/manifest.yml files inside
-    # the spree_core gem.
-    def self.manifests_root
-      File.expand_path('../spree/upgrades', __dir__)
-    end
-
-    # All available manifest directories, parsed into { from:, to:, dir: }.
-    # Sorted by `to` ascending, with `from` as a tiebreaker (smallest first)
-    # for the rare case where two manifests share a `to` boundary.
-    def self.available_manifests
-      Dir.glob(File.join(manifests_root, '*_to_*')).filter_map do |dir|
-        name = File.basename(dir)
-        match = name.match(/\A([\d_]+)_to_([\d_]+)\z/)
-        next unless match
-
-        { from: match[1].tr('_', '.'), to: match[2].tr('_', '.'), dir: dir }
-      end.sort_by { |m| version_parts(m[:to]) + version_parts(m[:from]) }
-    end
-
-    def self.version_parts(v)
-      v.split('.').map { |s| Integer(s, 10) rescue 0 }
-    end
-
-    # Compare two dotted-version strings (returns -1, 0, +1).
-    def self.compare(a, b)
-      version_parts(a) <=> version_parts(b)
-    end
-
     # The runner is a class (not a method) so individual concerns (selection,
     # rendering, invocation) stay separable and the plan can be inspected
     # without execution.
@@ -100,13 +69,7 @@ module Spree
       # Plan mode selects exactly what a real run executes, so a dry run after
       # bumping the gem lists every backfill the upgrade is about to perform.
       def eligible_manifests
-        Spree::Upgrade.available_manifests
-          .select { |manifest| Spree::Upgrade.compare(manifest[:to], target_version) <= 0 }
-          .map { |entry| load_manifest_yaml(entry) }
-      end
-
-      def load_manifest_yaml(entry)
-        YAML.safe_load_file(File.join(entry[:dir], 'manifest.yml'))
+        Spree::Upgrade.manifests.select { |manifest| Spree::Upgrade.compare(manifest['to'], target_version) <= 0 }
       end
 
       def run_full_walk(manifests)
@@ -122,10 +85,22 @@ module Spree
           end
         end
 
+        stamp_completed_boundaries(manifests) unless dry_run
+
         puts
         puts dry_run ? '  (dry run — nothing executed)' : '  Upgrade tasks complete.'
       end
 
+      # Records the boundaries this walk finished, so a later dashboard visit
+      # shows only what is still outstanding rather than every step of every
+      # manifest ever written. A partial walk stamps nothing — `invoke` aborts
+      # on a failed step, so reaching here means every step succeeded.
+      def stamp_completed_boundaries(manifests)
+        manifests.each do |manifest|
+          Spree::UpgradeRecord.stamp!(manifest['to'], source: 'walk')
+        end
+      end
+
       # STEP=<id> looks across every eligible manifest; we need exactly one
       # match. Multiple matches are likely a manifest bug (two manifests
       # referencing the same step id) but we surface it rather than picking
@@ -162,38 +137,84 @@ module Spree
         puts
         puts "  Step #{index}/#{total} [#{step['id']}]"
         puts "    #{step['name']}"
-        puts "    > bin/rake #{step['task']}"
+        puts "    > #{step_command(step)}"
         return unless step['notes']
 
         step['notes'].each_line { |line| puts "    #{line.chomp}" }
       end
 
       def print_step_complete(step)
-        puts "    ✓ #{step['task']} done."
+        puts "    ✓ #{step_label(step)} done."
       end
 
+      def step_label(step)
+        step['task_class'] || step['task']
+      end
+
+      def step_command(step)
+        if step['task_class']
+          "bin/rake \"spree:maintenance_tasks:perform[#{step['task_class']}]\""
+        else
+          "bin/rake #{step['task']}"
+        end
+      end
+
+      # Both step kinds run through the maintenance task runner, so a shell
+      # walk records the same audit rows a dashboard run does: a class-backed
+      # step runs its own task, a rake-backed step runs inside UpgradeStep.
+      #
+      # Returns false when the step was skipped, so the caller can leave the
+      # "done" line off a step that never ran.
       def invoke(step)
-        task = step.fetch('task')
-
-        # Steps contributed by optional gems (payment gateways, for instance)
-        # are absent unless that gem is installed. Skipping keeps the upgrade
-        # runnable on installs that never had the gem, while an install that
-        # does have it still gets the backfill.
-        if step['optional'] && !Rake::Task.task_defined?(task)
-          puts "    Skipping #{task} — not installed."
-          return false
+        return false if skip_uninstalled?(step)
+
+        puts "    Running #{step_label(step)}..."
+
+        result = Spree::MaintenanceTasks::Start.call(
+          task_name: Spree::Upgrade.task_class_name(step),
+          arguments: step_arguments(step),
+          initiated_via: 'cli',
+          inline: true
+        )
+
+        abort "    #{result.error}" if result.failure?
+
+        run = result.value.reload
+        (run.tallies || {}).each { |key, value| puts "      #{key}: #{value}" }
+
+        if run.errored?
+          puts "    #{run.error_class}: #{run.error_message}"
+          abort '    Step failed. Fix the cause, then re-run this step.'
+        end
+
+        # Anything short of success — cancelled or still running — means
+        # the step's data is not converted, and the steps after it depend on it.
+        unless run.succeeded?
+          puts "    The step did not finish (#{run.status})."
+          abort '    Re-run this step once it can finish.'
         end
 
-        puts "    Running #{task}..."
+        true
+      end
+
+      # A rake-backed step is named by id; a class-backed step that reads
+      # environment variables gets the ones the operator exported, so
+      # `CONFIRM_NO_PEPPER=true bin/rake spree:upgrade` reaches it.
+      def step_arguments(step)
+        return Spree::Upgrade.task_arguments(step) unless step['task_class']
+
+        task_class = Spree::MaintenanceTask.find_registered(step['task_class'])
+        task_class.respond_to?(:arguments_from_environment) ? task_class.arguments_from_environment : {}
+      end
+
+      # Steps contributed by optional gems (payment gateways, for instance)
+      # are absent unless that gem is installed. Skipping keeps the upgrade
+      # runnable on installs that never had the gem, while an install that
+      # does have it still gets the backfill.
+      def skip_uninstalled?(step)
+        return false if Spree::Upgrade.available?(step)
 
-        # Rake caches invoked tasks in-process; explicit reenable lets a
-        # single `rake spree:upgrade` run re-invoke aggregators that share
-        # subtasks across multiple manifests (e.g. two manifests both
-        # depending on `spree:install:migrations` would otherwise only
-        # invoke it once).
-        rake_task = Rake::Task[task]
-        rake_task.reenable
-        rake_task.invoke
+        puts "    Skipping #{step_label(step)} — not installed."
         true
       end
     end