opinionated_rails 0.1.4

data/lib/opinionated_rails/steps/addons/secrets_handling_step.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  module Steps
+    module Addons
+      class SecretsHandlingStep < Step
+        def self.id = :secrets_handling
+        def self.tier = :addon
+        def self.needs = []
+        def self.summary = "Configure secrets handling"
+        def self.description = "Chooses Rails encrypted credentials or dotenv for managing secrets."
+        def self.prompts = "Secrets handling: Rails credentials or dotenv (default: Rails credentials)"
+
+        DOTENV_RAILS_VERSION = "3.2.0".freeze
+
+        ENV_EXAMPLE_HEADER = <<~ENV
+          # Copy this file to .env and fill in real values locally.
+          # .env is gitignored; this file (.env.example) is committed with placeholders only.
+        ENV
+
+        ENV_GLOB_PATTERNS = %w[ .env* /.env* ].freeze
+        ENV_IGNORE_PATTERNS = (%w[ .env /.env ] + ENV_GLOB_PATTERNS).freeze
+        ENV_EXAMPLE_UNIGNORE = %w[ !.env.example !/.env.example ].freeze
+
+        def if_condition(_context) = true
+
+        def prompt(context)
+          shell = context.shell
+          shell.say("Choose how secrets are handled:")
+          shell.say("  1. Rails credentials (default)")
+          shell.say("  2. dotenv")
+
+          choice = shell.ask("Secrets handling (default: Rails credentials):").to_s.strip
+          choice = "1" if choice.empty?
+
+          loop do
+            case choice.downcase
+            when "rails credentials", "rails_credentials", "1"
+              context.answer(:secrets_handling, :rails_credentials)
+              break
+            when "dotenv", "2"
+              context.answer(:secrets_handling, :dotenv)
+              break
+            else
+              shell.say("Invalid. Enter 'Rails credentials', 'dotenv', 1, or 2.", :red)
+              choice = shell.ask("Secrets handling (default: Rails credentials):").to_s.strip
+              choice = "1" if choice.empty?
+            end
+          end
+        end
+
+        def generate(context)
+          strategy = context.get(:secrets_handling) || :rails_credentials
+
+          case strategy
+          when :dotenv
+            install_dotenv(context)
+          else
+            check_rails_credentials(context)
+          end
+
+          context.set_output(:secrets_handling, { secrets_handling: strategy })
+        end
+
+        def outputs(context)
+          context.output(:secrets_handling)
+        end
+
+        private
+
+        def check_rails_credentials(context)
+          master_key = File.join(context.app_path, "config/master.key")
+          credentials = File.join(context.app_path, "config/credentials.yml.enc")
+          return if File.exist?(master_key) && File.exist?(credentials)
+
+          context.shell.say(
+            "Warning: config/master.key or config/credentials.yml.enc is missing — Rails credentials may not work as expected.",
+            :yellow
+          )
+        end
+
+        def install_dotenv(context)
+          add_dev_test_group_gem(context, "gem \"dotenv-rails\", \"#{DOTENV_RAILS_VERSION}\"")
+          write_env_example(context)
+          gitignore_dotenv(context)
+        end
+
+        def write_env_example(context)
+          path = File.join(context.app_path, ".env.example")
+          return if File.exist?(path)
+
+          File.write(path, ENV_EXAMPLE_HEADER)
+        end
+
+        def gitignore_dotenv(context)
+          path = File.join(context.app_path, ".gitignore")
+          return unless File.exist?(path)
+
+          content = File.read(path)
+          patterns = content.lines.map(&:strip)
+          additions = []
+          additions << ".env" unless patterns.intersect?(ENV_IGNORE_PATTERNS)
+          # A glob like `.env*` would also hide the committed template.
+          if patterns.intersect?(ENV_GLOB_PATTERNS) && !patterns.intersect?(ENV_EXAMPLE_UNIGNORE)
+            additions << "!/.env.example"
+          end
+          return if additions.empty?
+
+          File.open(path, "a") do |f|
+            f.print("\n") unless content.empty? || content.end_with?("\n")
+            additions.each { |line| f.puts(line) }
+          end
+        end
+
+        def add_dev_test_group_gem(context, gem_line)
+          gemfile_path = File.join(context.app_path, "Gemfile")
+          return unless File.exist?(gemfile_path)
+
+          content = File.read(gemfile_path)
+          return if content.include?(gem_line)
+
+          lines = content.lines
+          group_start = lines.index { |line| line.strip == "group :development, :test do" }
+
+          if group_start
+            end_index = (group_start + 1...lines.size).find { |i| lines[i].strip == "end" }
+            lines.insert(end_index, "  #{gem_line}\n")
+          else
+            lines << "\n" unless lines.last.nil? || lines.last.end_with?("\n")
+            lines << "\ngroup :development, :test do\n  #{gem_line}\nend\n"
+          end
+
+          File.write(gemfile_path, lines.join)
+        end
+      end
+    end
+  end
+end

