ruby_cms 0.2.1.1 → 1.0.0

data/lib/generators/ruby_cms/install_generator.rb

@@ -1,1159 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-
-module RubyCms
-  module Generators
-    class InstallGenerator < ::Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
-
-      NEXT_STEPS_MESSAGE = <<~TEXT
-
-        ✓ RubyCMS install complete.
-
-        Next steps (if not already done):
-        - rails db:migrate
-        - rails ruby_cms:seed_permissions (includes manage_visitor_errors and manage_analytics)
-        - rails ruby_cms:setup_admin (or: rails ruby_cms:grant_manage_admin email=you@example.com)
-        - To seed content blocks from YAML: add content under content_blocks in config/locales/<locale>.yml, then run rails ruby_cms:content_blocks:seed (or call it from db/seeds.rb).
-
-        Notes:
-        - If the host uses /admin already, remove or change those routes.
-        - Avoid root to: redirect("/admin") — use a real root or ruby_cms.unauthorized_redirect_path.
-        - Review config/initializers/ruby_cms.rb (session, CSP).
-        - RubyCMS admin styles are compiled once on install to app/assets/stylesheets/ruby_cms/admin.css.
-        - Visit /admin (sign in as the admin you configured).
-
-        Tracking:
-        - Visitor errors: Automatically captured via ApplicationController (see /admin/visitor_errors)
-        - Page views (Ahoy): Include RubyCms::PageTracking in your public controllers to track page views
-          Example: class PagesController < ApplicationController; include RubyCms::PageTracking; end
-        - Conversions: Call ahoy.track RubyCms::Analytics::Report::EVENT_CONVERSION, goal: "contact_form"
-          from any controller action (e.g. after a successful form submit). Goal names are free-form strings.
-        - Bot filtering: Set config.ruby_cms.analytics_visit_scope to exclude IPs/bots (see config/initializers/ruby_cms.rb)
-        - Analytics: View visit/event data in Ahoy tables (ahoy_visits, ahoy_events)
-      TEXT
-
-      def run_authentication
-        user_path = Rails.root.join("app/models/user.rb")
-        return if File.exist?(user_path)
-
-        say "ℹ Task authentication: User model not found. " \
-            "Running 'rails g authentication' (Rails 8+).", :cyan
-        @authentication_attempted = true
-        run "bin/rails generate authentication"
-        run "bundle install"
-      rescue StandardError => e
-        say "⚠ Could not run 'rails g authentication': #{e.message}.", :yellow
-        say "   On Rails 8+, run 'rails g authentication' and 'bundle install' manually.", :yellow
-      end
-
-      def verify_auth
-        verify_user_model
-        verify_session_model
-        verify_application_controller
-      end
-
-      def verify_user_model
-        return if defined?(::User)
-
-        message = if @authentication_attempted
-                    "Run 'rails db:migrate' if the authentication generator succeeded."
-                  else
-                    "User model not found. Run 'rails g authentication' before using /admin."
-                  end
-        say "ℹ Task authentication: #{message}", :yellow
-      end
-
-      def verify_session_model
-        return if defined?(::Session)
-
-        say "ℹ Task authentication: Session model not found. " \
-            "The host app should provide authentication.",
-            :yellow
-      end
-
-      def verify_application_controller
-        ac_path = Rails.root.join("app/controllers/application_controller.rb")
-        return unless ac_path.exist?
-
-        content = File.read(ac_path)
-        return if content.include?("include Authentication")
-        return if @authentication_warning_shown
-
-        say "ℹ Task authentication: ApplicationController does not include " \
-            "Authentication. Ensure /admin is protected.",
-            :yellow
-        @authentication_warning_shown = true
-      end
-
-      def create_initializer
-        @detected_pages = detect_page_templates
-        template "ruby_cms.rb", "config/initializers/ruby_cms.rb"
-      end
-
-      def mount_engine
-        route 'mount RubyCms::Engine => "/"'
-      end
-
-      def add_catch_all_route
-        routes_path = Rails.root.join("config/routes.rb")
-        return unless routes_path.exist?
-
-        content = File.read(routes_path)
-        return if content.include?("ruby_cms/errors#not_found")
-
-        # Add catch-all route at the end of the routes block (before final 'end')
-        catch_all = <<~ROUTE
-
-          # RubyCMS: Catch-all route for 404 error tracking (must be LAST)
-          match "*path", to: "ruby_cms/errors#not_found", via: :all,
-                constraints: ->(req) { !req.path.start_with?("/rails/", "/assets/") }
-        ROUTE
-
-        # Insert before the last 'end' in the file
-        gsub_file routes_path, /(\nend)\s*\z/ do
-          "#{catch_all}end\n"
-        end
-        say "✓ Catch-all route: Added for 404 error tracking", :green
-      rescue StandardError => e
-        say "⚠ Catch-all route: Could not add automatically: #{e.message}. " \
-            "Add manually at the END of routes.rb:\n  " \
-            'match "*path", to: "ruby_cms/errors#not_found", via: :all, ' \
-            'constraints: ->(req) { !req.path.start_with?("/rails/", "/assets/") }',
-            :yellow
-      end
-
-      def add_permittable_to_user
-        user_path = Rails.root.join("app/models/user.rb")
-        unless File.exist?(user_path)
-          say "Skipping User: app/models/user.rb not found.", :yellow
-          return
-        end
-
-        return if File.read(user_path).include?("RubyCms::Permittable")
-
-        inject_into_file user_path, after: /class User .*\n/ do
-          "  include RubyCms::Permittable\n"
-        end
-      end
-
-      def add_current_user_to_authentication
-        auth_path = Rails.root.join("app/controllers/concerns/authentication.rb")
-        return unless auth_path.exist?
-        return if File.read(auth_path).include?("def current_user")
-
-        gsub_file auth_path, "    helper_method :authenticated?\n",
-                  "    helper_method :authenticated?, :current_user\n"
-        inject_into_file auth_path, after: "  private\n" do
-          "    def current_user\n      Current.user\n    end\n\n"
-        end
-      end
-
-      def add_visitor_error_capture
-        ac_path = Rails.root.join("app/controllers/application_controller.rb")
-        return unless ac_path.exist?
-
-        content = File.read(ac_path)
-        return if content.include?("RubyCms::VisitorErrorCapture")
-
-        to_inject = "  include RubyCms::VisitorErrorCapture\n"
-        to_inject += "  rescue_from StandardError, with: :handle_visitor_error\n" \
-          unless content.include?("rescue_from StandardError")
-
-        inject_into_file ac_path, after: /class ApplicationController.*\n/ do
-          to_inject
-        end
-        say "✓ Visitor error capture: Added to ApplicationController", :green
-      rescue StandardError => e
-        say "⚠ Visitor error capture: Could not add to ApplicationController: #{e.message}. " \
-            "Add manually: include RubyCms::VisitorErrorCapture and rescue_from StandardError, with: :handle_visitor_error",
-            :yellow
-      end
-
-      def add_page_tracking_to_home_controller
-        home_path = Rails.root.join("app/controllers/home_controller.rb")
-        return unless home_path.exist?
-
-        content = File.read(home_path)
-        return if content.include?("RubyCms::PageTracking")
-
-        inject_into_file home_path, after: /class HomeController.*\n/ do
-          "  include RubyCms::PageTracking\n"
-        end
-
-        say "✓ Page tracking: Added RubyCms::PageTracking to HomeController", :green
-      rescue StandardError => e
-        say "⚠ Page tracking: Could not add to HomeController: #{e.message}. " \
-            "Add manually: include RubyCms::PageTracking",
-            :yellow
-      end
-
-      def copy_fallback_css
-        src_dir = RubyCms::Engine.root.join("app/assets/stylesheets/ruby_cms")
-        dest_dir = Rails.root.join("app/assets/stylesheets/ruby_cms")
-
-        return unless src_dir.exist?
-
-        FileUtils.mkdir_p(dest_dir)
-        copy_admin_css(dest_dir)
-        # Don't copy component files - only the compiled admin.css is needed
-        # copy_components_css(src_dir, dest_dir)
-        say "✓ Task css/copy: Combined component CSS into " \
-            "app/assets/stylesheets/ruby_cms/admin.css", :green
-      rescue StandardError => e
-        say "⚠ Task css/copy: Could not copy CSS files: #{e.message}.", :yellow
-      end
-
-      def create_admin_layout
-        layout_path = Rails.root.join("app/views/layouts/admin.html.erb")
-        return if File.exist?(layout_path)
-
-        template "admin.html.erb", layout_path.to_s
-        say "✓ Layout admin: Created app/views/layouts/admin.html.erb", :green
-      rescue StandardError => e
-        say "⚠ Layout admin: Could not create admin.html.erb: #{e.message}. " \
-            "Create it manually using the RubyCMS template.", :yellow
-      end
-      no_tasks do
-        def copy_admin_css(dest_dir)
-          admin_css_dest = dest_dir.join("admin.css")
-          precompiled_admin_css = RubyCms::Engine.root.join("app/assets/stylesheets/ruby_cms/admin.css")
-          if File.exist?(precompiled_admin_css) && File.size(precompiled_admin_css).to_i.positive?
-            FileUtils.cp(precompiled_admin_css, admin_css_dest)
-            return
-          end
-
-          RubyCms::Engine.compile_admin_css(admin_css_dest)
-          return if File.size(admin_css_dest).to_i > 64
-
-          say "⚠ Task css/copy: Generated admin.css is very small. " \
-              "Ensure RubyCMS ships precompiled CSS at app/assets/stylesheets/ruby_cms/admin.css.",
-              :yellow
-        end
-
-        def copy_components_css(src_dir, dest_dir)
-          components_src_dir = src_dir.join("components")
-          components_dest_dir = dest_dir.join("components")
-          return unless components_src_dir.exist? && components_src_dir.directory?
-
-          FileUtils.mkdir_p(components_dest_dir)
-          Dir.glob(components_src_dir.join("*.css")).each do |src_file|
-            copy_component_css_file(src_file, components_dest_dir)
-          end
-        end
-
-        def copy_component_css_file(src_file, dest_dir)
-          filename = File.basename(src_file)
-          dest_file = dest_dir.join(filename)
-          return if dest_file.exist? && File.mtime(src_file) <= File.mtime(dest_file)
-
-          FileUtils.cp(src_file, dest_file, preserve: true)
-        end
-      end
-
-      def install_ahoy
-        if ahoy_already_installed?
-          say "ℹ Task ahoy: Existing Ahoy setup detected (tables or migrations). Skipping ahoy:install.",
-              :cyan
-          configure_ahoy_server_side_only
-          return
-        end
-
-        say "ℹ Task ahoy: Installing Ahoy for visit/event tracking.", :cyan
-        run "bin/rails generate ahoy:install"
-        add_ahoy_security_fields_migration
-        configure_ahoy_server_side_only
-        say "✓ Task ahoy: Installed Ahoy (visits, events, tracking)", :green
-      rescue StandardError => e
-        say "⚠ Task ahoy: Could not install: #{e.message}. " \
-            "Run 'rails g ahoy:install' manually.",
-            :yellow
-      end
-
-      def install_action_text
-        migrate_dir = Rails.root.join("db/migrate")
-        return unless migrate_dir.directory?
-
-        if action_text_already_installed?(migrate_dir)
-          say "ℹ Task action_text: Existing Action Text setup detected. Skipping action_text:install.",
-              :cyan
-        else
-          say "ℹ Task action_text: Installing Action Text for rich text/image content blocks.", :cyan
-          run "bin/rails action_text:install"
-          say "✓ Task action_text: Installed Action Text", :green
-        end
-
-        configure_action_text_assets
-      rescue StandardError => e
-        say "⚠ Task action_text: Could not install: #{e.message}. Rich text will be disabled.",
-            :yellow
-      end
-
-      no_tasks do
-        def ahoy_already_installed?
-          return true if ahoy_tables_exist?
-
-          migrate_dir = Rails.root.join("db/migrate")
-          return false unless migrate_dir.directory?
-
-          Dir.glob(migrate_dir.join("*.rb").to_s).any? do |f|
-            content = File.read(f)
-            content.include?("ahoy_visits") || content.include?("ahoy_events")
-          end
-        end
-
-        def ahoy_tables_exist?
-          return false unless defined?(ActiveRecord::Base)
-
-          # Calling connection lazily establishes a connection when possible,
-          # so we can detect existing Ahoy tables even before AR reports connected?.
-          c = ActiveRecord::Base.connection
-          c.data_source_exists?("ahoy_visits") || c.data_source_exists?("ahoy_events")
-        rescue ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError,
-               ActiveRecord::StatementInvalid
-          false
-        end
-
-        def add_ahoy_security_fields_migration
-          run "bin/rails generate migration AddRubyCmsFieldsToAhoyEvents"
-          migration_file = Rails.root.glob("db/migrate/*add_ruby_cms*fields*.rb").max_by(&:basename)
-          return unless migration_file
-
-          migration_file = migration_file.to_s
-          content = <<~RUBY
-            class AddRubyCmsFieldsToAhoyEvents < ActiveRecord::Migration[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]
-              def change
-                return unless table_exists?(:ahoy_events)
-
-                add_column :ahoy_events, :page_name, :string unless column_exists?(:ahoy_events, :page_name)
-                add_column :ahoy_events, :ip_address, :string unless column_exists?(:ahoy_events, :ip_address)
-                add_column :ahoy_events, :request_path, :string unless column_exists?(:ahoy_events, :request_path)
-                add_column :ahoy_events, :user_agent, :text unless column_exists?(:ahoy_events, :user_agent)
-                add_column :ahoy_events, :description, :text unless column_exists?(:ahoy_events, :description)
-
-                add_index :ahoy_events, :page_name, if_not_exists: true
-                add_index :ahoy_events, :ip_address, if_not_exists: true
-                add_index :ahoy_events, :request_path, if_not_exists: true
-                add_index :ahoy_events, [:name, :page_name], if_not_exists: true
-                add_index :ahoy_events, [:name, :request_path], if_not_exists: true
-              end
-            end
-          RUBY
-          File.write(migration_file, content)
-        end
-
-        def configure_ahoy_server_side_only
-          ahoy_path = Rails.root.join("config/initializers/ahoy.rb")
-          content = if ahoy_path.exist?
-                      File.read(ahoy_path)
-                    else
-                      <<~RUBY
-                        # Configure Ahoy
-                      RUBY
-                    end
-
-          # Ensure Ahoy is loaded before any references (fixes NameError when
-          # ahoy_matey loads after initializers)
-          content = %(require "ahoy_matey"\n\n#{content}) unless content.include?('require "ahoy_matey"')
-
-          # Ensure a default Ahoy store class exists.
-          unless content.match?(/class\s+Ahoy::Store\s*<\s*Ahoy::DatabaseStore/)
-            content += <<~RUBY
-
-              class Ahoy::Store < Ahoy::DatabaseStore
-              end
-            RUBY
-          end
-
-          if content.include?("Ahoy.api = false")
-            File.write(ahoy_path, content)
-            return
-          end
-
-          append = "\n\n# RubyCMS: server-side tracking only (no JavaScript)\nAhoy.api = false\nAhoy.geocode = false\n"
-          File.write(ahoy_path, "#{content}#{append}")
-        end
-
-        def action_text_already_installed?(migrate_dir)
-          return true if active_storage_tables_exist? || action_text_tables_exist?
-
-          existing = Dir.glob(migrate_dir.join("*.rb").to_s).join("\n")
-          existing.include?("create_action_text_rich_texts") ||
-            existing.include?("create_active_storage_tables")
-        end
-
-        def active_storage_tables_exist?
-          return false unless defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
-
-          c = ActiveRecord::Base.connection
-          c.data_source_exists?("active_storage_blobs") &&
-            c.data_source_exists?("active_storage_attachments")
-        rescue ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError
-          false
-        end
-
-        def action_text_tables_exist?
-          return false unless defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
-
-          ActiveRecord::Base.connection.data_source_exists?("action_text_rich_texts")
-        rescue ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError
-          false
-        end
-
-        def configure_action_text_assets
-          add_action_text_importmap_pins
-          add_action_text_imports_to_admin_entrypoint
-        end
-
-        def add_action_text_importmap_pins
-          importmap_path = Rails.root.join("config/importmap.rb")
-          return unless File.exist?(importmap_path)
-
-          content = File.read(importmap_path)
-          lines_to_add = []
-          lines_to_add << %(pin "trix") unless content.include?('pin "trix"')
-          lines_to_add << %(pin "@rails/actiontext", to: "actiontext.esm.js") unless content.include?('pin "@rails/actiontext"')
-          return if lines_to_add.empty?
-
-          inject_into_file importmap_path.to_s, before: /^end/ do
-            "\n  # RubyCMS rich text (Action Text + Trix)\n  #{lines_to_add.join("\n  ")}\n"
-          end
-          say "✓ Task action_text/importmap: Added trix/actiontext pins to importmap.rb.", :green
-        rescue StandardError => e
-          say "⚠ Task action_text/importmap: Could not add pins: #{e.message}. " \
-              "Add pins for trix and @rails/actiontext manually.",
-              :yellow
-        end
-
-        def add_action_text_imports_to_admin_entrypoint
-          admin_js_path = Rails.root.join("app/javascript/admin.js")
-          content = File.exist?(admin_js_path) ? File.read(admin_js_path) : ""
-
-          lines_to_add = []
-          lines_to_add << %(import "trix") unless content.include?('import "trix"') || content.include?("import 'trix'")
-          unless content.include?('import "@rails/actiontext"') ||
-                 content.include?("import '@rails/actiontext'")
-            lines_to_add << %(import "@rails/actiontext")
-          end
-          return if lines_to_add.empty?
-
-          if File.exist?(admin_js_path)
-            append_to_file admin_js_path.to_s, "\n#{lines_to_add.join("\n")}\n"
-            say "✓ Task action_text/js: Added Action Text imports to app/javascript/admin.js.", :green
-          else
-            content = <<~JS
-              // RubyCMS admin entrypoint
-              import "trix"
-              import "@rails/actiontext"
-            JS
-            File.write(admin_js_path, content)
-            say "✓ Task action_text/js: Created app/javascript/admin.js with Action Text imports.", :green
-          end
-        rescue StandardError => e
-          say "⚠ Task action_text/js: Could not update admin.js: #{e.message}. " \
-              "Import trix and @rails/actiontext manually.",
-              :yellow
-        end
-      end
-
-      def install_tailwind
-        gemfile = Rails.root.join("Gemfile")
-        tailwind_css = detect_tailwind_entry_css_path
-
-        install_tailwind_if_needed(gemfile, tailwind_css)
-        configure_tailwind(tailwind_css)
-      rescue StandardError => e
-        say "⚠ Task tailwind: Could not install: #{e.message}. Add tailwindcss-rails manually.",
-            :yellow
-      end
-
-      no_tasks do
-        def detect_tailwind_entry_css_path
-          candidates = [
-            Rails.root.join("app/assets/tailwind/application.css"),
-            Rails.root.join("app/assets/stylesheets/application.tailwind.css"),
-            Rails.root.join("app/assets/stylesheets/tailwind.css")
-          ]
-          candidates.find(&:exist?) || candidates.first
-        end
-
-        def install_tailwind_if_needed(gemfile, tailwind_css)
-          return if File.exist?(tailwind_css)
-
-          if File.read(gemfile).include?("tailwindcss-rails")
-            say "ℹ Task tailwind: Tailwind CSS gem found; running tailwindcss:install.", :cyan
-          else
-            say "ℹ Task tailwind: Adding tailwindcss-rails for admin styling.", :cyan
-            run "bundle add tailwindcss-rails"
-          end
-          run "bin/rails tailwindcss:install"
-          say "✓ Task tailwind: Installed Tailwind CSS", :green
-        end
-
-        def configure_tailwind(tailwind_css)
-          ensure_ruby_cms_tailwind_safelist_partial
-          run "bin/rails tailwindcss:build" if File.exist?(tailwind_css)
-          # Importmap pins are provided by the engine via `ruby_cms/config/importmap.rb`.
-          add_importmap_pins
-          add_stimulus_registration
-        end
-      end
-
-      def install_ruby_ui
-        gemfile = Rails.root.join("Gemfile")
-        gemfile_content = File.read(gemfile)
-        return if ruby_ui_in_gemfile?(gemfile_content)
-
-        add_ruby_ui_gem
-      rescue StandardError => e
-        say "⚠ Task ruby_ui: Could not add: #{e.message}. " \
-            "Run 'bundle add ruby_ui --group development --require false' manually.",
-            :yellow
-        nil
-      end
-
-      def run_ruby_ui_install
-        gemfile = Rails.root.join("Gemfile")
-        gemfile_content = File.read(gemfile)
-        return unless ruby_ui_in_gemfile?(gemfile_content)
-        return if ruby_ui_already_installed?
-
-        install_ruby_ui_generator
-      end
-
-      no_tasks do
-        def ruby_ui_in_gemfile?(content)
-          content.include?("ruby_ui") || content.include?("rails_ui")
-        end
-
-        def add_ruby_ui_gem
-          say "ℹ Task ruby_ui: Adding ruby_ui to Gemfile.", :cyan
-          run "bundle add ruby_ui --group development --require false"
-          run "bundle install"
-          say "✓ Task ruby_ui: Added ruby_ui to Gemfile", :green
-        end
-
-        def ruby_ui_already_installed?
-          ruby_ui_initializer = Rails.root.join("config/initializers/ruby_ui.rb")
-          ruby_ui_base = Rails.root.join("app/components/ruby_ui/base.rb")
-          if File.exist?(ruby_ui_initializer) || File.exist?(ruby_ui_base)
-            say "ℹ Task ruby_ui:install: ruby_ui is already installed. Skipping.", :cyan
-            return true
-          end
-          false
-        end
-
-        def install_ruby_ui_generator
-          say "ℹ Task ruby_ui:install: Running ruby_ui:install generator.", :cyan
-          try_ruby_ui_install
-        rescue StandardError => e
-          say "⚠ Task ruby_ui:install: Could not find generator: #{e.message}. " \
-              "Run 'rails g ruby_ui:install' manually.",
-              :yellow
-        end
-
-        def try_ruby_ui_install
-          run "bin/rails generate ruby_ui:install"
-          say "✓ Task ruby_ui:install: Installed ruby_ui", :green
-        rescue StandardError
-          try_rails_ui_install
-        end
-
-        def try_rails_ui_install
-          say "ℹ Task ruby_ui:install: Using rails_ui:install (ruby_ui alias).", :cyan
-          run "bin/rails generate rails_ui:install"
-          say "✓ Task ruby_ui:install: Installed rails_ui", :green
-        end
-
-        def add_ruby_ui_to_application_helper
-          helper_path = Rails.root.join("app/helpers/application_helper.rb")
-          return unless File.exist?(helper_path)
-
-          content = File.read(helper_path)
-          return if ruby_ui_already_included?(content)
-
-          inject_ruby_ui_include(helper_path)
-        rescue StandardError => e
-          say "⚠ Task ruby_ui/helper: Could not add RubyUI: #{e.message}. " \
-              "Add 'include RubyUI' manually.",
-              :yellow
-        end
-
-        def ruby_ui_already_included?(content)
-          content.include?("include RubyUI") || content.include?("include RubyUi")
-        end
-
-        def inject_ruby_ui_include(helper_path)
-          say "✓ Task ruby_ui/helper: Added include RubyUI to ApplicationHelper.", :green
-          inject_into_file helper_path.to_s, after: /module ApplicationHelper\n/ do
-            "  include RubyUI\n"
-          end
-        end
-
-        def generate_ruby_ui_components
-          # Skip component generation - page builder removed.
-          # Generate manually: rails g ruby_ui:component ComponentName
-          say "ℹ Task ruby_ui/components: Skipping automatic component generation " \
-              "(page builder removed). " \
-              "Generate components manually if needed: rails g ruby_ui:component ComponentName",
-              :cyan
-        end
-      end
-
-      # Directories to skip when scanning for page templates
-      SKIP_VIEW_DIRS = %w[layouts shared mailers components admin].freeze
-
-      # NOTE: Rails generators are Thor groups; private methods can still be
-      # treated as "tasks" unless wrapped in `no_tasks`.
-      no_tasks do
-        def detect_page_templates
-          views_dir = Rails.root.join("app/views")
-          return {} unless Dir.exist?(views_dir)
-
-          pages = {}
-          views_base = views_dir.to_s
-          scan_for_templates(views_dir, pages, views_base)
-          log_detected_pages(pages) if pages.any?
-          pages
-        rescue StandardError => e
-          say "⚠ Task pages: Could not scan for page templates: #{e.message}.", :yellow
-          {}
-        end
-
-        def scan_for_templates(dir_path, pages, views_base, relative_path="")
-          # Find all template files in this directory
-          Dir.glob(File.join(dir_path, "*.{html.erb,html.haml,html.slim}")).each do |template_file|
-            base_name = File.basename(template_file, ".*")
-            base_name = File.basename(base_name, ".*") # Remove .html extension
-
-            # Skip partials
-            next if base_name.start_with?("_")
-            # Skip admin pages
-            next if relative_path.start_with?("admin") || relative_path == "admin"
-
-            # Build template path relative to app/views
-            if relative_path.empty?
-              template_path = base_name
-              page_key = base_name
-            elsif base_name == "index"
-              page_key = relative_path.split("/").last
-              template_path = "#{relative_path}/index"
-            # pages/index.html.erb -> "pages" => "pages/index"
-            else
-              # pages/home.html.erb -> "home" => "pages/home"
-              page_key = base_name
-              template_path = "#{relative_path}/#{base_name}"
-            end
-
-            pages[page_key] = template_path
-          end
-
-          # Recursively scan subdirectories (skip common non-page dirs, limit depth)
-          Dir.glob(File.join(dir_path, "*")).each do |path|
-            next unless File.directory?(path)
-
-            dir_name = File.basename(path)
-            # Skip admin directories and common non-page directories
-            next if SKIP_VIEW_DIRS.include?(dir_name)
-            # Skip if we're already in an admin path
-            next if relative_path.start_with?("admin")
-
-            # Limit depth to 2 levels (e.g., app/views/pages/home is OK, but not deeper)
-            depth = relative_path.empty? ? 1 : relative_path.split("/").length + 1
-            next if depth > 2
-
-            new_relative_path = relative_path.empty? ? dir_name : "#{relative_path}/#{dir_name}"
-            scan_for_templates(path, pages, views_base, new_relative_path)
-          end
-        end
-        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-
-        def log_detected_pages(pages)
-          say "✓ Task pages: Detected #{pages.size} page template(s): " \
-              "#{pages.keys.join(', ')}", :green
-        end
-
-        def add_importmap_pins
-          importmap_path = Rails.root.join("config/importmap.rb")
-          return unless File.exist?(importmap_path)
-
-          content = File.read(importmap_path)
-          gem_js_path = calculate_gem_js_path
-          return if importmap_already_configured?(content, gem_js_path)
-
-          inject_importmap_pins(importmap_path, gem_js_path)
-        rescue StandardError => e
-          say "⚠ Task importmap: Could not add pins: #{e.message}. " \
-              "Add manually to config/importmap.rb.",
-              :yellow
-        end
-
-        def calculate_gem_js_path
-          RubyCms::Engine.root.join("app/javascript").relative_path_from(Rails.root).to_s
-        end
-
-        def importmap_already_configured?(content, gem_js_path)
-          pin_pattern = %(pin_all_from "#{gem_js_path}/controllers", under: "controllers")
-          content.include?("RubyCMS Stimulus controllers") || content.include?(pin_pattern)
-        end
-
-        def inject_importmap_pins(importmap_path, gem_js_path)
-          pin_line = %(pin_all_from "#{gem_js_path}/controllers", under: "controllers")
-          alias_line = %(pin "ruby_cms", to: "controllers/ruby_cms/index.js", preload: true)
-          inject_into_file importmap_path.to_s, before: /^end/ do
-            "\n  # RubyCMS Stimulus controllers\n  #{pin_line}\n  #{alias_line}\n"
-          end
-          say "✓ Task importmap: Added RubyCMS controllers to importmap.rb.", :green
-        end
-
-        def add_stimulus_registration
-          controllers_app_path = Rails.root.join("app/javascript/controllers/application.js")
-          return handle_missing_stimulus_file unless File.exist?(controllers_app_path)
-
-          content = File.read(controllers_app_path)
-          unless stimulus_already_exposed?(content)
-            expose_stimulus_application(controllers_app_path,
-                                        content)
-          end
-          import_rubycms_controllers(controllers_app_path, content)
-          cleanup_old_registration_code
-        end
-
-        def handle_missing_stimulus_file
-          say "⚠ Task stimulus: Could not find app/javascript/controllers/application.js. " \
-              "RubyCMS controllers may need manual setup.",
-              :yellow
-        end
-
-        def stimulus_already_exposed?(content)
-          if content.include?("window.Stimulus") || content.include?("window.application")
-            say "ℹ Task stimulus: Stimulus application is already exposed on window.", :cyan
-            return true
-          end
-          false
-        end
-
-        def expose_stimulus_application(controllers_app_path, content)
-          return unless stimulus_application_startable?(content)
-
-          if stimulus_const_assignment?(content)
-            add_stimulus_const_pattern(controllers_app_path)
-          elsif stimulus_var_assignment?(content)
-            add_stimulus_var_pattern(controllers_app_path)
-          else
-            warn_manual_stimulus_exposure
-          end
-        end
-
-        def stimulus_application_startable?(content)
-          content.include?("const application") && content.include?("Application.start")
-        end
-
-        def stimulus_const_assignment?(content)
-          content.match?(/const\s+application\s*=\s*Application\.start\(\)/)
-        end
-
-        def stimulus_var_assignment?(content)
-          content.match?(/application\s*=\s*Application\.start\(\)/)
-        end
-
-        def warn_manual_stimulus_exposure
-          say "⚠ Task stimulus: Could not automatically expose. " \
-              "Manually add 'window.Stimulus = application'.",
-              :yellow
-        end
-
-        def add_stimulus_const_pattern(controllers_app_path)
-          gsub_file controllers_app_path.to_s,
-                    /const\s+application\s*=\s*Application\.start\(\)/,
-                    "const application = Application.start()\nwindow.Stimulus = application"
-          say_stimulus_added
-        end
-
-        def add_stimulus_var_pattern(controllers_app_path)
-          gsub_file controllers_app_path.to_s,
-                    /application\s*=\s*Application\.start\(\)/,
-                    "application = Application.start()\nwindow.Stimulus = application"
-          say_stimulus_added
-        end
-
-        def say_stimulus_added
-          say "✓ Task stimulus: Added window.Stimulus = application to " \
-              "controllers/application.js.",
-              :green
-        end
-
-        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
-        def import_rubycms_controllers(controllers_app_path, content)
-          # Re-read content in case it was modified by expose_stimulus_application
-          content = File.read(controllers_app_path) if File.exist?(controllers_app_path)
-
-          return if content.include?('import "ruby_cms"') || content.include?("import 'ruby_cms'")
-          return if content.include?("registerRubyCmsControllers")
-
-          # Try to add after the Stimulus import (most common pattern)
-          stimulus_import_pattern = %r{import\s+.*@hotwired/stimulus.*$}
-          if content.match?(stimulus_import_pattern)
-            inject_into_file controllers_app_path.to_s,
-                             after: stimulus_import_pattern,
-                             verbose: false do
-              "\nimport \"ruby_cms\""
-            end
-            say "✓ Task stimulus: Added RubyCMS controllers import.", :green
-            return
-          end
-
-          # Try to add after any import statement
-          first_import_pattern = /^import\s+.*$/m
-          if content.match?(first_import_pattern)
-            inject_into_file controllers_app_path.to_s,
-                             after: first_import_pattern,
-                             verbose: false do
-              "\nimport \"ruby_cms\""
-            end
-            say "✓ Task stimulus: Added RubyCMS controllers import.", :green
-            return
-          end
-
-          # Add at the very top if no imports found
-          prepend_to_file controllers_app_path.to_s, "import \"ruby_cms\"\n"
-          say "✓ Task stimulus: Added RubyCMS controllers import.", :green
-        rescue StandardError => e
-          say "⚠ Task stimulus: Could not add RubyCMS import: #{e.message}. " \
-              "Add 'import \"ruby_cms\"' manually to controllers/application.js.",
-              :yellow
-        end
-        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
-
-        def cleanup_old_registration_code
-          js_files = find_js_files_to_check
-          js_files.each {|js_file| cleanup_file_registration(js_file) }
-        rescue StandardError
-          # Silent fail - not critical
-        end
-
-        def find_js_files_to_check
-          [
-            Rails.root.join("app/javascript/application.js"),
-            Rails.root.join("app/javascript/index.js"),
-            Rails.root.join("app/javascript/entrypoints/application.js")
-          ].select(&:exist?)
-        end
-
-        def cleanup_file_registration(js_file)
-          content = File.read(js_file)
-          return unless needs_cleanup?(content)
-
-          new_content = remove_registration_lines(content)
-          return if new_content == content
-
-          File.write(js_file, new_content)
-          say "✓ Task stimulus: Removed old manual registration from #{js_file.basename}. " \
-              "Auto-registration handles this now.",
-              :green
-        end
-
-        def needs_cleanup?(content)
-          content.include?("registerRubyCmsControllers(application)") &&
-            content.exclude?("if (typeof application !== \"undefined\")")
-        end
-
-        def remove_registration_lines(content)
-          lines = content.split("\n")
-          lines.reject do |line|
-            line.strip.include?("registerRubyCmsControllers(application)") ||
-              (line.strip.start_with?("import") && line.include?("registerRubyCmsControllers") &&
-                line.include?("ruby_cms"))
-          end.join("\n")
-        end
-
-        # Keep Tailwind generation fast without scanning the gem path:
-        # generate a host-app safelist partial from RubyCMS classes.
-        def ensure_ruby_cms_tailwind_safelist_partial
-          classes = ruby_cms_tailwind_classes
-          return if classes.empty?
-
-          safelist_path = Rails.root.join("app/views/ruby_cms/_tailwind_safelist.html.erb")
-          FileUtils.mkdir_p(safelist_path.dirname)
-          File.write(safelist_path, build_tailwind_safelist_partial(classes))
-          say "✓ Task tailwind/safelist: Generated app/views/ruby_cms/_tailwind_safelist.html.erb.",
-              :green
-        rescue StandardError => e
-          say "⚠ Task tailwind/safelist: Could not generate safelist partial: #{e.message}.", :yellow
-        end
-
-        def ruby_cms_tailwind_classes
-          patterns = [
-            RubyCms::Engine.root.join("app/views/**/*.erb"),
-            RubyCms::Engine.root.join("app/components/**/*.rb"),
-            RubyCms::Engine.root.join("app/helpers/**/*.rb"),
-            RubyCms::Engine.root.join("app/javascript/**/*.js")
-          ]
-
-          tokens = Set.new
-          patterns.each do |pattern|
-            Dir.glob(pattern.to_s).each do |path|
-              extract_tailwind_tokens_from(File.read(path), tokens)
-            end
-          end
-
-          tokens.to_a.sort
-        end
-
-        def extract_tailwind_tokens_from(content, tokens)
-          class_strings(content).each do |raw|
-            add_tailwind_tokens(raw, tokens)
-
-            # Also include classes from interpolated branches:
-            # "#{active ? 'text-blue-600' : 'text-gray-600'}"
-            raw.scan(/['"]([^'"]+)['"]/).flatten.each do |inner|
-              add_tailwind_tokens(inner, tokens)
-            end
-          end
-        end
-
-        def class_strings(content)
-          regexes = [
-            /class\s*=\s*"([^"]+)"/m,
-            /class\s*=\s*'([^']+)'/m,
-            /class:\s*"([^"]+)"/m,
-            /class:\s*'([^']+)'/m
-          ]
-
-          regexes.flat_map { |regex| content.scan(regex).flatten.compact }
-        end
-
-        def add_tailwind_tokens(value, tokens)
-          value
-            .gsub(/\#\{[^}]*\}/, " ")
-            .split(/\s+/)
-            .map(&:strip)
-            .reject(&:empty?)
-            .each do |token|
-              next unless token.match?(/\A[-!:\[\]\/.%a-zA-Z0-9_]+\z/)
-              next unless token.match?(/[A-Za-z]/)
-              next if token.start_with?("http", "/", "#")
-
-              tokens << token
-            end
-        end
-
-        def build_tailwind_safelist_partial(classes)
-          grouped_classes = classes.each_slice(20).map { |group| group.join(" ") }.join("\n  ")
-
-          <<~ERB
-            <%# RubyCMS Tailwind safelist (auto-generated by ruby_cms:install). %>
-            <%# Keep this file so Tailwind picks up classes used inside the RubyCMS gem. %>
-            <div class="hidden #{grouped_classes}"></div>
-          ERB
-        end
-
-        # RubyCMS admin styles are precompiled to app/assets/stylesheets/ruby_cms/admin.css.
-        # Legacy cleanup helpers kept for backward compatibility.
-        def remove_ruby_cms_tailwind_source(tailwind_css_path)
-          return unless valid_tailwind_source_path?(tailwind_css_path)
-
-          content = File.read(tailwind_css_path)
-          cleaned_content = remove_legacy_ruby_cms_tailwind_sources(content)
-          return if cleaned_content == content
-
-          File.write(tailwind_css_path, cleaned_content)
-          say_tailwind_source_cleaned
-        rescue StandardError => e
-          say_tailwind_source_clean_failed(e)
-        end
-
-        # Remove RubyCMS content globs from Tailwind v3 config as well.
-        def remove_ruby_cms_tailwind_content_paths
-          config_path = Rails.root.join("config/tailwind.config.js")
-          return unless File.exist?(config_path)
-
-          content = File.read(config_path)
-          cleaned = content.gsub(/^\s*["']?[^"'\n]*ruby_cms[^"'\n]*["']?,?\s*$\n?/i, "")
-          return if cleaned == content
-
-          File.write(config_path, cleaned)
-          say "✓ Task tailwind/content: Removed RubyCMS paths from tailwind.config.js.", :green
-        rescue StandardError => e
-          say "⚠ Task tailwind/content: Could not clean tailwind.config.js: #{e.message}.", :yellow
-        end
-
-        def remove_legacy_ruby_cms_tailwind_sources(content)
-          content
-            .gsub(%r{^\s*/\*\s*Include RubyCMS views/components so Tailwind finds utility classes\.\s*\*/\s*$\n?}, "")
-            .gsub(/^\s*@source\s+"[^"\n]*ruby_cms[^"\n]*";\s*$\n?/i, "")
-        end
-
-        def valid_tailwind_source_path?(tailwind_css_path)
-          tailwind_css_path.to_s.present? && File.exist?(tailwind_css_path)
-        end
-
-        def say_tailwind_source_cleaned
-          say "✓ Task tailwind/source: Removed RubyCMS @source paths from tailwind entry CSS.",
-              :green
-        end
-
-        def say_tailwind_source_clean_failed(error)
-          say "⚠ Task tailwind/source: Could not clean @source lines: #{error.message}. " \
-              "Check tailwind/application.css manually.",
-              :yellow
-        end
-      end
-
-      def run_migrate
-        say "ℹ Task db:migrate: Running db:migrate.", :cyan
-        success = run("bin/rails db:migrate")
-        raise "db:migrate failed" unless success
-
-        say "✓ Task db:migrate: Completed", :green
-      rescue StandardError => e
-        say "⚠ Task db:migrate: Failed: #{e.message}. Run rails db:create db:migrate if needed.",
-            :yellow
-      end
-
-      def run_seed_permissions
-        say "ℹ Task permissions: Seeding RubyCMS permissions.", :cyan
-        success = seed_permissions_via_open3
-        say_seed_permissions_outcome(success)
-      rescue StandardError => e
-        say_seed_permissions_error(e)
-      end
-
-      def run_setup_admin
-        return if skip_setup_admin_due_to_existing_admin?
-        return unless setup_admin_tty?
-
-        run_setup_admin_task
-      rescue StandardError => e
-        say_setup_admin_error(e)
-      end
-
-      no_tasks do
-        def seed_permissions_via_open3
-          require "open3"
-
-          _stdin, stdout, stderr, wait_thr = open3_seed_permissions_process
-          stderr_thread = stream_seed_permissions_stderr(stderr)
-          stdout_thread = stream_seed_permissions_stdout(stdout)
-
-          success = wait_thr.value.success?
-          stderr_thread.join
-          stdout_thread.join
-          close_seed_permissions_streams(stdout, stderr)
-          success
-        end
-
-        def open3_seed_permissions_process
-          Open3.popen3(*seed_permissions_command, chdir: Rails.root.to_s)
-        end
-
-        def seed_permissions_command
-          # Use argv form to avoid invoking a shell.
-          %w[bin/rails ruby_cms:seed_permissions ruby_cms:import_initializer_settings]
-        end
-
-        def stream_seed_permissions_stderr(stderr)
-          Thread.new do
-            stderr.each_line do |line|
-              $stderr.print line unless line.include?("already initialized constant")
-            end
-          end
-        end
-
-        def stream_seed_permissions_stdout(stdout)
-          Thread.new do
-            stdout.each_line {|line| $stdout.print line }
-          end
-        end
-
-        def close_seed_permissions_streams(stdout, stderr)
-          stdout.close
-          stderr.close
-        end
-
-        def say_seed_permissions_outcome(success)
-          if success
-            say "✓ Task permissions: Seeded RubyCMS permissions", :green
-          else
-            say "⚠ Task permissions: Could not seed. " \
-                "Run 'rails ruby_cms:seed_permissions' manually.",
-                :yellow
-          end
-        end
-
-        def say_seed_permissions_error(error)
-          say "⚠ Task permissions: Could not seed: #{error.message}. " \
-              "Run 'rails ruby_cms:seed_permissions' manually.",
-              :yellow
-        end
-
-        def skip_setup_admin_due_to_existing_admin?
-          return false unless user_with_admin_permissions_exists?
-
-          say "ℹ Task setup_admin: User with admin permissions already exists. " \
-              "Skipping setup_admin.",
-              :cyan
-          true
-        end
-
-        def setup_admin_tty?
-          return true if $stdin.tty?
-
-          say "ℹ Task setup_admin: Skipping interactive setup (non-TTY). " \
-              "Run: rails ruby_cms:setup_admin",
-              :yellow
-          false
-        end
-
-        def run_setup_admin_task
-          say "ℹ Task setup_admin: Running setup_admin (create or pick first admin).", :cyan
-          run "bin/rails ruby_cms:setup_admin"
-          say "✓ Task setup_admin: Completed", :green
-        end
-
-        def say_setup_admin_error(error)
-          say "⚠ Task setup_admin: Failed or skipped: #{error.message}. " \
-              "Run: rails ruby_cms:setup_admin",
-              :yellow
-        end
-
-        def user_with_admin_permissions_exists? # rubocop:disable Metrics/MethodLength
-          return false unless defined?(::User)
-
-          begin
-            # Ensure permissions exist first
-            RubyCms::Permission.ensure_defaults!
-
-            # Check if any user has ALL required admin permissions
-            required_keys = %w[
-              manage_admin
-              manage_permissions
-              manage_content_blocks
-              manage_visitor_errors
-              manage_analytics
-            ]
-            required_permission_ids = RubyCms::Permission.where(key: required_keys).pluck(:id)
-            return false if required_permission_ids.size != required_keys.size
-
-            # Find users who have all required permissions
-            user_ids_with_all_perms = RubyCms::UserPermission
-                                      .where(permission_id: required_permission_ids)
-                                      .group(:user_id)
-                                      .having("COUNT(DISTINCT permission_id) = ?", required_keys.size)
-                                      .pluck(:user_id)
-
-            user_ids_with_all_perms.any?
-          rescue StandardError
-            # If there's an error (e.g., tables don't exist yet), assume no admin exists
-            false
-          end
-        end
-      end
-
-      def show_next_steps
-        say NEXT_STEPS_MESSAGE, :green
-      end
-    end
-  end
-end