spree_core 5.1.8 → 5.2.0.rc2

data/lib/generators/spree/cursor_rules/templates/spree_rules.mdc

@@ -0,0 +1,387 @@
+---
+alwaysApply: true
+---
+
+# Cursor Rules for Spree Commerce Development
+
+## General Development Guidelines
+
+### Framework & Architecture
+
+- Spree is built on Ruby on Rails and follows MVC architecture
+- All Spree code must be namespaced under `Spree::` module
+- Spree is distributed as Rails engines with separate gems (core, admin, api, storefront, emails, etc.)
+- Follow Rails conventions and the Rails Security Guide
+- Prefer Rails idioms and standard patterns over custom solutions
+
+### Code Organization
+
+- Place all models in `app/models/spree/` directory
+- Place all controllers in `app/controllers/spree/` directory  
+- Place all views in `app/views/spree/` directory
+- Place all services in `app/services/spree/` directory
+- Place all mailers in `app/mailers/spree/` directory
+- Place all API serializers in `app/serializers/spree/` directory
+- Place all helpers in `app/helpers/spree/` directory
+- Place all jobs in `app/jobs/spree/` directory
+- Place all presenters in `app/presenters/spree/` directory
+- Use consistent file naming: `spree/product.rb` for `Spree::Product` class
+- Group related functionality into concerns when appropriate
+- Do not call `Spree::User` directly, use `Spree.user_class` instead
+- Do not call `Spree::AdminUser` directly, use `Spree.admin_user_class` instead
+
+## Naming Conventions & Structure
+
+### Classes & Modules
+
+```ruby
+# ✅ Correct naming
+module Spree
+  class Product < Spree.base_class
+  end
+end
+
+module Spree
+  module Admin
+    class ProductsController < ResourceController
+    end
+  end
+end
+
+# ❌ Incorrect - missing namespace
+class Product < ApplicationRecord
+end
+```
+
+Always inherit from `Spree.base_class` when creating models.
+
+### File Paths
+
+- Models: `app/models/spree/product.rb`
+- Controllers: `app/controllers/spree/admin/products_controller.rb`
+- Views: `app/views/spree/admin/products/`
+- Decorators: `app/models/spree/product_decorator.rb`
+
+## Model Development
+
+### Model Patterns
+
+- Use ActiveRecord associations appropriately, always pass `class_name` and `dependent` options
+- Implement concerns for shared functionality
+- Use scopes for reusable query patterns
+- Include `Spree::Metafields` concern for models that need metadata support
+
+```ruby
+# ✅ Good model structure
+class Spree::Product < Spree.base_class
+  include Spree::Metafields
+  
+  has_many :variants, class_name: 'Spree::Variant', dependent: :destroy
+  has_many :product_properties, class_name: 'Spree::ProductProperty', dependent: :destroy
+  has_many :properties, through: :product_properties, source: :property
+  
+  scope :available, -> { where(available_on: ..Time.current) }
+  
+  validates :name, presence: true
+  validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
+end
+```
+
+For uniqueness validation, always use `scope: spree_base_uniqueness_scope`
+
+## Controller Development
+
+### Controller Inheritance
+
+- Admin controllers inherit from `Spree::Admin::ResourceController` which handles most of CRUD operations
+- API controllers inherit from `Spree::Api::V2::BaseController`
+- Storefront controllers inherit from `Spree::StoreController`
+
+### Parameter Handling
+
+- Always use strong parameters
+
+```ruby
+# ✅ Proper parameter handling
+def permitted_product_params
+  params.require(:product).permit(:name, :description, :price)
+end
+```
+
+## Customization & Extensions
+
+### Spree::Dependencies System (Preferred Method)
+
+Dependencies allow you to replace parts of Spree core with custom implementations. This is the preferred method for customization.
+
+#### Global Customization
+
+In `config/initializers/spree.rb`:
+
+```ruby
+# Single service replacement
+Spree::Dependencies.cart_add_item_service = 'MyAddToCartService'
+
+# Or using block syntax
+Spree.dependencies do |dependencies|
+  dependencies.cart_add_item_service = 'MyAddToCartService'
+  dependencies.checkout_complete_service = 'MyCheckoutCompleteService'
+end
+```
+
+#### API Level Customization
+
+```ruby
+# Storefront API specific
+Spree::Api::Dependencies.storefront_cart_serializer = 'MyCartSerializer'
+Spree::Api::Dependencies.storefront_cart_add_item_service = 'MyAddToCartService'
+
+# Platform API specific
+Spree::Api::Dependencies.platform_product_serializer = 'MyProductSerializer'
+```
+
+#### Service Implementation
+
+```ruby
+# ✅ Proper service inheritance
+class MyAddToCartService < Spree::Cart::AddItem
+  def call(order:, variant:, quantity: nil, public_metadata: {}, private_metadata: {}, options: {})
+    ApplicationRecord.transaction do
+      run :add_to_line_item
+      run Spree::Dependencies.cart_recalculate_service.constantize
+      run :update_external_system
+    end
+  end
+
+  private
+
+  def update_external_system(result)
+    # Custom logic here
+  end
+end
+```
+
+#### Available Injection Points
+
+Common dependencies you can override:
+- Cart services: `cart_add_item_service`, `cart_update_service`, `cart_remove_item_service`
+- Checkout services: `checkout_next_service`, `checkout_complete_service`
+- Order services: `order_approve_service`, `order_cancel_service`
+- Payment services: `payment_create_service`, `payment_process_service`
+- Ability classes: `ability_class`
+- Serializers: Various API serializers for different endpoints
+
+### Decorators (Use Sparingly)
+
+Decorators should be a last resort - they make upgrades difficult. Use `Module.prepend` pattern for decorators.
+
+#### Model Decorators
+
+```ruby
+# ✅ Proper decorator structure
+module Spree
+  module ProductDecorator
+    def self.prepended(base)
+      base.has_many :videos, class_name: 'Spree::Video', dependent: :destroy
+      base.before_validation :strip_whitespaces
+    end
+
+    def custom_name
+      name.upcase
+    end
+
+    private
+
+    def strip_whitespaces
+      self.name = name.strip if name.present?
+    end
+  end
+
+  Product.prepend(ProductDecorator)
+end
+```
+
+#### Controller Decorators
+
+```ruby
+# ✅ Controller decorator with dependency injection
+module Spree
+  module Admin
+    module ProductsControllerDecorator
+      def self.prepended(base)
+        base.before_action :load_custom_data, only: [:show, :edit]
+      end
+
+      def custom_action
+        # Custom action implementation
+      end
+
+      private
+
+      def load_custom_data
+        @custom_data = fetch_custom_data
+      end
+    end
+
+    ProductsController.prepend(ProductsControllerDecorator)
+  end
+end
+```
+
+### View Customization
+
+#### Admin Panel Injection Points
+
+Use partial injection for admin customization:
+
+```ruby
+# In config/initializers/spree.rb
+Rails.application.config.spree_admin.head_partials << 'spree/admin/shared/custom_head'
+Rails.application.config.spree_admin.body_end_partials << 'spree/admin/shared/custom_footer'
+```
+
+Available injection points:
+- `head_partials` - Injects into `<head>` tag
+- `body_start_partials` - Injects at start of `<body>`
+- `body_end_partials` - Injects at end of `<body>`
+
+#### Storefront Themes
+
+Create custom themes for storefront customization:
+
+```bash
+bin/rails g spree:storefront:theme MyTheme
+```
+
+```ruby
+# Register theme in config/initializers/spree.rb
+Rails.application.config.spree.themes << Spree::Themes::MyTheme
+```
+
+#### View Overrides
+
+Override specific views by creating files in your app:
+
+```
+app/views/themes/my_theme/spree/products/index.html.erb
+```
+
+Do not override views for admin, only for storefront. Avoid overriding any views for Checkout or Cart.
+
+### Authentication Integration
+
+```ruby
+# In config/initializers/spree.rb
+Spree.user_class = 'User'
+Spree.admin_user_class = 'AdminUser'
+
+# Custom authentication
+Rails.application.config.to_prepare do
+  Spree::ApplicationController.include MyAuthenticationModule
+end
+```
+
+## Testing Guidelines
+
+### Test Structure
+
+- Use RSpec for testing
+- Place specs in `spec/` directory following Rails conventions
+- Use Spree's testing helpers and factories
+
+```ruby
+# ✅ Proper test structure
+require 'spec_helper'
+
+RSpec.describe Spree::Product, type: :model do
+  let(:product) { create(:product) }
+  
+  describe '#available?' do
+    it 'returns true when product is available' do
+      expect(product.available?).to be true
+    end
+  end
+end
+```
+
+### Factory Usage
+
+```ruby
+# Use Spree factories
+create(:product, name: 'Test Product')
+create(:order_with_line_items)
+create(:user)
+```
+
+## Performance & Security
+
+### Database Queries
+
+- Use includes/joins to avoid N+1 queries
+- Add database indexes for frequently queried fields
+- Use counter caches for associations that are counted frequently
+
+### Security
+
+- Always use strong parameters in controllers
+- Sanitize user input
+- Use Spree's built-in authorization system (CanCanCan)
+- Validate file uploads and restrict file types
+
+## Common Patterns
+
+### Service Objects
+
+```ruby
+# ✅ Spree service pattern
+module Spree
+  class MyCustomService
+    prepend Spree::ServiceModule::Base
+
+    def call(param1:, param2: nil)
+      # Service logic here
+      success(result_data)
+    rescue StandardError => e
+      failure(e.message)
+    end
+  end
+end
+```
+
+### API Development
+
+```ruby
+# ✅ Custom API endpoint
+module Spree
+  module Api
+    module V2
+      class CustomController < Spree::Api::V2::BaseController
+        def index
+          render json: serialized_collection
+        end
+
+        private
+
+        def serialized_collection
+          Spree::Api::Dependencies.storefront_product_serializer.constantize.new(
+            collection,
+            include: resource_includes,
+            fields: sparse_fields
+          ).serializable_hash
+        end
+      end
+    end
+  end
+end
+```
+
+## Avoid These Patterns
+
+❌ Direct inheritance from Rails classes without Spree namespace
+❌ Monkey patching without using decorators or dependencies
+❌ Hard-coding configuration values
+❌ Direct SQL queries without using ActiveRecord
+❌ Creating models outside Spree namespace when extending core functionality
+❌ Using class_eval decorators (use Module.prepend instead)
+❌ Overriding entire view files when partial injection would work
+❌ Modifying core Spree files directly