data/lib/opinionated_rails/steps/addons/services_step.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  module Steps
+    module Addons
+      class ServicesStep < Step
+        def self.id = :services
+        def self.tier = :addon
+        def self.needs = []
+        def self.summary = "Add an application service architecture"
+        def self.description = "Installs an ApplicationService base class and an in-house Result object."
+        def self.prompts = "Add an application service architecture? (default: no)"
+
+        TEMPLATES_DIR = File.expand_path("../../templates/services", __dir__)
+
+        FILES = {
+          "application_service.rb" => "app/services/application_service.rb",
+          "result.rb" => "app/services/result.rb"
+        }.freeze
+
+        def if_condition(_context) = true
+
+        def prompt(context)
+          shell = context.shell
+          choice = shell.ask("Add an application service architecture? (default: no):").to_s.strip
+          choice = "no" if choice.empty?
+
+          loop do
+            case choice.downcase
+            when "yes", "y"
+              context.answer(:services, true)
+              break
+            when "no", "n"
+              context.answer(:services, false)
+              break
+            else
+              shell.say("Invalid. Enter 'yes' or 'no'.", :red)
+              choice = shell.ask("Add an application service architecture? (default: no):").to_s.strip
+              choice = "no" if choice.empty?
+            end
+          end
+        end
+
+        def generate(context)
+          enabled = context.get(:services) == true
+
+          if enabled
+            writer = OpinionatedRails::Generators::FileWriter.new
+            FILES.each do |source, destination|
+              content = File.read(File.join(TEMPLATES_DIR, source))
+              writer.write(File.join(context.app_path, destination), content)
+            end
+          end
+
+          context.set_output(:services, { services: enabled })
+        end
+
+        def outputs(context)
+          context.output(:services)
+        end
+      end
+    end
+  end
+end

