spree_core 5.4.3 → 5.5.0.rc2

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

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+require_relative '../model/model_generator'
+
+module Spree
+  # spree:api_resource — scaffold a complete v3-conformant API resource on
+  # top of `spree:model`.
+  #
+  #   bin/rails g spree:api_resource Brand name:string:uniq active:boolean --writable
+  #
+  # Inherits from Spree::ModelGenerator (model + migration with Spree
+  # conventions: prefixed IDs, spree_-prefixed tables, null: false, optional
+  # acts_as_paranoid + Spree::Metafields). Adds on top:
+  #
+  #   - Store + Admin controllers     (managed — overwrite on re-run)
+  #   - Store + Admin serializers     (managed — overwrite on re-run)
+  #   - Factory                       (managed — overwrite on re-run)
+  #   - Controller specs              (managed — overwrite on re-run)
+  #   - Routes                        (idempotent inject between sentinels)
+  #
+  # Owned-once contract: if the model file already exists, the generator
+  # leaves it (and the migration) alone — domain code is yours after
+  # creation. Re-running adds/updates API surfaces only.
+  #
+  # TypeScript types and Zod schemas regenerate automatically via the
+  # Lefthook pre-commit hook when a serializer file is staged.
+  #
+  # See docs/plans/spree-dev-cli-and-generators.md (Track 3) for the
+  # owned-once / managed-forever / append-only contract.
+  class ApiResourceGenerator < Spree::ModelGenerator
+    # API-specific templates live alongside this generator. Parent's
+    # templates (model.rb.tt, create_table_migration.rb.tt) are inherited
+    # via Spree::ModelGenerator.source_paths.
+    def self.source_paths
+      [File.expand_path('templates', __dir__), *superclass.source_paths]
+    end
+
+    class_option :store,
+                 type: :boolean,
+                 default: true,
+                 desc: 'Generate Store API controller + serializer'
+
+    class_option :admin,
+                 type: :boolean,
+                 default: true,
+                 desc: 'Generate Admin API controller + serializer'
+
+    class_option :store_name,
+                 type: :string,
+                 desc: 'Expose Store API under a different name (e.g. Brand → Discount)'
+
+    class_option :writable,
+                 type: :boolean,
+                 default: false,
+                 desc: 'Make the Store API writable (create/update/destroy)'
+
+    class_option :skip_routes,
+                 type: :boolean,
+                 default: false,
+                 desc: "Don't inject routes into spree/api/config/routes.rb"
+
+    class_option :skip_specs,
+                 type: :boolean,
+                 default: false,
+                 desc: "Don't generate controller specs"
+
+    # api_resource generates its own controller specs and factory directly,
+    # so we remove the parent's spec/fixture hooks. Otherwise Rails would
+    # invoke rspec (boots Rails → PendingMigrationError on the freshly-
+    # created migration; or "[not found]" warning on re-runs).
+    remove_hook_for :test_framework
+    remove_hook_for :fixture_replacement if hooks[:fixture_replacement]
+
+    # Re-runs are part of the contract (owned-once gating skips the model
+    # and migration). Rails' NamedBase collision check would otherwise abort
+    # the second run with "Spree::Brand is already used in your application".
+    class_option :skip_collision_check, type: :boolean, default: true, desc: false
+
+    desc 'Scaffold a complete v3-conformant API resource (model + migration + controllers + serializers + routes + factory + specs)'
+
+    # --- Owned-once gating ---
+    #
+    # Thor's parent commands run BEFORE subclass commands (commands merge
+    # from superclass first). So we can't snapshot model existence in a
+    # subclass action and have parent's create_model_file see it. We
+    # capture state in initialize, before any action runs.
+
+    def initialize(*args)
+      super
+      @model_existed_before_run = File.exist?(File.join(destination_root, model_file_destination))
+    end
+
+    # Override parent: skip if the model file already exists. Re-running
+    # never overwrites domain code.
+    def create_model_file
+      if @model_existed_before_run
+        say_status :skip, "model #{model_file_destination} (owned-once; already exists)", :yellow
+        return
+      end
+      super
+    end
+
+    # 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
+    def create_migration_file
+      if @model_existed_before_run
+        say_status :skip, 'migration (model already exists; add a new migration for schema changes)', :yellow
+        return
+      end
+      super
+    end
+
+    # --- API surface ---
+
+    def create_store_controller
+      return unless options[:store]
+
+      template 'store_controller.rb.tt', store_controller_path
+    end
+
+    def create_admin_controller
+      return unless options[:admin]
+
+      template 'admin_controller.rb.tt', admin_controller_path
+    end
+
+    def create_store_serializer
+      return unless options[:store]
+
+      template 'store_serializer.rb.tt', store_serializer_path
+
+      # --store-name aliases the store-facing class under a different name
+      # (e.g. Brand → Discount) while keeping the model/table internal.
+      if store_external_name != bare_class_name
+        template 'store_aliased_serializer.rb.tt',
+                 "app/serializers/spree/api/v3/#{store_external_name.underscore}_serializer.rb"
+      end
+    end
+
+    def create_admin_serializer
+      return unless options[:admin]
+
+      template 'admin_serializer.rb.tt', admin_serializer_path
+    end
+
+    def create_factory
+      # spec/factories/ is the FactoryBot default scan path that a freshly-
+      # generated `rspec:install` + `factory_bot_rails` setup already picks
+      # up via `FactoryBot.find_definitions`. Spree's own factories live
+      # under lib/spree/testing_support/factories/ because that path is
+      # exported by gems; downstream apps don't have that loader by default.
+      template 'factory.rb.tt', "spec/factories/spree/#{singular_name}_factory.rb"
+    end
+
+    def create_controller_specs
+      return if options[:skip_specs]
+
+      if options[:store]
+        template 'store_controller_spec.rb.tt',
+                 "spec/controllers/spree/api/v3/store/#{plural_name}_controller_spec.rb"
+      end
+      if options[:admin]
+        template 'admin_controller_spec.rb.tt',
+                 "spec/controllers/spree/api/v3/admin/#{plural_name}_controller_spec.rb"
+      end
+    end
+
+    def inject_routes
+      return if options[:skip_routes]
+
+      routes_file = api_routes_path
+
+      unless File.exist?(routes_file) && File.writable?(routes_file)
+        say_status :skip, "routes.rb at #{routes_file} (not writable — only edge installs can modify gem source)", :yellow
+        return
+      end
+
+      inject_route_for(:store, store_route_line) if options[:store]
+      inject_route_for(:admin, admin_route_line) if options[:admin]
+    end
+
+    def print_summary
+      say ''
+      say "✓ Generated Spree::#{bare_class_name} API resource", :green
+      say ''
+      say "  Prefixed ID:  #{id_prefix}_xxxxxxxxxx  (edit `has_prefix_id` in the model to change)"
+      if store_external_name != bare_class_name
+        say "  Store API:    /api/v3/store/#{store_external_plural}  (aliased from #{bare_class_name})"
+      elsif options[:store]
+        say "  Store API:    /api/v3/store/#{plural_name}  (#{writable? ? 'full CRUD' : 'read-only'})"
+      end
+      say "  Admin API:    /api/v3/admin/#{plural_name}  (full CRUD)" if options[:admin]
+      say ''
+      say '  Next steps:', :yellow
+      say '    1. Review the generated model — add validations, scopes, callbacks'
+      say '    2. Apply the migration:  pnpm exec spree migrate'
+      say '    3. Set up authorization (CanCanCan ability) for the resource'
+      say '    4. Decide whether this resource is store-scoped (add `has_many` on Store)'
+      if options[:store] || options[:admin]
+        say '    5. Run the specs:  pnpm exec spree exec bundle exec rspec spec/controllers/spree/api/v3/'
+      end
+      say ''
+    end
+
+    # --- Helpers exposed to templates and other actions ---
+
+    no_tasks do
+      def writable?
+        options[:writable]
+      end
+
+      # NamedBase's class_name includes the namespace prefix (e.g. Spree::Brand
+      # when class_path is forced to ["spree"]). Templates that nest under
+      # `module Spree` need the bare name to avoid Spree::Spree::Brand.
+      def bare_class_name
+        class_name.demodulize
+      end
+
+      # The external name the Store API surfaces this as. Defaults to the
+      # canonical class name; --store-name overrides (e.g. Brand → Discount).
+      def store_external_name
+        options[:store_name] || bare_class_name
+      end
+
+      def store_external_plural
+        store_external_name.tableize
+      end
+
+      # Used in templates that refer to the resource by singular/plural
+      # snake_case identifiers (factory names, file names, route names).
+      def singular_name
+        file_name
+      end
+
+      def plural_name
+        file_name.pluralize
+      end
+
+      # Attributes the controller permits on write. By default, every column
+      # except references (FKs come through nested), attachments, rich text.
+      def permitted_attribute_names
+        attributes
+          .reject { |a| a.reference? || a.attachment? || a.attachments? || a.rich_text? || a.token? || a.password_digest? }
+          .map(&:name)
+      end
+    end
+
+    private
+
+    # Where the model file lands. We use parent's class_path + file_name so
+    # this stays in sync with whatever Spree::ModelGenerator decides.
+    def model_file_destination
+      File.join('app/models', class_path, "#{file_name}.rb")
+    end
+
+    def store_controller_path
+      "app/controllers/spree/api/v3/store/#{plural_name}_controller.rb"
+    end
+
+    def admin_controller_path
+      "app/controllers/spree/api/v3/admin/#{plural_name}_controller.rb"
+    end
+
+    def store_serializer_path
+      "app/serializers/spree/api/v3/#{singular_name}_serializer.rb"
+    end
+
+    def admin_serializer_path
+      "app/serializers/spree/api/v3/admin/#{singular_name}_serializer.rb"
+    end
+
+    # Absolute path to spree_api's routes.rb. On edge installs (SPREE_PATH set)
+    # this resolves to the monorepo source; on a published-gem install it
+    # resolves to the gem cache directory (typically read-only).
+    def api_routes_path
+      File.join(Gem.loaded_specs['spree_api'].full_gem_path, 'config/routes.rb')
+    end
+
+    # The routes line we inject into the Store namespace.
+    # --writable expands to full CRUD; default is read-only (index/show).
+    def store_route_line
+      if store_external_name != bare_class_name
+        # --store-name Discount: alias under a different external name,
+        # but route to the canonical controller (brands).
+        if writable?
+          "        resources :#{store_external_plural}, controller: '#{plural_name}'"
+        else
+          "        resources :#{store_external_plural}, controller: '#{plural_name}', only: [:index, :show]"
+        end
+      elsif writable?
+        "        resources :#{plural_name}"
+      else
+        "        resources :#{plural_name}, only: [:index, :show]"
+      end
+    end
+
+    # Admin always gets full CRUD.
+    def admin_route_line
+      "        resources :#{plural_name}"
+    end
+
+    # The 8-space-indented sentinel markers.
+    BEGIN_MARKER = '        # BEGIN spree:api_resource managed routes'.freeze
+    END_MARKER   = '        # END spree:api_resource managed routes'.freeze
+
+    # Idempotent injection. First run: insert sentinels + the route line at
+    # the top of the namespace. Subsequent runs: find the existing sentinels
+    # and insert the route line between them only if not already present.
+    def inject_route_for(namespace, route_line)
+      file = api_routes_path
+      content = File.read(file)
+
+      sentinel_pattern = sentinel_pattern_for(namespace)
+
+      if content =~ sentinel_pattern
+        # Sentinels exist for this namespace — find the block, check if
+        # `resources :<plural>` is already there.
+        block = Regexp.last_match(0)
+        if block.include?(route_line.strip)
+          say_status :identical, "routes.rb (#{namespace}: #{route_line.strip})", :blue
+          return
+        end
+
+        # Insert just above the END marker, preserving the existing block.
+        new_block = block.sub(END_MARKER, "#{route_line}\n#{END_MARKER}")
+        File.write(file, content.sub(block, new_block))
+        say_status :inject, "routes.rb (#{namespace}: #{route_line.strip})", :green
+      else
+        # First run for this namespace — inject the full block right after
+        # the namespace's opening line.
+        opening = "      namespace :#{namespace} do\n"
+        new_block = "#{BEGIN_MARKER}\n#{route_line}\n#{END_MARKER}\n\n"
+        updated = content.sub(opening, opening + new_block)
+        if updated == content
+          # The namespace anchor wasn't found — likely a non-default
+          # routes.rb. Warn rather than silently claim success.
+          say_status :skip, "routes.rb (#{namespace}: namespace block not found — add manually)", :yellow
+          return
+        end
+        File.write(file, updated)
+        say_status :inject, "routes.rb (#{namespace}: sentinels + #{route_line.strip})", :green
+      end
+    end
+
+    # Match the BEGIN…END block scoped to a specific namespace. Anchors on
+    # the namespace's opening line so we don't accidentally match the Admin
+    # block when looking at Store and vice versa.
+    def sentinel_pattern_for(namespace)
+      /#{Regexp.escape("namespace :#{namespace} do")}.*?#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}/m
+    end
+  end
+end