data/lib/generators/spree/dummy/dummy_generator.rb

@@ -38,7 +38,6 @@ module Spree
       opts[:skip_spring] = true
       opts[:skip_test] = true
       opts[:skip_bootsnap] = true
-      opts[:skip_asset_pipeline] = true # skip installing propshaft, we're still using sprockets as a dependency
       opts[:skip_docker] = true
       opts[:skip_rubocop] = true
       opts[:skip_brakeman] = true

data/lib/generators/spree/install/install_generator.rb

@@ -14,6 +14,7 @@ module Spree
     class_option :install_admin, type: :boolean, default: false, banner: 'installs default rails admin'
     class_option :auto_accept, type: :boolean
     class_option :user_class, type: :string
+    class_option :admin_user_class, type: :string
     class_option :admin_email, type: :string
     class_option :admin_password, type: :string
     class_option :lib_name, type: :string, default: 'spree'
@@ -69,6 +70,11 @@ module Spree
     def install_admin
       if @install_admin && Spree::Core::Engine.admin_available?
         generate 'spree:admin:install'
+
+        # generate devise controllers if authentication is devise
+        if @authentication == 'devise'
+          generate 'spree:admin:devise'
+        end
       end
     end
 
@@ -95,7 +101,6 @@ module Spree
       append_file 'db/seeds.rb', <<-SEEDS.strip_heredoc
 
         Spree::Core::Engine.load_seed if defined?(Spree::Core)
