tsykvas_rails_template 0.1.0

data/lib/generators/tsykvas_rails_template/companions/companions_generator.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "tsykvas_rails_template/probe"
+
+module TsykvasRailsTemplate
+  module Generators
+    # Adds the recommended companion gems used across the author's reference
+    # projects (sport / planner / esl). Runs `bundle install` and the per-gem
+    # `:install` sub-generators (no User model is generated for Devise).
+    #
+    # Designed to be idempotent: re-running the generator does not duplicate
+    # Gemfile entries, re-run sub-generators, or re-inject configuration.
+    class CompanionsGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DESC
+        Add and install the recommended companion gems for tsykvas_rails_template.
+
+        Default groups: auth (devise + omniauth-csrf), forms (simple_form),
+        images (mini_magick), jobs-ui (mission_control-jobs, only if solid_queue),
+        test (rspec-rails + factory_bot_rails + shoulda-matchers + webmock + faker),
+        dev (dotenv-rails). Use --skip-* flags to opt out per group.
+
+        Devise's User model is NOT generated — run `rails g devise User` (or
+        whatever resource name fits your domain) yourself when ready.
+      DESC
+
+      class_option :skip_auth,
+                   type: :boolean, default: false,
+                   desc: "Don't add devise + omniauth-rails_csrf_protection"
+      class_option :skip_forms,
+                   type: :boolean, default: false,
+                   desc: "Don't add simple_form"
+      class_option :skip_images,
+                   type: :boolean, default: false,
+                   desc: "Don't add mini_magick"
+      class_option :skip_jobs_ui,
+                   type: :boolean, default: false,
+                   desc: "Don't add mission_control-jobs (or its mount)"
+      class_option :skip_test,
+                   type: :boolean, default: false,
+                   desc: "Don't add the rspec/factory_bot/shoulda/webmock/faker stack"
+      class_option :skip_dev,
+                   type: :boolean, default: false,
+                   desc: "Don't add dotenv-rails"
+      class_option :skip_bundle,
+                   type: :boolean, default: false,
+                   desc: "Don't run `bundle install` after editing Gemfile"
+      class_option :skip_post_install,
+                   type: :boolean, default: false,
+                   desc: "Don't run `:install` sub-generators or inject configs"
+
+      def add_top_level_gems
+        wanted = []
+        wanted += %w[devise omniauth-rails_csrf_protection] unless options[:skip_auth]
+        wanted << "simple_form" unless options[:skip_forms]
+        wanted << "mini_magick" unless options[:skip_images]
+        wanted << "mission_control-jobs" if !options[:skip_jobs_ui] && solid_queue_present?
+
+        wanted.each { |name| add_gem_if_missing(name) }
+      end
+
+      def add_test_group_gems
+        return if options[:skip_test]
+
+        add_grouped_gems(%i[development test], %w[rspec-rails factory_bot_rails faker])
+        add_grouped_gems([:test], %w[shoulda-matchers webmock])
+      end
+
+      def add_dev_group_gems
+        return if options[:skip_dev]
+
+        add_grouped_gems(%i[development test], %w[dotenv-rails])
+      end
+
+      def run_bundle_install
+        return if options[:skip_bundle]
+
+        in_root do
+          Bundler.with_unbundled_env do
+            run "bundle install"
+          end
+        end
+      end
+
+      # Bump the companion gems we just added to their latest matching
+      # versions. `bundle install` is a no-op on re-runs where Gemfile.lock
+      # already pins older versions; `bundle update` lifts those pins within
+      # whatever constraint the Gemfile expresses (none, by default → latest).
+      def bundle_update_companions
+        return if options[:skip_bundle]
+
+        names = companion_gem_names
+        return if names.empty?
+
+        in_root do
+          Bundler.with_unbundled_env { run "bundle update #{names.join(" ")}" }
+        end
+      end
+
+      def run_devise_install
+        return if skip_post_install_for?(:auth)
+        return if File.exist?(destination_path("config/initializers/devise.rb"))
+
+        generate "devise:install"
+      end
+
+      def run_simple_form_install
+        return if skip_post_install_for?(:forms)
+        return if File.exist?(destination_path("config/initializers/simple_form.rb"))
+
+        flag = probe[:has_bootstrap] ? " --bootstrap" : ""
+        generate "simple_form:install#{flag}"
+      end
+
+      def run_rspec_install
+        return if skip_post_install_for?(:test)
+        return if File.exist?(destination_path("spec/rails_helper.rb"))
+
+        generate "rspec:install"
+      end
+
+      def configure_shoulda_matchers
+        return if skip_post_install_for?(:test)
+        return unless File.exist?(destination_path("spec/rails_helper.rb"))
+        return if File.read(destination_path("spec/rails_helper.rb")).include?("Shoulda::Matchers")
+
+        append_to_file "spec/rails_helper.rb", shoulda_config_block
+      end
+
+      def configure_webmock
+        return if skip_post_install_for?(:test)
+        return unless File.exist?(destination_path("spec/rails_helper.rb"))
+        return if File.read(destination_path("spec/rails_helper.rb")).include?("WebMock.disable_net_connect!")
+
+        append_to_file "spec/rails_helper.rb", webmock_config_block
+      end
+
+      def mount_mission_control_jobs
+        return if skip_post_install_for?(:jobs_ui)
+        return unless solid_queue_present?
+        return unless File.exist?(destination_path("config/routes.rb"))
+        return if File.read(destination_path("config/routes.rb")).include?("MissionControl::Jobs::Engine")
+
+        route mission_control_route_block
+      end
+
+      def add_dotenv_to_gitignore
+        return if skip_post_install_for?(:dev)
+        return unless File.exist?(destination_path(".gitignore"))
+        return if File.read(destination_path(".gitignore")).match?(/^\.env\b/)
+
+        append_to_file ".gitignore",
+                       "\n# dotenv-rails (added by tsykvas_rails_template:companions)\n.env\n.env.*\n!.env.example\n"
+      end
+
+      def announce
+        say ""
+        say "  Companions installed.", :green
+        say "    Next: rails g devise User  (run yourself when your user schema is ready)"
+        say "    /jobs UI is mounted with admin-only constraint; needs User#admin?"
+        say "    Image processing requires ImageMagick installed system-wide."
+        say ""
+      end
+
+      private
+
+      def destination_path(rel)
+        File.join(destination_root, rel)
+      end
+
+      def gemfile_path
+        destination_path("Gemfile")
+      end
+
+      def gemfile_content
+        @gemfile_content = nil if defined?(@gemfile_content_mtime) && @gemfile_content_mtime != File.mtime(gemfile_path)
+        return "" unless File.exist?(gemfile_path)
+
+        @gemfile_content_mtime = File.mtime(gemfile_path)
+        @gemfile_content ||= File.read(gemfile_path)
+      end
+
+      def gem_in_gemfile?(name)
+        gemfile_content.match?(/^\s*gem\s+['"]#{Regexp.escape(name)}['"]/)
+      end
+
+      def add_gem_if_missing(name, *args)
+        if gem_in_gemfile?(name)
+          say_status :exist, "gem '#{name}' already in Gemfile", :blue
+          return
+        end
+
+        gem(name, *args)
+        # Force re-read on next gem_in_gemfile? check.
+        @gemfile_content = nil
+      end
+
+      def add_grouped_gems(groups, names)
+        needed = names.reject { |n| gem_in_gemfile?(n) }
+        return if needed.empty?
+
+        gem_group(*groups) { needed.each { |n| gem n } }
+        @gemfile_content = nil
+      end
+
+      COMPANION_GROUPS = {
+        skip_auth: %w[devise omniauth-rails_csrf_protection],
+        skip_forms: %w[simple_form],
+        skip_images: %w[mini_magick],
+        skip_test: %w[rspec-rails factory_bot_rails faker shoulda-matchers webmock],
+        skip_dev: %w[dotenv-rails]
+      }.freeze
+
+      def companion_gem_names
+        names = COMPANION_GROUPS.flat_map { |opt, gems| options[opt] ? [] : gems }
+        names << "mission_control-jobs" if !options[:skip_jobs_ui] && solid_queue_present?
+        names.select { |n| gem_in_gemfile?(n) }
+      end
+
+      def probe
+        @probe ||= TsykvasRailsTemplate::Probe.run(root: destination_root)
+      end
+
+      def solid_queue_present?
+        probe[:background_jobs].include?(:solid_queue)
+      end
+
+      def skip_post_install_for?(group)
+        return true if options[:skip_post_install]
+
+        options["skip_#{group}".to_sym]
+      end
+
+      def shoulda_config_block
+        <<~RUBY
+
+          # shoulda-matchers (added by tsykvas_rails_template:companions)
+          Shoulda::Matchers.configure do |config|
+            config.integrate do |with|
+              with.test_framework :rspec
+              with.library :rails
+            end
+          end
+        RUBY
+      end
+
+      def webmock_config_block
+        <<~RUBY
+
+          # webmock (added by tsykvas_rails_template:companions)
+          require "webmock/rspec"
+          WebMock.disable_net_connect!(allow_localhost: true)
+        RUBY
+      end
+
+      def mission_control_route_block
+        <<~RUBY
+          # MissionControl::Jobs UI — admins only.
+          # Lambda runs per request, so missing User model at boot doesn't crash.
+          # Without User#admin? all /jobs requests return 404 (lock-by-default).
+          mount MissionControl::Jobs::Engine,
+                at: "/jobs",
+                constraints: ->(req) {
+                  user = req.env["warden"]&.user
+                  user.respond_to?(:admin?) && user.admin?
+                }
+        RUBY
+      end
+    end
+  end
+end

data/lib/generators/tsykvas_rails_template/concept/concept_generator.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module TsykvasRailsTemplate
+  module Generators
+    class ConceptGenerator < ::Rails::Generators::Base
+      argument :concept_name,
+               type: :string,
+               banner: "ConceptName"
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DESC
+        Scaffold a new concept under app/concepts/<path>/{operation,component}/.
+
+        Examples:
+          rails g tsykvas_rails_template:concept Crm::Property
+          rails g tsykvas_rails_template:concept Property --controller
+          rails g tsykvas_rails_template:concept Admin::User --actions index show
+      DESC
+
+      class_option :actions,
+                   type: :array,
+                   default: %w[index show new create edit update destroy],
+                   desc: "Subset of CRUD actions to generate"
+
+      class_option :controller,
+                   type: :boolean,
+                   default: false,
+                   desc: "Also generate a thin controller"
+
+      VALID_CONCEPT_NAME = %r{\A[A-Za-z][A-Za-z0-9]*(?:(?:::|/)[A-Za-z][A-Za-z0-9]*)*\z}
+
+      def validate_concept_name
+        name = concept_name.to_s.strip
+
+        if name.empty?
+          raise ::Thor::Error,
+                "concept name is required (e.g. 'Crm::Property' or 'crm/property')"
+        end
+
+        if name.start_with?("::") || name.start_with?("/")
+          raise ::Thor::Error,
+                "concept name '#{name}' must not start with '::' or '/'"
+        end
+
+        return if name.match?(VALID_CONCEPT_NAME)
+
+        raise ::Thor::Error,
+              "concept name '#{name}' has invalid characters " \
+              "(allowed: letters, digits, '::' or '/' separators; " \
+              "each segment must start with a letter)"
+      end
+
+      def generate_operations
+        actions.each do |action|
+          template "operation/#{action}.rb.tt",
+                   "app/concepts/#{path}/operation/#{action}.rb"
+        end
+      end
+
+      def generate_components
+        component_actions.each do |action|
+          template "component/#{action}.rb.tt",
+                   "app/concepts/#{path}/component/#{action}.rb"
+          template "component/#{action}.html.slim.tt",
+                   "app/concepts/#{path}/component/#{action}.html.slim"
+        end
+      end
+
+      def generate_controller
+        return unless options[:controller]
+
+        template "controller.rb.tt",
+                 "app/controllers/#{controller_file_path}.rb"
+      end
+
+      def announce_next_steps
+        say ""
+        say "  Concept #{class_name} scaffolded.", :green
+        say "    - operations: app/concepts/#{path}/operation/"
+        say "    - components: app/concepts/#{path}/component/"
+        say "    - controller: app/controllers/#{controller_file_path}.rb" if options[:controller]
+        say "    Add routes for #{plural_var.tr("_", " ")} in config/routes.rb."
+        say "    Implement the policy at app/policies/#{singular_var}_policy.rb."
+        say ""
+      end
+
+      private
+
+      def actions
+        options[:actions]
+      end
+
+      def component_actions
+        actions & %w[index show new edit]
+      end
+
+      def class_name
+        @class_name ||= concept_name.split(%r{::|/}).reject(&:empty?).map(&:camelize).join("::")
+      end
+
+      def path
+        @path ||= class_name.gsub("::", "/").underscore
+      end
+
+      def singular_var
+        @singular_var ||= path.split("/").last
+      end
+
+      def plural_var
+        @plural_var ||= singular_var.pluralize
+      end
+
+      def resource_class
+        @resource_class ||= class_name.split("::").last
+      end
+
+      def i18n_key
+        @i18n_key ||= path.tr("/", ".")
+      end
+
+      def controller_class_name
+        parts = class_name.split("::")
+        parts[-1] = parts.last.pluralize
+        "#{parts.join("::")}Controller"
+      end
+
+      def controller_file_path
+        pieces = path.split("/")
+        pieces[-1] = pieces.last.pluralize
+        "#{pieces.join("/")}_controller"
+      end
+
+      def url_helper_singular
+        path.tr("/", "_")
+      end
+
+      def url_helper_plural
+        url_helper_singular.sub(/#{Regexp.escape(singular_var)}\z/, plural_var)
+      end
+    end
+  end
+end

data/lib/generators/tsykvas_rails_template/concept/templates/component/edit.html.slim.tt

@@ -0,0 +1,5 @@
+h1= I18n.t("<%= i18n_key %>.edit.title")
+
+= form_with model: @<%= singular_var %> do |f|
+  / TODO: form fields for <%= singular_var %>.
+  = f.submit

data/lib/generators/tsykvas_rails_template/concept/templates/component/edit.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Component::Edit < ::Base::Component::Base
+  def initialize(<%= singular_var %>:)
+    @<%= singular_var %> = <%= singular_var %>
+  end
+
+  private
+
+  attr_reader :<%= singular_var %>
+end

data/lib/generators/tsykvas_rails_template/concept/templates/component/index.html.slim.tt

@@ -0,0 +1,5 @@
+h1= I18n.t("<%= i18n_key %>.index.title")
+
+ul
+  - @<%= plural_var %>.each do |<%= singular_var %>|
+    li= <%= singular_var %>.id

data/lib/generators/tsykvas_rails_template/concept/templates/component/index.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Component::Index < ::Base::Component::Base
+  def initialize(<%= plural_var %>: [])
+    @<%= plural_var %> = <%= plural_var %>
+  end
+
+  private
+
+  attr_reader :<%= plural_var %>
+end

data/lib/generators/tsykvas_rails_template/concept/templates/component/new.html.slim.tt

@@ -0,0 +1,5 @@
+h1= I18n.t("<%= i18n_key %>.new.title")
+
+= form_with model: @<%= singular_var %> do |f|
+  / TODO: form fields for <%= singular_var %>.
+  = f.submit

data/lib/generators/tsykvas_rails_template/concept/templates/component/new.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Component::New < ::Base::Component::Base
+  def initialize(<%= singular_var %>:)
+    @<%= singular_var %> = <%= singular_var %>
+  end
+
+  private
+
+  attr_reader :<%= singular_var %>
+end

data/lib/generators/tsykvas_rails_template/concept/templates/component/show.html.slim.tt

@@ -0,0 +1,4 @@
+h1= I18n.t("<%= i18n_key %>.show.title")
+
+/ TODO: render @<%= singular_var %> attributes here.
+p ID: #{@<%= singular_var %>.id}

data/lib/generators/tsykvas_rails_template/concept/templates/component/show.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Component::Show < ::Base::Component::Base
+  def initialize(<%= singular_var %>:)
+    @<%= singular_var %> = <%= singular_var %>
+  end
+
+  private
+
+  attr_reader :<%= singular_var %>
+end

data/lib/generators/tsykvas_rails_template/concept/templates/controller.rb.tt

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class <%= controller_class_name %> < ApplicationController
+<% if actions.include?("index") -%>
+  def index
+    endpoint <%= class_name %>::Operation::Index, <%= class_name %>::Component::Index
+  end
+
+<% end -%>
+<% if actions.include?("show") -%>
+  def show
+    endpoint <%= class_name %>::Operation::Show, <%= class_name %>::Component::Show
+  end
+
+<% end -%>
+<% if actions.include?("new") -%>
+  def new
+    endpoint <%= class_name %>::Operation::New, <%= class_name %>::Component::New
+  end
+
+<% end -%>
+<% if actions.include?("create") -%>
+  def create
+    endpoint <%= class_name %>::Operation::Create, <%= class_name %>::Component::New
+  end
+
+<% end -%>
+<% if actions.include?("edit") -%>
+  def edit
+    endpoint <%= class_name %>::Operation::Edit, <%= class_name %>::Component::Edit
+  end
+
+<% end -%>
+<% if actions.include?("update") -%>
+  def update
+    endpoint <%= class_name %>::Operation::Update, <%= class_name %>::Component::Edit
+  end
+
+<% end -%>
+<% if actions.include?("destroy") -%>
+  def destroy
+    endpoint <%= class_name %>::Operation::Destroy
+  end
+<% end -%>
+end

data/lib/generators/tsykvas_rails_template/concept/templates/operation/create.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Operation::Create < ::Base::Operation::Base
+  def perform!(params:, current_user:)
+    <%= singular_var %> = <%= resource_class %>.new
+    authorize! <%= singular_var %>, :create?
+
+    <%= singular_var %>.assign_attributes(<%= singular_var %>_params(params))
+    <%= singular_var %>.save!
+
+    self.model = <%= singular_var %>
+    self.redirect_path = "/<%= url_helper_plural.tr('_', '/') %>/#{<%= singular_var %>.id}"
+    notice(I18n.t("<%= i18n_key %>.create.success"))
+  end
+
+  private
+
+  # For complex forms (virtual attributes, sub-operation calls during
+  # assignment, multi-record submits) promote this into a
+  # <%= class_name %>::Form object. See .claude/docs/forms.md.
+  def <%= singular_var %>_params(params)
+    raise NotImplementedError, <<~MSG
+      Implement <%= class_name %>::Operation::Create#<%= singular_var %>_params.
+
+        params.require(:<%= singular_var %>).permit(:name, :description) # list real attributes
+
+      For complex forms, promote into a <%= class_name %>::Form object
+      instead. See .claude/docs/forms.md.
+    MSG
+  end
+end

data/lib/generators/tsykvas_rails_template/concept/templates/operation/destroy.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Operation::Destroy < ::Base::Operation::Base
+  def perform!(params:, current_user:)
+    <%= singular_var %> = <%= resource_class %>.find(params[:id])
+    authorize! <%= singular_var %>, :destroy?
+    <%= singular_var %>.destroy!
+
+    self.model = <%= singular_var %>
+    self.redirect_path = "/<%= url_helper_plural.tr('_', '/') %>"
+    notice(I18n.t("<%= i18n_key %>.destroy.success"))
+  end
+end

data/lib/generators/tsykvas_rails_template/concept/templates/operation/edit.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Operation::Edit < ::Base::Operation::Base
+  def perform!(params:, current_user:)
+    <%= singular_var %> = <%= resource_class %>.find(params[:id])
+    authorize! <%= singular_var %>, :edit?
+
+    self.model = <%= singular_var %>
+  end
+end

data/lib/generators/tsykvas_rails_template/concept/templates/operation/index.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Operation::Index < ::Base::Operation::Base
+  def perform!(params:, current_user:)
+    <%= plural_var %> = policy_scope(<%= resource_class %>)
+
+    self.model = ::OpenStruct.new(<%= plural_var %>: <%= plural_var %>)
+  end
+end

data/lib/generators/tsykvas_rails_template/concept/templates/operation/new.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Operation::New < ::Base::Operation::Base
+  def perform!(params:, current_user:)
+    <%= singular_var %> = <%= resource_class %>.new
+    authorize! <%= singular_var %>, :new?
+
+    self.model = <%= singular_var %>
+  end
+end

data/lib/generators/tsykvas_rails_template/concept/templates/operation/show.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Operation::Show < ::Base::Operation::Base
+  def perform!(params:, current_user:)
+    <%= singular_var %> = <%= resource_class %>.find(params[:id])
+    authorize! <%= singular_var %>, :show?
+
+    self.model = <%= singular_var %>
+  end
+end

data/lib/generators/tsykvas_rails_template/concept/templates/operation/update.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class <%= class_name %>::Operation::Update < ::Base::Operation::Base
+  def perform!(params:, current_user:)
+    <%= singular_var %> = <%= resource_class %>.find(params[:id])
+    authorize! <%= singular_var %>, :update?
+
+    <%= singular_var %>.assign_attributes(<%= singular_var %>_params(params))
+    <%= singular_var %>.save!
+
+    self.model = <%= singular_var %>
+    self.redirect_path = "/<%= url_helper_plural.tr('_', '/') %>/#{<%= singular_var %>.id}"
+    notice(I18n.t("<%= i18n_key %>.update.success"))
+  end
+
+  private
+
+  # For complex forms (virtual attributes, sub-operation calls during
+  # assignment, multi-record submits) promote this into a
+  # <%= class_name %>::Form object. See .claude/docs/forms.md.
+  def <%= singular_var %>_params(params)
+    raise NotImplementedError, <<~MSG
+      Implement <%= class_name %>::Operation::Update#<%= singular_var %>_params.
+
+        params.require(:<%= singular_var %>).permit(:name, :description) # list real attributes
+
+      For complex forms, promote into a <%= class_name %>::Form object
+      instead. See .claude/docs/forms.md.
+    MSG
+  end
+end