Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Consolidate agent rules into CLAUDE.md (#13539)

Damian Legawiec787763227bc5
diff --git a/.cursor/rules/spree.mdc b/.cursor/rules/spree.mdc
deleted file mode 100644
index c022d8f34a..0000000000
--- a/.cursor/rules/spree.mdc
+++ /dev/null
@@ -1,159 +0,0 @@
----
-alwaysApply: true
----
-
-# General Spree Commerce Rules
-
-## 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
-
-## Core Naming Conventions
-- Do NOT call `Spree::User` directly, use `Spree.user_class` instead
-- Do NOT call `Spree::AdminUser` directly, use `Spree.admin_user_class` instead
-- Always inherit from `Spree.base_class` when creating models
-- Use consistent file naming: `spree/product.rb` for `Spree::Product` class
-
-## Model Standards
-- Use ActiveRecord associations with `class_name` and `dependent` options
-- For uniqueness validation, always use `scope: spree_base_uniqueness_scope`
-- Include `Spree::Metafields` concern for models that need metadata support
-- Use scopes for reusable query patterns
-
-```ruby
-# ✅ Correct model structure
-class Spree::Product < Spree.base_class
- include Spree::Metafields
-
- has_many :variants, class_name: 'Spree::Variant', dependent: :destroy
-
- scope :available, -> { where(available_on: ..Time.current) }
-
- validates :name, presence: true
- validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
-end
-```
-
-## Database & Migration Standards
-- Follow Rails migration conventions
-- Use proper indexing for performance
-- Do NOT include foreign key constraints
-- Always add `null: false` to required columns
-- Add unique indexes to columns used for uniqueness validation
-- Add `deleted_at` column to tables with soft delete functionality (paranoia gem)
-
-## Security Standards
-- Follow Rails Security Guide principles
-- Use strong parameters consistently
-- Always use `Spree::PermittedAttributes` to define allowed parameters
-- Never permit mass assignment without validation
-- Use allowlists, not blocklists for parameters
-
-## Performance Guidelines
-- Use includes/preload to avoid N+1 queries
-- Implement proper database indexing
-- Use scopes for reusable query logic
-- Consider caching for expensive operations
-
-## Error Handling
-- Use Rails error reporter
-- Use appropriate exception classes
-- Provide meaningful error messages
-- Implement proper error recovery where possible
-
-## Internationalization
-- Use `Spree.t` for translations instead of `I18n.t`
-- Do NOT repeat translations in multiple files
-- Try to use existing translations as much as possible
-
-## Testing Standards
-- Use RSpec for testing
-- Use `create` for persisted objects in tests
-- Use `build` for non-persisted objects (faster)
-- Add new factories in `lib/spree/testing_support/factories/`
-
-## Documentation
-- Document complex business logic
-- Use YARD documentation format for public APIs
-- Keep comments up-to-date with code changes
-# General Spree Commerce Rules
-
-## 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
-
-## Core Naming Conventions
-- Do NOT call `Spree::User` directly, use `Spree.user_class` instead
-- Do NOT call `Spree::AdminUser` directly, use `Spree.admin_user_class` instead
-- Always inherit from `Spree.base_class` when creating models
-- Use consistent file naming: `spree/product.rb` for `Spree::Product` class
-
-## Model Standards
-- Use ActiveRecord associations with `class_name` and `dependent` options
-- For uniqueness validation, always use `scope: spree_base_uniqueness_scope`
-- Include `Spree::Metafields` concern for models that need metadata support
-- Use scopes for reusable query patterns
-
-```ruby
-# ✅ Correct 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
-
- scope :available, -> { where(available_on: ..Time.current) }
-
- validates :name, presence: true
- validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
-end
-```
-
-## Database & Migration Standards
-- Follow Rails migration conventions
-- Use proper indexing for performance
-- Do NOT include foreign key constraints
-- Always add `null: false` to required columns
-- Add unique indexes to columns used for uniqueness validation
-- Add `deleted_at` column to tables with soft delete functionality (paranoia gem)
-
-## Security Standards
-- Follow Rails Security Guide principles
-- Use strong parameters consistently
-- Always use `Spree::PermittedAttributes` to define allowed parameters
-- Never permit mass assignment without validation
-- Use allowlists, not blocklists for parameters
-
-## Performance Guidelines
-- Use includes/preload to avoid N+1 queries
-- Implement proper database indexing
-- Use scopes for reusable query logic
-- Consider caching for expensive operations
-
-## Error Handling
-- Use Rails error reporter
-- Use appropriate exception classes
-- Provide meaningful error messages
-- Implement proper error recovery where possible
-
-## Internationalization
-- Use `Spree.t` for translations instead of `I18n.t`
-- Do NOT repeat translations in multiple files
-- Try to use existing translations as much as possible
-
-## Testing Standards
-- Use RSpec for testing
-- Use `create` for persisted objects in tests
-- Use `build` for non-persisted objects (faster)
-- Add new factories in `lib/spree/testing_support/factories/`
-
-## Documentation
-- Document complex business logic
-- Use YARD documentation format for public APIs
-- Keep comments up-to-date with code changes
diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 0000000000..681311eb9c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
\ No newline at end of file
diff --git a/admin/.cursor/rules/admin.mdc b/admin/.cursor/rules/admin.mdc
deleted file mode 100644
index 10f33d2eea..0000000000
--- a/admin/.cursor/rules/admin.mdc
+++ /dev/null
@@ -1,228 +0,0 @@
----
-alwaysApply: true
----
-
-# Spree Admin Interface Rules
-
-## Controller Standards
-- Admin controllers inherit from `Spree::Admin::ResourceController`
-- ResourceController handles most CRUD operations automatically
-- Use `stub_authorization!` for controller spec authentication
-- Always add `render_views` to controller specs
-
-```ruby
-# ✅ Proper admin controller
-class Spree::Admin::ProductsController < Spree::Admin::ResourceController
- private
-
- def permitted_resource_params
- params.require(:product).permit(Spree::PermittedAttributes.product_attributes)
- end
-end
-```
-
-## Form Builder Standards
-- Use `Spree::Admin::FormBuilder` methods for all form fields
-- Always use the provided form field methods for consistency
-
-### Available Form Field Methods
-- `f.spree_text_field :name`
-- `f.spree_number_field :price`
-- `f.spree_email_field :email`
-- `f.spree_date_field :available_on`
-- `f.spree_datetime_field :discontinue_on`
-- `f.spree_text_area :description`
-- `f.spree_rich_text_area :description` (with Trix editor)
-- `f.spree_select :category_id, options`
-- `f.spree_collection_select :category_id, collection, :id, :name`
-- `f.spree_check_box :active`
-- `f.spree_radio_button :status, 'active'`
-
-### Form Structure Standards
-For new resource forms:
-```erb
-<%= render 'spree/admin/shared/new_resource' %>
-```
-
-For edit resource forms:
-```erb
-<%= render 'spree/admin/shared/edit_resource' %>
-```
-
-### Reusable Form Partial Pattern
-Create `_form.html.erb` with proper card structure:
-```erb
-<div class="card mb-6">
- <div class="card-header">
- <h5 class="card-title">
- <%= Spree.t(:general_settings) %>
- </h5>
- </div>
-
- <div class="card-body">
- <%= f.spree_text_field :name %>
- <%= f.spree_rich_text_area :description %>
- <%= f.spree_check_box :active %>
- </div>
-</div>
-```
-
-## View Standards
-- Use Turbo Rails features (Hotwire) as much as possible
-- Use Stimulus controllers for JavaScript interactions
-- Follow Bootstrap 4 styling conventions
-- Use `Spree.t` for all translations
-
-## JavaScript & Stimulus
-- Place Stimulus controllers in `app/javascript/controllers/spree/admin/`
-- Use data attributes for controller binding
-- Follow Stimulus naming conventions
-
-## Asset Organization
-- Stylesheets: `app/assets/stylesheets/spree/admin/`
-- JavaScript: `app/javascript/`
-- Images: `app/assets/images/spree/admin/`
-
-## Security
-- Admin controllers are automatically secured when inheriting from ResourceController
-- Use CanCanCan for authorization
-- Authentication handled by app developers (Devise installer provided)
-
-## Translation Files
-- Place admin translations in `admin/config/locales/en.yml`
-- Use namespace structure: `spree.admin.product.name`
-- Reuse existing translations when possible
-
-## Testing Standards
-- Place admin specs in `spec/controllers/spree/admin/`
-- Always use `render_views` in controller specs
-- Use `stub_authorization!` for authentication in specs
-
-```ruby
-# ✅ Proper admin controller spec
-require 'spec_helper'
-
-RSpec.describe Spree::Admin::ProductsController, type: :controller do
- stub_authorization!
- render_views
-
- describe '#index' do
- it 'renders the index template' do
- get :index
- expect(response).to render_template(:index)
- end
- end
-end
-```
-# Spree Admin Interface Rules
-
-## Controller Standards
-- Admin controllers inherit from `Spree::Admin::ResourceController`
-- ResourceController handles most CRUD operations automatically
-- Use `stub_authorization!` for controller spec authentication
-- Always add `render_views` to controller specs
-
-```ruby
-# ✅ Proper admin controller
-class Spree::Admin::ProductsController < Spree::Admin::ResourceController
- private
-
- def permitted_resource_params
- params.require(:product).permit(Spree::PermittedAttributes.product_attributes)
- end
-end
-```
-
-## Form Builder Standards
-- Use `Spree::Admin::FormBuilder` methods for all form fields
-- Always use the provided form field methods for consistency
-
-### Available Form Field Methods
-- `f.spree_text_field :name`
-- `f.spree_number_field :price`
-- `f.spree_email_field :email`
-- `f.spree_date_field :available_on`
-- `f.spree_datetime_field :discontinue_on`
-- `f.spree_text_area :description`
-- `f.spree_rich_text_area :description` (with Trix editor)
-- `f.spree_select :category_id, options`
-- `f.spree_collection_select :category_id, collection, :id, :name`
-- `f.spree_check_box :active`
-- `f.spree_radio_button :status, 'active'`
-
-### Form Structure Standards
-For new resource forms:
-```erb
-<%= render 'spree/admin/shared/new_resource' %>
-```
-
-For edit resource forms:
-```erb
-<%= render 'spree/admin/shared/edit_resource' %>
-```
-
-### Reusable Form Partial Pattern
-Create `_form.html.erb` with proper card structure:
-```erb
-<div class="card mb-6">
- <div class="card-header">
- <h5 class="card-title">
- <%= Spree.t(:general_settings) %>
- </h5>
- </div>
-
- <div class="card-body">
- <%= f.spree_text_field :name %>
- <%= f.spree_rich_text_area :description %>
- <%= f.spree_check_box :active %>
- </div>
-</div>
-```
-
-## View Standards
-- Use Turbo Rails features (Hotwire) as much as possible
-- Use Stimulus controllers for JavaScript interactions
-- Follow Bootstrap 4 styling conventions
-- Use `Spree.t` for all translations
-
-## JavaScript & Stimulus
-- Place Stimulus controllers in `app/javascript/controllers/spree/admin/`
-- Use data attributes for controller binding
-- Follow Stimulus naming conventions
-
-## Asset Organization
-- Stylesheets: `app/assets/stylesheets/spree/admin/`
-- JavaScript: `app/javascript/`
-- Images: `app/assets/images/spree/admin/`
-
-## Security
-- Admin controllers are automatically secured when inheriting from ResourceController
-- Use CanCanCan for authorization
-- Authentication handled by app developers (Devise installer provided)
-
-## Translation Files
-- Place admin translations in `admin/config/locales/en.yml`
-- Use namespace structure: `spree.admin.product.name`
-- Reuse existing translations when possible
-
-## Testing Standards
-- Place admin specs in `spec/controllers/spree/admin/`
-- Always use `render_views` in controller specs
-- Use `stub_authorization!` for authentication in specs
-
-```ruby
-# ✅ Proper admin controller spec
-require 'spec_helper'
-
-RSpec.describe Spree::Admin::ProductsController, type: :controller do
- stub_authorization!
- render_views
-
- describe '#index' do
- it 'renders the index template' do
- get :index
- expect(response).to render_template(:index)
- end
- end
-end
-```
diff --git a/api/.cursor/rules/api.mdc b/api/.cursor/rules/api.mdc
deleted file mode 100644
index ac8cf48c4f..0000000000
--- a/api/.cursor/rules/api.mdc
+++ /dev/null
@@ -1,168 +0,0 @@
----
-alwaysApply: true
----
-
-# Spree API Rules
-
-## Controller Standards
-- API controllers inherit from `Spree::Api::V2::BaseController`
-- Follow RESTful conventions
-- Use proper HTTP status codes
-- Implement proper error handling
-
-```ruby
-# ✅ Proper API controller
-class Spree::Api::V2::Storefront::ProductsController < Spree::Api::V2::BaseController
- def index
- render json: serialized_collection
- end
-
- def show
- render json: serialized_resource
- end
-
- private
-
- def serialized_collection
- collection_serializer.new(
- collection,
- include: resource_includes,
- sparse_fields: sparse_fields
- ).serializable_hash
- end
-
- def serialized_resource
- resource_serializer.new(
- resource,
- include: resource_includes,
- sparse_fields: sparse_fields
- ).serializable_hash
- end
-end
-```
-
-## Serializer Standards
-- Use JsonApiSerializer for all API responses
-- Place serializers in `app/serializers/spree/`
-- Follow JSON:API specification
-
-```ruby
-# ✅ Proper serializer structure
-class Spree::V2::Storefront::ProductSerializer < Spree::Api::V2::BaseSerializer
- set_type :product
-
- attributes :name, :description, :slug, :available_on
-
- has_many :variants, serializer: :variant
- has_many :images, serializer: :image
-
- attribute :display_price do |product|
- product.price_in(current_currency)
- end
-end
-```
-
-## Authentication & Authorization
-- Use token-based authentication
-- Implement proper scoping for resources
-- Use CanCanCan for authorization checks
-
-## Error Handling
-- Return proper HTTP status codes
-- Use consistent error response format
-- Handle validation errors appropriately
-
-```ruby
-# ✅ Proper error handling
-rescue_from ActiveRecord::RecordInvalid do |exception|
- render json: { error: exception.record.errors.full_messages }, status: :unprocessable_entity
-end
-
-rescue_from ActiveRecord::RecordNotFound do
- render json: { error: 'Resource not found' }, status: :not_found
-end
-```
-
-## Parameter Handling
-- Use strong parameters
-- Validate required parameters
-- Handle filtering and sorting parameters
-
-```ruby
-# ✅ Proper parameter handling
-def permitted_params
- params.require(:product).permit(Spree::PermittedAttributes.product_attributes)
-end
-
-def filter_params
- params.permit(:name, :category_id, :available_on)
-end
-```
-
-## Pagination
-- Use Kaminari for pagination
-- Return pagination metadata
-- Support page size limits
-
-## Filtering & Sorting
-- Implement ransack for complex filtering
-- Support sorting by multiple fields
-- Validate sort parameters
-
-## Include Relationships
-- Support sparse fieldsets
-- Allow including related resources
-- Optimize N+1 queries with includes
-
-## Versioning
-- Use namespace versioning (V2, V3, etc.)
-- Maintain backward compatibility
-- Document API changes
-
-## Testing Standards
-- Test all endpoints thoroughly
-- Use request specs for integration testing
-- Test authentication and authorization
-- Test error scenarios
-
-```ruby
-# ✅ Proper API spec
-require 'spec_helper'
-
-RSpec.describe '/api/v2/storefront/products', type: :request do
- describe 'GET /api/v2/storefront/products' do
- let!(:products) { create_list(:product, 3) }
-
- it 'returns products' do
- get '/api/v2/storefront/products'
-
- expect(response).to have_http_status(:ok)
- expect(json_response['data']).to be_an(Array)
- expect(json_response['data'].size).to eq(3)
- end
- end
-end
-```
-
-## JSON:API Compliance
-- Follow JSON:API specification
-- Use proper resource relationships
-- Include meta information
-- Support compound documents
-
-## Security
-- Validate all inputs
-- Implement rate limiting
-- Use HTTPS in production
-- Sanitize output data
-
-## Documentation
-- Document all endpoints
-- Include request/response examples
-- Document authentication requirements
-- Use OpenAPI/Swagger for API docs
-
-## Translation Files
-- Place API translations in `api/config/locales/en.yml`
-- Use namespace structure for error messages
-- Provide translations for validation errors
diff --git a/core/.cursor/rules/core.mdc b/core/.cursor/rules/core.mdc
deleted file mode 100644
index 1d25c23cd4..0000000000
--- a/core/.cursor/rules/core.mdc
+++ /dev/null
@@ -1,255 +0,0 @@
----
-alwaysApply: true
----
-
-# Spree Core Rules
-
-## Model Standards
-- All core models inherit from `Spree.base_class`
-- Use ActiveRecord associations with proper options (always add class_name, dependent, inverse_of)
-- Include appropriate concerns for shared functionality
-- Implement proper validations and scopes
-
-```ruby
-# ✅ Core model structure
-class Spree::Product < Spree.base_class
- include Spree::Metafields
-
- has_many :variants, -> { order(:position) }, class_name: 'Spree::Variant',
- dependent: :destroy, inverse_of: :product
- has_many :product_properties, class_name: 'Spree::ProductProperty',
- dependent: :destroy, inverse_of: :product
- has_many :properties, through: :product_properties
-
- validates :name, presence: true
- validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
-
- scope :available, -> { where(available_on: ..Time.current) }
- scope :active, -> { where(deleted_at: nil) }
-end
-```
-
-## Service Objects
-- Place service objects in `app/services/spree/`
-- Follow single responsibility principle
-- Return result objects or raise exceptions
-- Include proper error handling
-- All service objects need to add `prepend ::Spree::ServiceModule::Base`
-- All service objects need to define call method
-- All services need to ruturn `success` or `failure`
-
-```ruby
-# ✅ Service object structure
-module Spree
- class OrderService
- prepend ::Spree::ServiceModule::Base
-
- def call(order:)
- return failure('Order already completed') if order.completed?
-
- Spree::Order.with_lock do
- order.finalize!
- order.update!(completed_at: Time.current)
- send_confirmation_email
- end
-
- success(order.reload)
- rescue StandardError => e
- Rails.error.report e
- failure(e.message)
- end
- end
-end
-```
-
-## Finder Objects
-- Place finder objects in `app/finders/spree/`
-- Handle complex query logic
-- Return ActiveRecord relations
-- Support chaining
-
-```ruby
-# ✅ Finder object structure
-module Spree
- class ProductsFinder
- def initialize(params = {})
- @params = params
- end
-
- def execute
- products = Spree::Product.includes(:variants, :images)
- products = filter_by_category(products)
- products = filter_by_price_range(products)
- products = sort_products(products)
- products
- end
-
- private
-
- attr_reader :params
-
- def filter_by_category(products)
- return products unless params[:category_id].present?
-
- products.joins(:classifications)
- .where(spree_classifications: { taxon_id: params[:category_id] })
- end
- end
-end
-```
-
-## Migration Standards
-- Use descriptive migration names with timestamps
-- Add proper indexes for performance
-- Include `null: false` for required columns
-- Add `deleted_at` for soft deletable models
-- Don't add foreign keys
-
-```ruby
-# ✅ Proper migration structure
-class CreateSpreeMetafields < ActiveRecord::Migration[8.0]
- def change
- create_table :spree_metafields do |t|
- t.string :key, null: false
- t.text :value, null: false
- t.string :kind, null: false, default: 'single_line_text_field'
- t.string :visibility, null: false, default: 'private'
- t.references :resource, polymorphic: true, null: false, index: false
- t.timestamps
- t.datetime :deleted_at, index: true
- end
-
- add_index :spree_metafields, [:resource_type, :resource_id, :key, :visibility],
- name: 'index_spree_metafields_on_resource_and_key_and_visibility'
- add_index :spree_metafields, :key
- end
-end
-```
-
-## Job Standards
-- Place jobs in `app/jobs/spree/`
-- Inherit from `Spree::BaseJob`
-- Use proper queue names
-- Handle failures gracefully
-- Each job needs to define a queue in `Spree.queues` (in `core/lib/spree/core.rb`
-
-```ruby
-# ✅ Job structure
-module Spree
- class OrderEmailJob < BaseJob
- queue_as Spree.queues.orders
-
- def perform(order_id)
- order = Spree::Order.find(order_id)
- Spree::OrderMailer.confirm_email(order).deliver_now
- rescue ActiveRecord::RecordNotFound => e
- Rails.error.report e
- # Order was deleted, no need to retry
- end
- end
-end
-```
-
-## Mailer Standards
-- Place mailers in `app/mailers/spree/`
-- Use proper email templates
-- Include both HTML and text versions
-- Handle missing records gracefully
-- All mailers need to inherit from `Spree::BaseMailer`
-
-```ruby
-# ✅ Mailer structure
-module Spree
- class OrderMailer < Spree::BaseMailer
- def confirm_email(order)
- @order = order
- @store = order.store
-
- mail(
- to: order.email,
- subject: Spree.t('order_mailer.confirm_email.subject', order: order.number)
- )
- end
- end
-end
-```
-
-## Concern Standards
-- Place concerns in appropriate model directories
-- Use proper module structure
-- Include class methods when needed
-- Document concern purpose
-
-```ruby
-# ✅ Concern structure
-module Spree
- module Metadata
- extend ActiveSupport::Concern
-
- included do
- has_many :metafields, as: :owner, class_name: 'Spree::Metafield', dependent: :destroy
- end
-
- def metafield(key)
- metafields.find_by(key: key)
- end
-
- def set_metafield(key, value, type: 'string')
- metafield = metafields.find_or_initialize_by(key: key)
- metafield.assign_attributes(value: value, value_type: type)
- metafield.save!
- metafield
- end
- end
-end
-```
-
-## Validator Standards
-- Place validators in `app/validators/spree/`
-- Follow ActiveModel::Validator patterns
-- Provide clear error messages
-
-## Presenter Standards
-- Place presenters in `app/presenters/spree/`
-- Handle view logic and formatting
-- Keep business logic in models/services
-
-## Testing Core Components
-- Test all public methods
-- Test edge cases and error conditions
-- Use proper factory definitions
-- Mock external dependencies
-- Don't test standard associations or validations
-- Always test custom validations
-
-```ruby
-# ✅ Core model spec
-require 'spec_helper'
-
-RSpec.describe Spree::Product, type: :model do
- let(:product) { create(:product) }
-
- describe 'Scopes' do
- describe '.available' do
- let!(:available_product) { create(:product, available_on: 1.day.ago) }
- let!(:future_product) { create(:product, available_on: 1.day.from_now) }
-
- it 'returns only available products' do
- expect(described_class.available).to include(available_product)
- expect(described_class.available).not_to include(future_product)
- end
- end
- end
-
- describe '#my_custom_method' do
- it 'returns the correct value' do
- expect(product.my_custom_method).to eq('expected_value')
- end
- end
-end
-```
-
-## Helper Standards
-- Place helpers in `app/helpers/spree/`
-- Keep helpers simple and focused
-- Use helpers for view-specific logic only
diff --git a/emails/.cursor/rules/emails.mdc b/emails/.cursor/rules/emails.mdc
deleted file mode 100644
index 429a1b4e17..0000000000
--- a/emails/.cursor/rules/emails.mdc
+++ /dev/null
@@ -1,129 +0,0 @@
----
-alwaysApply: true
----
-
-# Spree Emails Rules
-
-## Mailer Standards
-- Inherit from `Spree::BaseMailer`
-- Use proper email templates
-- Include both HTML and text versions
-- Handle missing records gracefully
-
-```ruby
-# ✅ Email mailer structure
-module Spree
- class OrderMailer < BaseMailer
- def confirm_email(order)
- @order = order
- @store = order.store
-
- mail(
- to: order.email,
- from: from_address(@store),
- subject: Spree.t('order_mailer.confirm_email.subject', order: order.number)
- )
- end
-
- def cancel_email(order)
- @order = order
- @store = order.store
-
- mail(
- to: order.email,
- from: from_address(@store),
- subject: Spree.t('order_mailer.cancel_email.subject', order: order.number)
- )
- end
-
- private
-
- def from_address(store)
- store.mail_from_address.presence || Spree::Store.default.mail_from_address
- end
- end
-end
-```
-
-## Template Standards
-- Use consistent email layout
-- Include store branding
-- Ensure mobile responsiveness
-- Test across email clients
-
-```erb
-<!-- ✅ Email template structure -->
-<%= content_for :email_title, Spree.t('order_mailer.confirm_email.subject', order: @order.number) %>
-
-<div class="email-container">
- <header class="email-header">
- <%= image_tag @store.logo.attached? ? @store.logo : 'spree/logo.png',
- alt: @store.name,
- class: 'store-logo' %>
- <h1><%= Spree.t('order_mailer.confirm_email.dear_customer') %></h1>
- </header>
-
- <main class="email-content">
- <p><%= Spree.t('order_mailer.confirm_email.order_summary_intro', order: @order.number) %></p>
-
- <%= render 'spree/order_mailer/order_details', order: @order %>
- </main>
-
- <footer class="email-footer">
- <%= render 'spree/shared/email_footer', store: @store %>
- </footer>
-</div>
-```
-
-## Styling Standards
-- Use inline CSS for email compatibility
-- Include fallbacks for email clients
-- Keep layouts simple and clean
-- Test with email preview tools
-
-## Asset Management
-- Optimize images for email
-- Use absolute URLs for assets
-- Include alt text for images
-- Consider dark mode support
-
-## Testing Standards
-- Test email delivery
-- Preview emails in development
-- Test across multiple email clients
-- Verify links and formatting
-
-```ruby
-# ✅ Email spec
-require 'spec_helper'
-
-RSpec.describe Spree::OrderMailer, type: :mailer do
- let(:order) { create(:completed_order_with_totals) }
- let(:mail) { described_class.confirm_email(order) }
-
- describe '#confirm_email' do
- it 'renders the headers' do
- expect(mail.subject).to include(order.number)
- expect(mail.to).to eq([order.email])
- expect(mail.from).to eq([order.store.mail_from_address])
- end
-
- it 'renders the body' do
- expect(mail.body.encoded).to include(order.number)
- expect(mail.body.encoded).to include(order.user.email)
- end
- end
-end
-```
-
-## Internationalization
-- Support multiple languages
-- Use proper locale selection
-- Include currency formatting
-- Handle right-to-left languages
-
-## Performance
-- Optimize email size
-- Use efficient image formats
-- Minimize external requests
-- Consider email caching
diff --git a/sample/.cursor/rules/sample.mdc b/sample/.cursor/rules/sample.mdc
deleted file mode 100644
index 5b82c46a13..0000000000
--- a/sample/.cursor/rules/sample.mdc
+++ /dev/null
@@ -1,87 +0,0 @@
----
-alwaysApply: true
----
-
-# Spree Sample Data Rules
-
-## Sample Data Standards
-- Provide realistic sample data
-- Include diverse product types
-- Create complete data relationships
-- Use proper image assets
-
-```ruby
-# ✅ Sample data creation
-Spree::Sample.create_sample_data do
- # Create taxonomies first
- clothing = Spree::Taxonomy.create!(name: 'Clothing')
- brands = Spree::Taxonomy.create!(name: 'Brands')
-
- # Create taxons
- shirts = clothing.root.children.create!(name: 'Shirts')
- pants = clothing.root.children.create!(name: 'Pants')
-
- # Create products with proper associations
- product = Spree::Product.create!(
- name: 'Sample T-Shirt',
- description: 'A comfortable cotton t-shirt',
- available_on: Time.current,
- meta_keywords: 'shirt, cotton, comfortable',
- shipping_category: shipping_category
- )
-
- # Create variants
- product.variants.create!(
- sku: 'SHIRT-SM-BLU',
- price: 19.99,
- cost_price: 8.00,
- weight: 0.5
- )
-end
-```
-
-## Data Consistency
-- Ensure referential integrity
-- Use consistent naming conventions
-- Include proper categorization
-- Maintain realistic pricing
-
-## Image Assets
-- Use high-quality product images
-- Include multiple views per product
-- Optimize image sizes
-- Use consistent aspect ratios
-
-## Testing Data
-- Create data for different scenarios
-- Include edge cases
-- Support multiple currencies
-- Test with various configurations
-
-```ruby
-# ✅ Sample factory usage
-FactoryBot.define do
- factory :sample_product, parent: :product do
- name { 'Sample Product' }
- description { 'This is a sample product for testing' }
- available_on { 1.week.ago }
-
- after(:create) do |product|
- create(:variant, product: product, price: 10.00)
- create(:image, viewable: product)
- end
- end
-end
-```
-
-## Seed Data Organization
-- Organize by logical groups
-- Use proper execution order
-- Handle dependencies correctly
-- Include cleanup methods
-
-## Localization Support
-- Include translated content
-- Support multiple currencies
-- Use locale-appropriate formatting
-- Test with different regions
diff --git a/storefront/.cursor/rules/storefront.mdc b/storefront/.cursor/rules/storefront.mdc
deleted file mode 100644
index 05b259bdc9..0000000000
--- a/storefront/.cursor/rules/storefront.mdc
+++ /dev/null
@@ -1,423 +0,0 @@
----
-alwaysApply: true
----
-
-# Spree Storefront Rules
-
-## Controller Standards
-- Storefront controllers inherit from `Spree::StoreController`
-- Handle customer-facing functionality
-- Implement proper SEO and caching
-- Use secure session handling
-
-```ruby
-# ✅ Storefront controller structure
-class Spree::ProductsController < Spree::StoreController
- before_action :find_product, only: [:show]
-
- def index
- @products = current_store.products.available.includes(:images, :variants)
- @products = @products.ransack(params[:q]).result if params[:q].present?
- @products = @products.page(params[:page])
- end
-
- def show
- @variants = @product.variants.includes(:images, :option_values)
- @product_properties = @product.product_properties.includes(:property)
- end
-
- private
-
- def find_product
- @product = current_store.products.friendly.find(params[:id])
- rescue ActiveRecord::RecordNotFound
- redirect_to products_path, alert: Spree.t('product_not_found')
- end
-end
-```
-
-## View Standards
-- Use Tailwind CSS for styling
-- Follow responsive design principles
-- Implement proper semantic HTML
-- Include accessibility attributes
-
-```erb
-<!-- ✅ Proper storefront view structure -->
-<article class="product-details" itemscope itemtype="http://schema.org/Product">
- <header class="product-header">
- <h1 class="text-3xl font-bold text-gray-900" itemprop="name">
- <%= @product.name %>
- </h1>
-
- <div class="mt-2">
- <span class="text-2xl font-semibold text-gray-900" itemprop="price">
- <%= @product.display_price %>
- </span>
- </div>
- </header>
-
- <div class="product-description mt-6" itemprop="description">
- <%= simple_format(@product.description) %>
- </div>
-</article>
-```
-
-## JavaScript & Stimulus
-
-- Try to use Turbo for all AJAX requests
-- Use Stimulus for interactive components that cannot be handled by Turbo
-- Place Stimulus controllers in `app/javascript/controllers/spree/storefront/`
-- Follow progressive enhancement principles
-- Minimize JavaScript dependencies
-
-```javascript
-// ✅ Storefront Stimulus controller
-import { Controller } from "@hotwired/stimulus"
-import { post } from "@rails/request.js"
-
-export default class extends Controller {
- static targets = ["quantity", "addToCart"]
- static values = {
- productId: Number,
- variantId: Number
- }
-
- connect() {
- this.updateAddToCartState()
- }
-
- updateQuantity(event) {
- const quantity = parseInt(event.target.value)
- this.updateAddToCartState()
- }
-
- async addToCart(event) {
- event.preventDefault()
-
- const response = await post('/line_items', {
- body: {
- variant_id: this.variantIdValue,
- quantity: this.quantityTarget.value
- }
- })
-
- if (response.ok) {
- const data = await response.json
- this.handleAddToCartResponse(data)
- }
- }
-}
-
-## SEO Standards
-- Include proper meta tags
-- Use structured data markup
-- Implement canonical URLs
-- Optimize page titles and descriptions
-
-```erb
-<!-- ✅ SEO meta tags -->
-<% content_for :title, @product.meta_title.presence || @product.name %>
-<% content_for :description, @product.meta_description.presence || truncate(@product.description, length: 160) %>
-
-<%= content_tag :div, itemscope: true, itemtype: "http://schema.org/Product" do %>
- <meta itemprop="name" content="<%= @product.name %>" />
- <meta itemprop="description" content="<%= @product.description %>" />
- <meta itemprop="sku" content="<%= @product.sku %>" />
- <!-- Product content -->
-<% end %>
-```
-
-## Performance Standards
-- Implement fragment caching
-- For images please use `spree_image_tag`, `spree_image_url` and `spree_image_path` helpers which automatically serve optimized WEBP images
-- Minimize HTTP requests
-- Implement lazy loading
-
-## Form Standards
-- Use Rails form helpers
-- Implement CSRF protection
-- Add proper validation feedback
-- Handle errors gracefully
-
-## Helper Standards
-- Place helpers in `app/helpers/spree/`
-- Use helpers for view-specific logic
-- Keep helpers simple and testable
-
-## Navigation Standards
-- Implement responsive navigation
-- Use proper ARIA labels
-- Support keyboard navigation
-- Include search functionality
-
-## Cart & Checkout Standards
-- Use AJAX for cart updates
-- Implement guest checkout
-- Handle payment errors gracefully
-- Provide clear progress indicators
-
-## Mobile Standards
-- Mobile-first responsive design
-- Touch-friendly interface elements
-- Optimize for mobile performance
-- Test on multiple device sizes
-
-## Accessibility Standards
-- Include proper ARIA labels
-- Ensure keyboard navigation
-- Maintain color contrast ratios
-- Provide alternative text for images
-
-## Testing Standards
-- Test critical user journeys
-- Use feature specs for integration testing
-- Test responsive behavior
-- Include accessibility testing
-
-```ruby
-# ✅ Storefront feature spec
-require 'spec_helper'
-
-RSpec.feature 'Product browsing', type: :feature, js: true do
- let!(:product) { create(:product, name: 'Test Product') }
-
- scenario 'viewing product details' do
- visit spree.product_path(product)
-
- expect(page).to have_content('Test Product')
- expect(page).to have_button('Add to Cart')
- expect(page).to have_css('[itemtype="http://schema.org/Product"]')
- end
-
- scenario 'adding product to cart' do
- visit spree.product_path(product)
-
- click_button 'Add to Cart'
-
- expect(page).to have_content('Item added to cart')
- expect(page).to have_css('.cart-count', text: '1')
- end
-end
-```
-
-## Translation Files
-- Place storefront translations in `storefront/config/locales/en.yml`
-- Use customer-friendly language
-- Include error messages and validation text
-
-## Security Standards
-- Sanitize user inputs
-- Implement rate limiting for forms
-- Use HTTPS for sensitive operations
-- Validate all form submissions
-
-# Spree Storefront Rules
-
-## Controller Standards
-- Storefront controllers inherit from `Spree::StoreController`
-- Handle customer-facing functionality
-- Implement proper SEO and caching
-- Use secure session handling
-
-```ruby
-# ✅ Storefront controller structure
-class Spree::ProductsController < Spree::StoreController
- before_action :find_product, only: [:show]
-
- def index
- @products = current_store.products.available.includes(:images, :variants)
- @products = @products.ransack(params[:q]).result if params[:q].present?
- @products = @products.page(params[:page])
- end
-
- def show
- @variants = @product.variants.includes(:images, :option_values)
- @product_properties = @product.product_properties.includes(:property)
- end
-
- private
-
- def find_product
- @product = current_store.products.friendly.find(params[:id])
- rescue ActiveRecord::RecordNotFound
- redirect_to products_path, alert: Spree.t('product_not_found')
- end
-end
-```
-
-## View Standards
-- Use Tailwind CSS for styling
-- Follow responsive design principles
-- Implement proper semantic HTML
-- Include accessibility attributes
-
-```erb
-<!-- ✅ Proper storefront view structure -->
-<article class="product-details" itemscope itemtype="http://schema.org/Product">
- <header class="product-header">
- <h1 class="text-3xl font-bold text-gray-900" itemprop="name">
- <%= @product.name %>
- </h1>
-
- <div class="mt-2">
- <span class="text-2xl font-semibold text-gray-900" itemprop="price">
- <%= @product.display_price %>
- </span>
- </div>
- </header>
-
- <div class="product-description mt-6" itemprop="description">
- <%= simple_format(@product.description) %>
- </div>
-</article>
-```
-
-## JavaScript & Stimulus
-
-- Try to use Turbo for all AJAX requests
-- Use Stimulus for interactive components that cannot be handled by Turbo
-- Place Stimulus controllers in `app/javascript/controllers/spree/storefront/`
-- Follow progressive enhancement principles
-- Minimize JavaScript dependencies
-
-```javascript
-// ✅ Storefront Stimulus controller
-import { Controller } from "@hotwired/stimulus"
-import { post } from "@rails/request.js"
-
-export default class extends Controller {
- static targets = ["quantity", "addToCart"]
- static values = {
- productId: Number,
- variantId: Number
- }
-
- connect() {
- this.updateAddToCartState()
- }
-
- updateQuantity(event) {
- const quantity = parseInt(event.target.value)
- this.updateAddToCartState()
- }
-
- async addToCart(event) {
- event.preventDefault()
-
- const response = await post('/line_items', {
- body: {
- variant_id: this.variantIdValue,
- quantity: this.quantityTarget.value
- }
- })
-
- if (response.ok) {
- const data = await response.json
- this.handleAddToCartResponse(data)
- }
- }
-}
-
-## SEO Standards
-- Include proper meta tags
-- Use structured data markup
-- Implement canonical URLs
-- Optimize page titles and descriptions
-
-```erb
-<!-- ✅ SEO meta tags -->
-<% content_for :title, @product.meta_title.presence || @product.name %>
-<% content_for :description, @product.meta_description.presence || truncate(@product.description, length: 160) %>
-
-<%= content_tag :div, itemscope: true, itemtype: "http://schema.org/Product" do %>
- <meta itemprop="name" content="<%= @product.name %>" />
- <meta itemprop="description" content="<%= @product.description %>" />
- <meta itemprop="sku" content="<%= @product.sku %>" />
- <!-- Product content -->
-<% end %>
-```
-
-## Performance Standards
-- Implement fragment caching
-- For images please use `spree_image_tag`, `spree_image_url` and `spree_image_path` helpers which automatically serve optimized WEBP images
-- Minimize HTTP requests
-- Implement lazy loading
-
-## Form Standards
-- Use Rails form helpers
-- Implement CSRF protection
-- Add proper validation feedback
-- Handle errors gracefully
-
-## Helper Standards
-- Place helpers in `app/helpers/spree/`
-- Use helpers for view-specific logic
-- Keep helpers simple and testable
-
-## Navigation Standards
-- Implement responsive navigation
-- Use proper ARIA labels
-- Support keyboard navigation
-- Include search functionality
-
-## Cart & Checkout Standards
-- Use AJAX for cart updates
-- Implement guest checkout
-- Handle payment errors gracefully
-- Provide clear progress indicators
-
-## Mobile Standards
-- Mobile-first responsive design
-- Touch-friendly interface elements
-- Optimize for mobile performance
-- Test on multiple device sizes
-
-## Accessibility Standards
-- Include proper ARIA labels
-- Ensure keyboard navigation
-- Maintain color contrast ratios
-- Provide alternative text for images
-
-## Testing Standards
-- Test critical user journeys
-- Use feature specs for integration testing
-- Test responsive behavior
-- Include accessibility testing
-
-```ruby
-# ✅ Storefront feature spec
-require 'spec_helper'
-
-RSpec.feature 'Product browsing', type: :feature, js: true do
- let!(:product) { create(:product, name: 'Test Product') }
-
- scenario 'viewing product details' do
- visit spree.product_path(product)
-
- expect(page).to have_content('Test Product')
- expect(page).to have_button('Add to Cart')
- expect(page).to have_css('[itemtype="http://schema.org/Product"]')
- end
-
- scenario 'adding product to cart' do
- visit spree.product_path(product)
-
- click_button 'Add to Cart'
-
- expect(page).to have_content('Item added to cart')
- expect(page).to have_css('.cart-count', text: '1')
- end
-end
-```
-
-## Translation Files
-- Place storefront translations in `storefront/config/locales/en.yml`
-- Use customer-friendly language
-- Include error messages and validation text
-
-## Security Standards
-- Sanitize user inputs
-- Implement rate limiting for forms
-- Use HTTPS for sensitive operations
-- Validate all form submissions