-        Spree::Auth::Engine.load_seed if defined?(Spree::Auth)
       SEEDS
     end
 
@@ -133,7 +138,7 @@ module Spree
           cmd.call
         end
       else
-        say_status :skipping, 'seed data (you can always run rake db:seed)'
+        say_status :skipping, 'seed data (you can always run bin/rails db:seed)'
       end
     end
 

data/lib/generators/spree/install/templates/config/initializers/spree.rb

@@ -29,6 +29,11 @@ end
 # Default is nil and your application host will be used
 # Spree.cdn_host = 'cdn.example.com'
 
+# Multi-store setup
+# You need to set a wildcard `root_domain` on the store to enable multi-store setup
+# all new stores will be created in a subdomain of the root domain, eg. store1.lvh.me, store2.lvh.me, etc.
+# Spree.root_domain = ENV.fetch('SPREE_ROOT_DOMAIN', 'lvh.me')
+
 # Use a different service for storage (S3, google, etc)
 # unless Rails.env.test?
 #   Spree.private_storage_service_name = :amazon_public # public assets, such as product images
@@ -86,5 +91,4 @@ Rails.application.config.after_initialize do
 end
 
 Spree.user_class = <%= (options[:user_class].blank? ? 'Spree::LegacyUser' : options[:user_class]).inspect %>