data/lib/generators/spree/api_resource/templates/admin_controller.rb.tt

@@ -0,0 +1,23 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class <%= plural_name.camelize %>Controller < ResourceController
+          protected
+
+          def model_class
+            Spree::<%= class_name.demodulize %>
+          end
+
+          def serializer_class
+            Spree::Api::V3::Admin::<%= bare_class_name %>Serializer
+          end
+
+          def permitted_params
+            params.permit(<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/spree/api_resource/templates/admin_controller_spec.rb.tt

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::<%= plural_name.camelize %>Controller, type: :controller do
+  render_views
+
+  include_context 'API v3 Admin authenticated'
+
+  let!(:<%= singular_name %>) { create(:<%= singular_name %>) }
+
+  before { request.headers.merge!(headers) }
+
+  describe 'GET #index' do
+    subject { get :index, as: :json }
+
+    it 'returns <%= plural_name %>' do
+      subject
+      expect(response).to have_http_status(:ok)
+      expect(json_response['data']).to be_an(Array)
+      expect(json_response['data'].map { |r| r['id'] }).to include(<%= singular_name %>.prefixed_id)
+    end
+  end
+
+  describe 'GET #show' do
+    subject { get :show, params: { id: <%= singular_name %>.prefixed_id }, as: :json }
+
+    it 'returns the <%= singular_name %>' do
+      subject
+      expect(response).to have_http_status(:ok)
+      expect(json_response['id']).to eq(<%= singular_name %>.prefixed_id)
+    end
+  end
+
+  describe 'POST #create' do
+    let(:create_params) { attributes_for(:<%= singular_name %>) }
+
+    it 'creates a <%= singular_name %>' do
+      expect { post :create, params: create_params, as: :json }.to change(Spree::<%= bare_class_name %>, :count).by(1)
+      expect(response).to have_http_status(:created)
+    end
+  end
+
+  describe 'PATCH #update' do
+    let(:update_params) { { id: <%= singular_name %>.prefixed_id }.merge(attributes_for(:<%= singular_name %>)) }
+
+    it 'updates the <%= singular_name %>' do
+      patch :update, params: update_params, as: :json
+      expect(response).to have_http_status(:ok)
+    end
+  end
+
+  describe 'DELETE #destroy' do
+    subject { delete :destroy, params: { id: <%= singular_name %>.prefixed_id }, as: :json }
+
+    it 'deletes the <%= singular_name %>' do
+      expect { subject }.to change(Spree::<%= bare_class_name %>, :count).by(-1)
+      expect(response).to have_http_status(:no_content)
+    end
+  end
+end

data/lib/generators/spree/api_resource/templates/admin_serializer.rb.tt

@@ -0,0 +1,11 @@
+module Spree
+  module Api
+    module V3
+      module Admin
+        class <%= bare_class_name %>Serializer < V3::<%= bare_class_name %>Serializer
+          attributes :created_at, :updated_at<%= ', :deleted_at' if paranoid? %>
+        end
+      end
+    end
+  end
+end

data/lib/generators/spree/api_resource/templates/factory.rb.tt

@@ -0,0 +1,26 @@
+FactoryBot.define do
+  factory :<%= singular_name %>, class: Spree::<%= bare_class_name %> do
+<% attributes.reject(&:reference?).each do |attr| -%>
+<% case attr.type
+   when :boolean -%>
+    <%= attr.name %> { true }
+<% when :integer, :decimal, :float -%>
+    <%= attr.name %> { 1 }
+<% when :date -%>
+    <%= attr.name %> { Date.current }
+<% when :datetime -%>
+    <%= attr.name %> { Time.current }
+<% else -%>
+    sequence(:<%= attr.name %>) { |n| "<%= bare_class_name %> #{n}" }
+<% end -%>
+<% end -%>
+<% attributes.select(&:reference?).each do |attr| -%>
+<% if attr.polymorphic? -%>
+    # <%= attr.name %> is polymorphic — point it at a concrete factory before using:
+    # association :<%= attr.name %>, factory: :product
+<% else -%>
+    association :<%= attr.name %>
+<% end -%>
+<% end -%>
+  end
+end

data/lib/generators/spree/api_resource/templates/store_aliased_serializer.rb.tt

@@ -0,0 +1,12 @@
+# --store-name=<%= store_external_name %>: this serializer aliases <%= bare_class_name %>Serializer
+# so the Store API surfaces the resource under a different external name
+# (e.g. internal Brand → public Discount). The model and table stay as
+# <%= bare_class_name %> / <%= table_name %>.
+module Spree
+  module Api
+    module V3
+      class <%= store_external_name %>Serializer < <%= bare_class_name %>Serializer
+      end
+    end
+  end
+end

data/lib/generators/spree/api_resource/templates/store_controller.rb.tt

@@ -0,0 +1,31 @@
+module Spree
+  module Api
+    module V3
+      module Store
+        class <%= plural_name.camelize %>Controller < ResourceController
+          protected
+
+          def model_class
+            Spree::<%= class_name.demodulize %>
+          end
+
+<% if store_external_name != bare_class_name -%>
+          def serializer_class
+            Spree::Api::V3::<%= store_external_name %>Serializer
+          end
+<% else -%>
+          def serializer_class
+            Spree::Api::V3::<%= bare_class_name %>Serializer
+          end
+<% end -%>
+<% if writable? -%>
+
+          def permitted_params
+            params.permit(<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>)
+          end
+<% end -%>
+        end
+      end
+    end
+  end
+end

data/lib/generators/spree/api_resource/templates/store_controller_spec.rb.tt

@@ -0,0 +1,61 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Store::<%= plural_name.camelize %>Controller, type: :controller do
+  render_views
+
+  include_context 'API v3 Store'
+
+  let!(:<%= singular_name %>) { create(:<%= singular_name %>) }
+
+  before { request.headers.merge!(headers) }
+
+  describe 'GET #index' do
+    subject { get :index, as: :json }
+
+    it 'returns <%= plural_name %>' do
+      subject
+      expect(response).to have_http_status(:ok)
+      expect(json_response['data']).to be_an(Array)
+      expect(json_response['data'].map { |r| r['id'] }).to include(<%= singular_name %>.prefixed_id)
+    end
+  end
+
+  describe 'GET #show' do
+    subject { get :show, params: { id: <%= singular_name %>.prefixed_id }, as: :json }
+
+    it 'returns the <%= singular_name %>' do
+      subject
+      expect(response).to have_http_status(:ok)
+      expect(json_response['id']).to eq(<%= singular_name %>.prefixed_id)
+    end
+  end
+<% if writable? -%>
+
+  describe 'POST #create' do
+    let(:create_params) { attributes_for(:<%= singular_name %>) }
+
+    it 'creates a <%= singular_name %>' do
+      expect { post :create, params: create_params, as: :json }.to change(Spree::<%= bare_class_name %>, :count).by(1)
+      expect(response).to have_http_status(:created)
+    end
+  end
+
+  describe 'PATCH #update' do
+    let(:update_params) { { id: <%= singular_name %>.prefixed_id }.merge(attributes_for(:<%= singular_name %>)) }
+
+    it 'updates the <%= singular_name %>' do
+      patch :update, params: update_params, as: :json
+      expect(response).to have_http_status(:ok)
+    end
+  end
+
+  describe 'DELETE #destroy' do
+    subject { delete :destroy, params: { id: <%= singular_name %>.prefixed_id }, as: :json }
+
+    it 'deletes the <%= singular_name %>' do
+      expect { subject }.to change(Spree::<%= bare_class_name %>, :count).by(-1)
+      expect(response).to have_http_status(:no_content)
+    end
+  end
+<% end -%>
+end

data/lib/generators/spree/api_resource/templates/store_serializer.rb.tt

@@ -0,0 +1,17 @@
+<%# Decimal columns serialize as strings on the wire (Alba's oj_rails backend
+    casts BigDecimal via as_json), so they must be typed :string — only
+    integer/float are real JSON numbers. -%>
+<% typelizable = attributes.reject(&:reference?).select { |a| %i[boolean integer decimal float].include?(a.type) } -%>
+module Spree
+  module Api
+    module V3
+      class <%= bare_class_name %>Serializer < BaseSerializer
+<% if typelizable.any? -%>
+        typelize <%= typelizable.map { |a| type = a.type == :boolean ? 'boolean' : (a.type == :decimal ? 'string' : 'number'); "#{a.name}: :#{type}" }.join(', ') %>
+
+<% end -%>
+        attributes <%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>
+      end
+    end
+  end
+end