data/lib/opinionated_rails/steps/addons/solid_stack_step.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  module Steps
+    module Addons
+      class SolidStackStep < Step
+        def self.id = :solid_stack
+        def self.tier = :addon
+        def self.needs = []
+        def self.summary = "Configure Solid Trifecta"
+        def self.description = "Sets up Solid Queue, Solid Cache, and Solid Cable for background jobs, caching, and Action Cable."
+        def self.prompts = "Background jobs/cache/cable: Solid Trifecta or Redis+Sidekiq (default: Solid)"
+
+        REDIS_VERSION = "6.0.0".freeze
+        SIDEKIQ_VERSION = "8.1.7".freeze
+
+        # `config.cache_store`/`config.active_job.queue_adapter` only get rewritten to their
+        # Solid variants by `solid_cache:install`/`solid_queue:install`, which are `after_bundle`
+        # hooks that never run under `rails new --skip-bundle` (our fast/no-network test path).
+        # So both the "Solid already installed" anchor and the untouched Rails default (still
+        # commented out) are handled here.
+        CACHE_STORE_ANCHORS = [
+          "config.cache_store = :solid_cache_store",
+          "# config.cache_store = :mem_cache_store"
+        ].freeze
+        CACHE_STORE_REPLACEMENT = "config.cache_store = :redis_cache_store, " \
+                                  "{ url: ENV.fetch(\"REDIS_URL\", \"redis://localhost:6379/1\") }"
+
+        QUEUE_ADAPTER_ANCHORS = [
+          "  config.active_job.queue_adapter = :solid_queue\n  config.solid_queue.connects_to = { database: { writing: :queue } }\n",
+          "  # config.active_job.queue_adapter = :resque\n"
+        ].freeze
+        QUEUE_ADAPTER_REPLACEMENT = "  config.active_job.queue_adapter = :sidekiq\n"
+
+        # Likewise, `config/cable.yml`'s production block only becomes `adapter: solid_cable`
+        # once `solid_cable:install` (also `after_bundle`) has run; otherwise it's still Rails'
+        # own un-swapped default, which already reads `adapter: redis` — nothing to do there.
+        CABLE_PRODUCTION_BLOCK = <<~YAML
+          production:
+            adapter: solid_cable
+            connects_to:
+              database:
+                writing: cable
+            polling_interval: 0.1.seconds
+            message_retention: 1.day
+        YAML
+
+        CABLE_PRODUCTION_REPLACEMENT = <<~YAML
+          production:
+            adapter: redis
+            url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>
+        YAML
+
+        SIDEKIQ_INITIALIZER = <<~RUBY
+          # frozen_string_literal: true
+
+          # Production must be told where Redis is, or jobs and cable silently talk to nothing. The Docker
+          # build runs assets:precompile with SECRET_KEY_BASE_DUMMY and no Redis, so that case is exempt.
+          redis_url = ENV.fetch("REDIS_URL") do
+            raise "REDIS_URL is not set" if Rails.env.production? && ENV["SECRET_KEY_BASE_DUMMY"].to_s.empty?
+
+            "redis://localhost:6379/1"
+          end
+
+          Sidekiq.configure_server do |config|
+            config.redis = { url: redis_url }
+          end
+
+          Sidekiq.configure_client do |config|
+            config.redis = { url: redis_url }
+          end
+        RUBY
+
+        SIDEKIQ_WEB_ROUTE_COMMENT = "  # Gate this behind authentication before enabling — Sidekiq::Web has no built-in auth.\n" \
+                                     "  # mount Sidekiq::Web => \"/sidekiq\"\n"
+
+        SOLID_GEMS = %w[ solid_cache solid_queue solid_cable ].freeze
+        SOLID_FILES = %w[
+          config/cache.yml config/queue.yml config/recurring.yml
+          db/cache_schema.rb db/queue_schema.rb db/cable_schema.rb
+          bin/jobs
+        ].freeze
+        SOLID_DATABASE_KEYS = %w[ cache queue cable ].freeze
+
+        def if_condition(_context) = true
+
+        def prompt(context)
+          shell = context.shell
+          shell.say("Choose a background jobs/cache/cable stack:")
+          shell.say("  1. Solid Trifecta (default)")
+          shell.say("  2. Redis + Sidekiq")
+
+          choice = shell.ask("Stack (default: Solid):").to_s.strip
+          choice = "1" if choice.empty?
+
+          loop do
+            case choice.downcase
+            when "solid", "1"
+              context.answer(:solid_stack, :solid)
+              break
+            when "redis", "2"
+              context.answer(:solid_stack, :redis)
+              break
+            else
+              shell.say("Invalid. Enter 'Solid', 'Redis', 1, or 2.", :red)
+              choice = shell.ask("Stack (default: Solid):").to_s.strip
+              choice = "1" if choice.empty?
+            end
+          end
+        end
+
+        def generate(context)
+          strategy = context.get(:solid_stack) || :solid
+
+          install_redis_and_sidekiq(context) if strategy == :redis
+
+          context.set_output(:solid_stack, { solid_stack: strategy })
+        end
+
+        def outputs(context)
+          context.output(:solid_stack)
+        end
+
+        private
+
+        def install_redis_and_sidekiq(context)
+          add_top_level_gem(context, "gem \"redis\", \"#{REDIS_VERSION}\"")
+          add_top_level_gem(context, "gem \"sidekiq\", \"#{SIDEKIQ_VERSION}\"")
+
+          swap_cache_store(context)
+          swap_queue_adapter(context)
+          swap_cable_adapter(context)
+          write_sidekiq_initializer(context)
+          add_commented_sidekiq_route(context)
+          remove_solid_leftovers(context)
+        end
+
+        # The Redis stack replaces Solid entirely; leaving the gems, configs and database
+        # blocks behind makes other environments (e.g. staging) boot solid_cable without config.
+        def remove_solid_leftovers(context)
+          remove_solid_gems(context)
+          SOLID_FILES.each { |file| FileUtils.rm_f(File.join(context.app_path, file)) }
+          remove_solid_database_blocks(context)
+        end
+
+        def remove_solid_gems(context)
+          path = File.join(context.app_path, "Gemfile")
+          return unless File.exist?(path)
+
+          pattern = /\Agem\s+["'](?:#{SOLID_GEMS.join('|')})["']/
+          File.write(path, File.read(path).lines.reject { |line| line.match?(pattern) }.join)
+        end
+
+        def remove_solid_database_blocks(context)
+          path = File.join(context.app_path, "config/database.yml")
+          return unless File.exist?(path)
+
+          keys = SOLID_DATABASE_KEYS.join("|")
+          content = File.read(path).gsub(/^  (?:#{keys}):\n(?:    .*\n|\s*\n)*?(?=  \S|\S|\z)/, "")
+          File.write(path, content)
+        end
+
+        def swap_cache_store(context)
+          swap_first_matching_anchor(
+            context,
+            File.join(context.app_path, "config/environments/production.rb"),
+            CACHE_STORE_ANCHORS,
+            CACHE_STORE_REPLACEMENT
+          )
+        end
+
+        def swap_queue_adapter(context)
+          swap_first_matching_anchor(
+            context,
+            File.join(context.app_path, "config/environments/production.rb"),
+            QUEUE_ADAPTER_ANCHORS,
+            QUEUE_ADAPTER_REPLACEMENT
+          )
+        end
+
+        # If Rails rewords the text we match, the swap would silently do nothing and leave the app on
+        # Solid while the Gemfile says Redis; say so instead.
+        def swap_first_matching_anchor(context, path, anchors, replacement)
+          relative = path.delete_prefix("#{context.app_path}/")
+          return warn_not_swapped(context, relative, replacement) unless File.exist?(path)
+
+          content = File.read(path)
+          return if content.include?(replacement)
+
+          anchor = anchors.find { |candidate| content.include?(candidate) }
+          return warn_not_swapped(context, relative, replacement) unless anchor
+
+          File.write(path, content.sub(anchor, replacement))
+        end
+
+        def warn_not_swapped(context, relative, replacement)
+          context.shell.say(
+            "Warning: could not switch #{relative} to Redis (expected Rails text not found). Set it by hand: #{replacement.strip}",
+            :yellow
+          )
+        end
+
+        def swap_cable_adapter(context)
+          path = File.join(context.app_path, "config/cable.yml")
+          return unless File.exist?(path)
+
+          content = File.read(path)
+          # Un-swapped Rails defaults (e.g. --skip-bundle) already read `adapter: redis`.
+          unless content.include?(CABLE_PRODUCTION_BLOCK)
+            unless content.include?("adapter: redis")
+              context.shell.say("Warning: config/cable.yml has no Solid Cable or Redis production block; set `adapter: redis` by hand.", :yellow)
+            end
+            return
+          end
+
+          File.write(path, content.sub(CABLE_PRODUCTION_BLOCK, CABLE_PRODUCTION_REPLACEMENT))
+        end
+
+        def write_sidekiq_initializer(context)
+          path = File.join(context.app_path, "config/initializers/sidekiq.rb")
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, SIDEKIQ_INITIALIZER)
+        end
+
+        def add_commented_sidekiq_route(context)
+          path = File.join(context.app_path, "config/routes.rb")
+          return unless File.exist?(path)
+
+          content = File.read(path)
+          return if content.include?("mount Sidekiq::Web")
+
+          lines = content.lines
+          end_index = lines.rindex { |line| line.strip == "end" }
+          return unless end_index
+
+          lines.insert(end_index, SIDEKIQ_WEB_ROUTE_COMMENT)
+          File.write(path, lines.join)
+        end
+
+        def add_top_level_gem(context, gem_line)
+          gemfile_path = File.join(context.app_path, "Gemfile")
+          return unless File.exist?(gemfile_path)
+
+          content = File.read(gemfile_path)
+          return if content.include?(gem_line)
+
+          File.open(gemfile_path, "a") { |f| f.puts(gem_line) }
+        end
+      end
+    end
+  end
+end

data/lib/opinionated_rails/steps/addons/spa_controller_step.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  module Steps
+    module Addons
+      class SpaControllerStep < Step
+        def self.id = :spa_controller
+        def self.tier = :addon
+        def self.needs = [ :frontend ]
+        def self.summary = "Add a SPA catch-all controller"
+        def self.description = "Generates the always-present spa_controller.rb#root action."
+        def self.prompts = "None"
+
+        def if_condition(context)
+          context.output(:app_type, :app_type) != :api_only
+        end
+
+        def prompt(_context); end
+
+        def generate(context)
+          unless if_condition(context)
+            context.set_output(:spa_controller, nil)
+            return
+          end
+
+          write_controller(context)
+          write_view(context)
+          append_route(context)
+
+          output_key = context.output(:frontend, :frontend) == :react ? :react_mount : :fallback_404
+          context.set_output(:spa_controller, { spa_controller: output_key })
+        end
+
+        def outputs(context)
+          context.output(:spa_controller)
+        end
+
+        private
+
+        def write_controller(context)
+          controller_path = File.join(context.app_path, "app/controllers/spa_controller.rb")
+          FileUtils.mkdir_p(File.dirname(controller_path))
+
+          controller = if context.output(:frontend, :frontend) == :react
+                         "class SpaController < ApplicationController\n  def root\n  end\nend\n"
+          else
+                         "class SpaController < ApplicationController\n  def root\n    render status: :not_found\n  end\nend\n"
+          end
+
+          File.write(controller_path, controller)
+        end
+
+        def write_view(context)
+          view_dir = File.join(context.app_path, "app/views/spa")
+          FileUtils.mkdir_p(view_dir)
+
+          view = if context.output(:frontend, :frontend) == :react
+                   "<div id=\"root\"></div>\n"
+          else
+                   "<h1>Not Found</h1>\n"
+          end
+
+          File.write(File.join(view_dir, "root.html.erb"), view)
+        end
+
+        def append_route(context)
+          routes_path = File.join(context.app_path, "config/routes.rb")
+          return unless File.exist?(routes_path)
+
+          lines = File.readlines(routes_path)
+          return if lines.any? { |line| line.include?("spa#root") }
+
+          end_index = lines.rindex { |line| line.strip == "end" }
+          return unless end_index
+
+          # `*path` does not match "/", so a React app needs an explicit root.
+          routes = []
+          routes << "  root \"spa#root\"\n" if context.output(:frontend, :frontend) == :react
+          routes << "  get \"*path\", to: \"spa#root\", constraints: ->(req) { !req.xhr? && req.format.html? }\n"
+          lines.insert(end_index, *routes)
+
+          File.write(routes_path, lines.join)
+        end
+      end
+    end
+  end
+end

data/lib/opinionated_rails/steps/addons/staging_env_step.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  module Steps
+    module Addons
+      class StagingEnvStep < Step
+        def self.id = :staging_env
+        def self.tier = :addon
+        # Staging is seeded from production, so it must run after every step that edits
+        # production.rb / database.yml / cable.yml (stack swap, mailer, Docker).
+        def self.needs = [ :solid_stack, :mailer, :docker_kamal ]
+        def self.summary = "Add staging environment"
+        def self.description = "Creates a staging Rails environment file and configuration."
+        def self.prompts = "Add a staging environment? (default: no)"
+
+        REVIEW_COMMENT = <<~RUBY
+          # Seeded from config/environments/production.rb by opinionated_rails.
+          # Review and adjust host names, credentials scoping, and any production-only
+          # assumptions before using this environment.
+
+        RUBY
+
+        MAIL_NOTICE = <<~RUBY
+          # Staging must not send real email through the production Postmark account. To test delivery,
+          # create a separate Postmark server for staging and use its token:
+          #   config.action_mailer.delivery_method = :postmark
+          #   config.action_mailer.postmark_settings = { api_token: ENV["POSTMARK_STAGING_API_TOKEN"] }
+        RUBY
+
+        # Files with a top-level `production:` block that needs a `staging:` twin; without it
+        # `RAILS_ENV=staging` fails to boot (e.g. solid_cable reading cable.yml).
+        STAGING_YAML_FILES = %w[ database cable cache queue recurring ].map { |name| "config/#{name}.yml" }.freeze
+
+        def if_condition(_context) = true
+
+        def prompt(context)
+          shell = context.shell
+          choice = shell.ask("Add a staging environment? (default: no):").to_s.strip
+          choice = "no" if choice.empty?
+
+          loop do
+            case choice.downcase
+            when "yes", "y"
+              context.answer(:staging_env, true)
+              break
+            when "no", "n"
+              context.answer(:staging_env, false)
+              break
+            else
+              shell.say("Invalid. Enter 'yes' or 'no'.", :red)
+              choice = shell.ask("Add a staging environment? (default: no):").to_s.strip
+              choice = "no" if choice.empty?
+            end
+          end
+        end
+
+        def generate(context)
+          enabled = context.get(:staging_env) == true
+
+          if enabled
+            write_staging_environment(context)
+            STAGING_YAML_FILES.each { |file| add_staging_yaml_block(File.join(context.app_path, file)) }
+          end
+
+          context.set_output(:staging_env, { staging_env: enabled })
+        end
+
+        def outputs(context)
+          context.output(:staging_env)
+        end
+
+        private
+
+        def write_staging_environment(context)
+          production_path = File.join(context.app_path, "config/environments/production.rb")
+          return unless File.exist?(production_path)
+
+          staging_path = File.join(context.app_path, "config/environments/staging.rb")
+          File.write(staging_path, REVIEW_COMMENT + isolate_mail(File.read(production_path)))
+        end
+
+        # Seeded from production, staging would deliver real email through the production Postmark account.
+        def isolate_mail(content)
+          content.gsub(/^(\s*)config\.action_mailer\.delivery_method = :postmark\n/) do
+            indent = Regexp.last_match(1)
+            MAIL_NOTICE.lines.map { |line| "#{indent}#{line}" }.join + "#{indent}config.action_mailer.delivery_method = :test\n"
+          end.gsub(/^\s*config\.action_mailer\.postmark_settings = .*\n/, "")
+        end
+
+        def add_staging_yaml_block(path)
+          return unless File.exist?(path)
+
+          lines = File.read(path).lines
+          return if lines.any? { |line| line.start_with?("staging:") }
+
+          start = lines.index { |line| line.start_with?("production:") }
+          return unless start
+
+          finish = (start + 1...lines.size).find { |i| lines[i].match?(/\A\S/) } || lines.size
+          block = lines[start...finish].join.rstrip.gsub("production", "staging")
+
+          lines[-1] = "#{lines.last.chomp}\n" unless lines.empty?
+          File.write(path, "#{lines.join}\n#{block}\n")
+        end
+      end
+    end
+  end
+end