-# Use a different class for admin users
-# Spree.admin_user_class = 'AdminUser'
+Spree.admin_user_class = <%= (options[:admin_user_class].blank? ? (options[:user_class].blank? ? 'Spree::LegacyUser' : options[:user_class]) : options[:admin_user_class]).inspect %>

data/lib/spree/core/configuration.rb

@@ -50,6 +50,7 @@ module Spree
       preference :mailer_logo, :string, deprecated: true
       preference :max_level_in_taxons_menu, :integer, deprecated: true
       preference :non_expiring_credit_types, :array, default: []
+      preference :product_properties_enabled, :boolean, default: false # enable legacy product properties
       preference :products_per_page, :integer, default: 12
       preference :require_master_price, :boolean, default: false
       preference :restock_inventory, :boolean, default: true # Determines if a return item is restocked automatically once it has been received

data/lib/spree/core/dependencies.rb

@@ -41,6 +41,7 @@ module Spree
         # order
         order_approve_service: 'Spree::Orders::Approve',
         order_cancel_service: 'Spree::Orders::Cancel',
+        order_updater: 'Spree::OrderUpdater',
 
         # shipment
         shipment_change_state_service: 'Spree::Shipments::ChangeState',
@@ -56,6 +57,7 @@ module Spree
         collection_sorter: 'Spree::BaseSorter',
         order_sorter: 'Spree::BaseSorter',
         products_sorter: 'Spree::Products::Sort',
+        posts_sorter: 'Spree::Posts::Sort',
 
         # paginator
         collection_paginator: 'Spree::Shared::Paginate',
@@ -102,6 +104,7 @@ module Spree
         completed_order_finder: 'Spree::Orders::FindComplete',
         credit_card_finder: 'Spree::CreditCards::Find',
         products_finder: 'Spree::Products::Find',
+        posts_finder: 'Spree::Posts::Find',
         taxon_finder: 'Spree::Taxons::Find',
         line_item_by_variant_finder: 'Spree::LineItems::FindByVariant',
         variant_finder: 'Spree::Variants::Find'

data/lib/spree/core/engine.rb

@@ -15,6 +15,7 @@ module Spree
                                :line_item_comparison_hooks,
                                :data_feed_types,
                                :export_types,
+                               :import_types,
                                :taxon_rules,
                                :themes,
                                :theme_layout_sections,
@@ -23,6 +24,8 @@ module Spree
                                :page_blocks,
                                :reports,
                                :translatable_resources,
+                               :metafield_types,
+                               :metafield_enabled_resources,
                                :analytics_events,
                                :analytics_event_handlers,
                                :integrations)