data/lib/generators/spree/controller_decorator/controller_decorator_generator.rb

@@ -0,0 +1,66 @@
+module Spree
+  # spree:controller_decorator — generate a decorator file for an existing
+  # Spree controller. Mirrors the model_decorator generator but handles
+  # arbitrary namespace depth (Spree::ProductsController,
+  # Spree::Admin::ProductsController, Spree::Api::V3::Store::ProductsController).
+  #
+  # @example
+  #   bin/rails g spree:controller_decorator Spree::ProductsController
+  #     => app/controllers/spree/products_controller_decorator.rb
+  #
+  #   bin/rails g spree:controller_decorator Spree::Admin::ProductsController
+  #     => app/controllers/spree/admin/products_controller_decorator.rb
+  class ControllerDecoratorGenerator < Rails::Generators::NamedBase
+    desc 'Creates a controller decorator for a Spree controller'
+
+    argument :name, type: :string, required: true,
+                    banner: 'Spree::ControllerName | Spree::Namespace::ControllerName'
+
+    def self.source_paths
+      paths = superclass.source_paths
+      paths << File.expand_path('templates', __dir__)
+      paths.flatten
+    end
+
+    def create_controller_decorator_file
+      template 'controller_decorator.rb.tt',
+               "app/controllers/#{file_path}_decorator.rb"
+    end
+
+    private
+
+    # Strip a leading `Spree::` and split the remainder on `::`.
+    # `"Spree::Admin::ProductsController"` => `["Admin", "ProductsController"]`
+    def name_parts
+      @name_parts ||= name.sub(/\ASpree::/, '').split('::').reject(&:empty?)
+    end
+
+    # The unqualified controller name — the last segment.
+    def controller_name
+      name_parts.last
+    end
+
+    # The namespace segments above the controller, joined as a constant
+    # chain. Empty string when the controller sits directly under Spree.
+    def namespace_chain
+      name_parts[0..-2].join('::')
+    end
+
+    # The decorator module name.
+    def decorator_name
+      "#{controller_name}Decorator"
+    end
+
+    # Path under app/controllers/, including the `spree/` root.
+    def file_path
+      ['spree', *name_parts.map(&:underscore)].join('/')
+    end
+
+    # Fully-qualified `Spree::Foo::Bar.prepend Spree::Foo::BarDecorator`.
+    def prepend_invocation
+      target = "Spree::#{name_parts.join('::')}"
+      module_chain = ['Spree', *name_parts[0..-2], decorator_name].join('::')
+      "#{target}.prepend #{module_chain}"
+    end
+  end
+end