@@ -150,7 +153,14 @@ module Spree
 
         Rails.application.config.spree.export_types = [
           Spree::Exports::Products,
-          Spree::Exports::Orders
+          Spree::Exports::Orders,
+          Spree::Exports::Customers,
+          Spree::Exports::GiftCards,
+          Spree::Exports::NewsletterSubscribers
+        ]
+
+        Rails.application.config.spree.import_types = [
+          Spree::Imports::Products,
         ]
 
         Rails.application.config.spree.taxon_rules = [
@@ -189,6 +199,7 @@ module Spree
         ]
 
         Rails.application.config.spree.page_sections = [
+          Spree::PageSections::Breadcrumbs,
           Spree::PageSections::FeaturedPosts,
           Spree::PageSections::TaxonGrid,
           Spree::PageSections::ImageWithText,
@@ -245,7 +256,51 @@ module Spree
           Spree::Property,
           Spree::Taxon,
           Spree::Taxonomy,
-          Spree::Store
+          Spree::Store,
+          Spree::Policy
+        ]
+
+        Rails.application.config.spree.metafield_types = [
+          Spree::Metafields::ShortText,
+          Spree::Metafields::LongText,
+          Spree::Metafields::RichText,
+          Spree::Metafields::Number,
+          Spree::Metafields::Boolean,
+          Spree::Metafields::Json
+        ]
+
+        Rails.application.config.spree.metafield_enabled_resources = [
+          Spree::Address,
+          Spree::Asset,
+          Spree::CreditCard,
+          Spree::CustomDomain,
+          Spree::CustomerReturn,
+          Spree::GiftCard,
+          Spree::Image,
+          Spree::LineItem,
+          Spree::NewsletterSubscriber,
+          Spree::OptionType,
+          Spree::OptionValue,
+          Spree::Order,
+          Spree::Payment,
+          Spree::PaymentMethod,
+          Spree::PaymentSource,
+          Spree::Post,
+          Spree::PostCategory,
+          Spree::Product,
+          Spree::Promotion,
+          Spree::Refund,
+          Spree::Shipment,
+          Spree::ShippingMethod,
+          Spree::StockItem,
+          Spree::StockTransfer,
+          Spree::Store,
+          Spree::StoreCredit,
+          Spree::TaxRate,
+          Spree::Taxon,
+          Spree::Taxonomy,
+          Spree::Variant,
+          Spree.user_class
         ]
 
         Rails.application.config.spree.analytics_events = {

data/lib/spree/core/version.rb

@@ -1,5 +1,5 @@
 module Spree
-  VERSION = '5.1.8'.freeze
+  VERSION = '5.2.0.rc2'.freeze
 
   def self.version
     VERSION

data/lib/spree/core.rb

@@ -6,10 +6,10 @@ require 'active_model/railtie'
 require 'active_record/railtie'
 require 'active_storage/engine'
 require 'action_text/engine'
+require 'action_cable/engine'
 
 require 'mail'
 require 'action_mailer/railtie'
-require 'sprockets/railtie'
 
 require 'active_merchant'
 require 'acts_as_list'
@@ -98,6 +98,8 @@ module Spree
     @@queues ||= OpenStruct.new(
       default: :default,
       exports: :default,
+      images: :default,
+      imports: :default,
       reports: :default,
       variants: :default,
       taxons: :default,

data/lib/spree/permitted_attributes.rb

@@ -15,12 +15,16 @@ module Spree
       :gift_card_attributes,
       :gift_card_batch_attributes,
       :image_attributes,
+      :import_attributes,
+      :import_mapping_attributes,
       :integration_attributes,
       :inventory_unit_attributes,
       :invitation_attributes,
       :line_item_attributes,
       :menu_attributes,
       :menu_item_attributes,
+      :metafield_attributes,
+      :metafield_definition_attributes,
       :option_type_attributes,
       :option_value_attributes,
       :page_attributes,
@@ -29,6 +33,7 @@ module Spree
       :page_section_attributes,
       :payment_attributes,
       :payment_method_attributes,
+      :policy_attributes,
       :post_attributes,
       :post_category_attributes,
       :product_attributes,
@@ -83,7 +88,7 @@ module Spree
 
     @@checkout_attributes = [
       :coupon_code, :email, :shipping_method_id, :special_instructions, :use_billing, :use_shipping,
-      :user_id, :bill_address_id, :ship_address_id, :accept_marketing, :signup_for_an_account
+      :user_id, :bill_address_id, :ship_address_id, :accept_marketing, :signup_for_an_account, :currency
     ]
 
     @@classification_attributes = [
@@ -107,12 +112,16 @@ module Spree
 
     @@export_attributes = [:type, :format, :record_selection, :search_params]
 
-    @@gift_card_attributes = [:code, :amount, :expires_at, :user_id]
+    @@gift_card_attributes = [:code, :amount, :expires_at, :user_id, :currency]
 
-    @@gift_card_batch_attributes = [:prefix, :codes_count, :amount, :expires_at]
+    @@gift_card_batch_attributes = [:prefix, :codes_count, :amount, :expires_at, :currency]
 
     @@image_attributes = [:alt, :attachment, :position, :viewable_type, :viewable_id]
 
+    @@import_attributes = [:type, :attachment, :delimiter]
+
+    @@import_mapping_attributes = [:file_column]
+
     @@integration_attributes = [:type, :active]
 
     @@inventory_unit_attributes = [:shipment, :shipment_id, :variant_id]
@@ -126,6 +135,10 @@ module Spree
     @@menu_item_attributes = [:name, :subtitle, :destination, :new_window, :item_type,
                               :linked_resource_type, :linked_resource_id, :code, :menu_id]
 
+    @@metafield_attributes = [:id, :value, :type, :metafield_definition_id, :_destroy]
+
+    @@metafield_definition_attributes = [:key, :name, :namespace, :metafield_type, :resource_type, :display_on]
+
     @@option_type_attributes = [:name, :presentation, :position, :filterable,
                                 option_values_attributes: [:id, :name, :presentation, :position, :_destroy]]
 
@@ -143,6 +156,8 @@ module Spree
 
     @@payment_method_attributes = [:name, :type, :description, :active, :display_on, :auto_capture, :position]
 
+    @@policy_attributes = [:name, :slug, :body]
+
     @@post_attributes = [:title, :meta_title, :meta_description, :slug, :author_id, :post_category_id, :published_at, :content, :excerpt, :image, tag_list: []]
 
     @@post_category_attributes = [:title, :slug, :description]