opinionated_rails 0.1.4

data/lib/opinionated_rails/kamal_config.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  # `kamal init` writes a fully commented-out deploy.yml, which is not deployable and loses data:
+  # no RAILS_MASTER_KEY, no volume for SQLite, no Redis for Sidekiq. This builds a file that is
+  # complete for the chosen stack; only the CHANGE_ME values (server, registry, host) are left to fill in.
+  module KamalConfig
+    PLACEHOLDER = "CHANGE_ME"
+
+    def self.service_name(app_name) = app_name.to_s.tr("_", "-")
+
+    def self.deploy_yml(app_name:, database:, stack:)
+      service = service_name(app_name)
+      volume = app_name.to_s
+      sqlite = database == :sqlite3
+      redis = stack == :redis
+
+      lines = []
+      lines << "# Kamal deployment for #{service}, generated by opinionated_rails."
+      lines << "# Replace every #{PLACEHOLDER}_* value, then run `bin/kamal setup`. Docs: https://kamal-deploy.org"
+      lines << "service: #{service}"
+      lines << "image: #{PLACEHOLDER}_registry_username/#{service}"
+      lines << ""
+      lines << "servers:"
+      lines << "  web:"
+      lines << "    - #{PLACEHOLDER}_server_ip"
+      if redis
+        lines << "  job:"
+        lines << "    hosts:"
+        lines << "      - #{PLACEHOLDER}_server_ip"
+        lines << "    cmd: bundle exec sidekiq"
+      end
+      lines << ""
+      lines << "proxy:"
+      lines << "  ssl: true"
+      lines << "  host: #{PLACEHOLDER}.example.com"
+      lines << ""
+      lines << "registry:"
+      lines << "  username: #{PLACEHOLDER}_registry_username"
+      lines << "  password:"
+      lines << "    - KAMAL_REGISTRY_PASSWORD"
+      lines << ""
+      lines << "builder:"
+      lines << "  arch: amd64"
+      lines << ""
+      lines << "env:"
+      lines << "  secret:"
+      lines << "    - RAILS_MASTER_KEY"
+      lines << "    - DATABASE_URL" unless sqlite
+      lines << "  clear:"
+      lines << (redis ? "    REDIS_URL: redis://#{service}-redis:6379/1" : "    SOLID_QUEUE_IN_PUMA: true")
+      lines << ""
+      lines << "# Persistent data. Without these, every deploy starts from an empty database/uploads."
+      lines << "volumes:"
+      lines << "  - \"#{volume}_storage:/rails/storage\""
+      lines << "  - \"#{volume}_data:/data\"" if sqlite
+      lines << ""
+      lines << "# Keep old fingerprinted assets available to in-flight requests during a deploy."
+      lines << "asset_path: /rails/public/assets"
+      lines.concat(redis_accessory(service)) if redis
+      lines << ""
+      lines << "aliases:"
+      lines << "  console: app exec --interactive --reuse \"bin/rails console\""
+      lines << "  shell: app exec --interactive --reuse \"bash\""
+      lines << "  logs: app logs -f"
+      lines << "  dbc: app exec --interactive --reuse \"bin/rails dbconsole --include-password\""
+      "#{lines.join("\n")}\n"
+    end
+
+    def self.redis_accessory(service)
+      [
+        "",
+        "accessories:",
+        "  redis:",
+        "    image: redis:7",
+        "    host: #{PLACEHOLDER}_server_ip",
+        "    directories:",
+        "      - data:/data",
+        "    cmd: redis-server --appendonly yes"
+      ]
+    end
+
+    # Safe to commit: values are read from the environment or from config/master.key, never written here.
+    def self.secrets(database:)
+      lines = [
+        "# Read from your environment or a file; never write raw credentials here (this file is committed).",
+        "KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD",
+        "RAILS_MASTER_KEY=$(cat config/master.key)"
+      ]
+      lines << "DATABASE_URL=$DATABASE_URL" unless database == :sqlite3
+      "#{lines.join("\n")}\n"
+    end
+  end
+end

data/lib/opinionated_rails/manifest.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+require "fileutils"
+
+module OpinionatedRails
+  class Manifest
+    FILENAME = ".opinionated_rails.yml"
+    VERSION = "0.1.0"
+
+    def self.load(app_path)
+      path = File.join(app_path, FILENAME)
+      data = File.exist?(path) ? YAML.safe_load_file(path, permitted_classes: [ Date, DateTime, Time ], aliases: true) || {} : {}
+      new(app_path, data)
+    end
+
+    def initialize(app_path, data)
+      @app_path = app_path
+      @data = data
+    end
+
+    def [](key)
+      @data[key]
+    end
+
+    def []=(key, value)
+      @data[key] = value
+    end
+
+    def to_h
+      @data.dup
+    end
+
+    def write
+      path = File.join(@app_path, FILENAME)
+      tmp = "#{path}.tmp.#{Process.pid}"
+      File.write(tmp, YAML.dump(@data))
+      File.rename(tmp, path)
+    end
+  end
+end

data/lib/opinionated_rails/pins.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+
+module OpinionatedRails
+  # Every gem and npm package the steps pin. `rake pins:check` confirms each pinned version still
+  # exists on its registry and reports newer ones, so pins cannot rot unnoticed.
+  module Pins
+    Pin = Struct.new(:registry, :name, :version, :source)
+    Result = Struct.new(:pin, :status, :latest)
+
+    # *_VERSION constants in the steps => gem name (the constant name alone is ambiguous)
+    GEM_NAMES = {
+      "RSPEC" => "rspec-rails", "REDIS" => "redis", "SIDEKIQ" => "sidekiq", "FACTORY_BOT" => "factory_bot_rails",
+      "DEVISE" => "devise", "GEARED_PAGINATION" => "geared_pagination", "PAGY" => "pagy",
+      "RUBOCOP_OMAKASE" => "rubocop-rails-omakase", "DOTENV_RAILS" => "dotenv-rails", "VCR" => "vcr",
+      "WEBMOCK" => "webmock", "DOCKERFILE_RAILS" => "dockerfile-rails", "KAMAL" => "kamal",
+      "LETTER_OPENER" => "letter_opener", "POSTMARK_RAILS" => "postmark-rails", "FAKER" => "faker",
+      "TAILWIND_RAILS" => "tailwindcss-rails"
+    }.freeze
+
+    # constants that pin an npm package rather than a gem
+    NPM_CONSTANTS = { "TAILWIND" => "tailwindcss" }.freeze
+
+    CONSTANT_PATTERN = /^\s+([A-Z][A-Z_]*)_VERSION = "(\d[\w.]*)"/
+    NPM_ASSIGNMENT_PATTERN = /package\["(?:dependencies|devDependencies)"\]\["([^"]+)"\] = "(\d[\w.]*)"/
+
+    def self.collect(root = File.expand_path("..", __dir__))
+      Dir.glob(File.join(root, "opinionated_rails/steps/**/*.rb")).sort.flat_map do |file|
+        source = File.read(file, encoding: "UTF-8")
+        relative = file.sub("#{root}/", "")
+        constants = source.scan(CONSTANT_PATTERN).map { |const, version| pin_for_constant(const, version, relative) }
+        npm = source.scan(NPM_ASSIGNMENT_PATTERN).map { |name, version| Pin.new(:npm, name, version, relative) }
+        constants + npm
+      end.uniq { |pin| [ pin.registry, pin.name, pin.version ] }
+    end
+
+    def self.pin_for_constant(const, version, source)
+      return Pin.new(:npm, NPM_CONSTANTS.fetch(const), version, source) if NPM_CONSTANTS.key?(const)
+
+      Pin.new(:gem, GEM_NAMES.fetch(const) { raise ArgumentError, "No gem name for #{const}_VERSION in #{source}; add it to Pins::GEM_NAMES" },
+              version, source)
+    end
+
+    # fetcher: ->(registry, name) { { versions: [...], latest: "x" } }
+    def self.check(pins, fetcher: method(:fetch))
+      pins.map do |pin|
+        info = fetcher.call(pin.registry, pin.name)
+        Result.new(pin, status_for(pin, info), info[:latest])
+      end
+    end
+
+    def self.status_for(pin, info)
+      return :missing unless info[:versions].include?(pin.version)
+
+      newer?(info[:latest], pin.version) ? :outdated : :current
+    end
+
+    def self.newer?(latest, pinned)
+      Gem::Version.correct?(latest) && Gem::Version.correct?(pinned) && Gem::Version.new(latest) > Gem::Version.new(pinned)
+    end
+
+    def self.fetch(registry, name)
+      case registry
+      when :gem
+        list = JSON.parse(get("https://rubygems.org/api/v1/versions/#{name}.json"))
+        stable = list.reject { |v| v["prerelease"] }.map { |v| v["number"] }
+        { versions: list.map { |v| v["number"] }, latest: stable.max_by { |v| Gem::Version.new(v) } }
+      when :npm
+        data = JSON.parse(get("https://registry.npmjs.org/#{name}"))
+        { versions: data.fetch("versions").keys, latest: data.dig("dist-tags", "latest") }
+      end
+    end
+
+    def self.get(url)
+      response = Net::HTTP.get_response(URI(url))
+      raise "GET #{url} returned #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      response.body
+    end
+  end
+end

data/lib/opinionated_rails/prerequisites.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  # Tools the chosen options shell out to. Checked before `rails new` so a missing tool fails
+  # fast with instructions, rather than leaving a half-built app (jsbundling-rails, for example,
+  # silently skips `yarn add esbuild` when yarn is absent).
+  module Prerequisites
+    INSTALL_HINTS = {
+      "node" => "install Node.js (https://nodejs.org)",
+      "yarn" => "enable it with `corepack enable` or install it with `npm install -g yarn`",
+      "bun" => "install it from https://bun.sh"
+    }.freeze
+
+    def self.required_tools(context)
+      return [] unless context.get(:frontend) == :react
+
+      context.get(:bundler) == :bun ? %w[ bun ] : %w[ node yarn ]
+    end
+
+    def self.available?(tool, path: ENV.fetch("PATH", ""))
+      path.split(File::PATH_SEPARATOR).any? do |dir|
+        candidate = File.join(dir, tool)
+        File.file?(candidate) && File.executable?(candidate)
+      end
+    end
+
+    def self.check!(context, path: ENV.fetch("PATH", ""))
+      return if context.skip_bundle_install
+
+      missing = required_tools(context).reject { |tool| available?(tool, path: path) }
+      return if missing.empty?
+
+      details = missing.map { |tool| "  - #{tool}: #{INSTALL_HINTS.fetch(tool)}" }.join("\n")
+      raise OpinionatedRails::Error,
+            "The React frontend needs tools that are not on your PATH:\n#{details}\n" \
+            "Install them and re-run, or pass --skip-bundle-install to only scaffold files."
+    end
+  end
+end

data/lib/opinionated_rails/rails_version_guard.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module OpinionatedRails
+  # The steps patch text and config that Rails 8.1 generates (Solid defaults, Kamal, authentication),
+  # so only Rails 8.1+ within 8.x is supported. Other versions are rejected before anything is generated.
+  class RailsVersionGuard
+    class UnsupportedError < OpinionatedRails::Error; end
+
+    MINIMUM = Gem::Version.new("8.1")
+    SUPPORTED_MAJOR = 8
+
+    def self.from_string(version)
+      new(version)
+    end
+
+    # Version of the `rails` executable `rails new` will use, or an error if there is none.
+    def self.installed
+      output, status = Bundler.with_unbundled_env { Open3.capture2e("rails", "--version") }
+      version = output[/Rails (\d[\w.]*)/, 1]
+      return version if status.success? && version
+
+      raise UnsupportedError, "Rails is not installed or `rails --version` failed. Install it with `gem install rails`."
+    rescue Errno::ENOENT
+      raise UnsupportedError, "Rails is not installed. Install it with `gem install rails`."
+    end
+
+    def self.check_installed!
+      from_string(installed).assert!
+    end
+
+    def initialize(version)
+      @version = version
+    end
+
+    def assert!
+      parsed = Gem::Version.correct?(@version) && Gem::Version.new(@version)
+
+      unless parsed && parsed.segments.first == SUPPORTED_MAJOR && parsed >= MINIMUM
+        raise UnsupportedError,
+              "Rails #{@version} is not supported. opinionated_rails needs Rails #{MINIMUM} or newer in the " \
+              "#{SUPPORTED_MAJOR}.x series. Update with `gem update rails`."
+      end
+
+      true
+    end
+  end
+end

data/lib/opinionated_rails/step.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  class Step
+    def self.id
+      raise NotImplementedError, "#{name}#id not implemented"
+    end
+
+    def self.summary
+      raise NotImplementedError, "#{name}#summary not implemented"
+    end
+
+    def self.description
+      raise NotImplementedError, "#{name}#description not implemented"
+    end
+
+    def self.tier
+      :addon
+    end
+
+    def self.needs
+      []
+    end
+
+    def if_condition(_context)
+      true
+    end
+
+    def prompt(_context)
+      raise NotImplementedError, "#{self.class}#prompt not yet implemented"
+    end
+
+    def generate(_context)
+      raise NotImplementedError, "#{self.class}#generate not yet implemented"
+    end
+
+    def outputs(_context)
+      raise NotImplementedError, "#{self.class}#outputs not yet implemented"
+    end
+  end
+end

data/lib/opinionated_rails/step_graph.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  class StepGraph
+    class Error < OpinionatedRails::Error; end
+    class CycleError < Error; end
+    class MissingDependencyError < Error; end
+
+    def initialize(steps)
+      @steps = steps
+      @by_id = steps.to_h { |step| [ step.class.id, step ] }
+    end
+
+    def sorted
+      @by_id.each_value do |step|
+        step.class.needs.each do |needed|
+          raise MissingDependencyError, "Step #{step.class.id.inspect} needs #{needed.inspect}, which is not registered" unless @by_id.key?(needed)
+        end
+      end
+
+      in_degree = Hash.new(0)
+      @by_id.each_key { |id| in_degree[id] = 0 }
+      dependents = Hash.new { |h, k| h[k] = [] }
+
+      @by_id.each_value do |step|
+        step.class.needs.each do |needed|
+          dependents[needed] << step.class.id
+          in_degree[step.class.id] += 1
+        end
+      end
+
+      queue = in_degree.select { |_, v| v.zero? }.keys
+      result = []
+
+      until queue.empty?
+        id = queue.shift
+        result << @by_id[id]
+
+        dependents[id].each do |dependent|
+          in_degree[dependent] -= 1
+          queue << dependent if in_degree[dependent].zero?
+        end
+      end
+
+      if result.size != @by_id.size
+        remaining = in_degree.reject { |_, v| v.zero? }.keys
+        raise CycleError, "Cyclic step dependencies detected among: #{remaining.map(&:inspect).join(', ')}"
+      end
+
+      result
+    end
+  end
+end

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  module Steps
+    module Addons
+      class AuthStep < Step
+        def self.id = :auth
+        def self.tier = :addon
+        def self.needs = []
+        def self.summary = "Configure authentication"
+        def self.description = "Prompts for a user model name and chooses Rails 8 built-in, Devise, or none."
+        def self.prompts = "User model name (default: User), then Rails 8 built-in / Devise / None (default: None)"
+
+        MODEL_NAME_FORMAT = /\A[A-Z][A-Za-z0-9]*\z/
+        DEVISE_VERSION = "5.0.4".freeze
+
+        def if_condition(_context) = true
+
+        API_ONLY_NOTICE = "Authentication is skipped for API-only apps: Rails' built-in generator and Devise " \
+                          "both generate browser-session code that does not work without cookies and views."
+
+        def prompt(context)
+          shell = context.shell
+
+          if api_only?(context)
+            shell.say(API_ONLY_NOTICE, :yellow)
+            context.answer(:auth, :none)
+            return
+          end
+
+          model_name = shell.ask("User model name (default: User):").to_s.strip
+          model_name = "User" if model_name.empty?
+          until MODEL_NAME_FORMAT.match?(model_name)
+            shell.say("Invalid model name. Use a CamelCase constant such as User or Account.", :red)
+            model_name = shell.ask("User model name (default: User):").to_s.strip
+            model_name = "User" if model_name.empty?
+          end
+          context.answer(:auth_model_name, model_name)
+
+          shell.say("Choose an authentication strategy:")
+          shell.say("  1. None (default)")
+          shell.say("  2. Rails 8 built-in")
+          shell.say("  3. Devise")
+
+          choice = shell.ask("Authentication (default: None):").to_s.strip
+          choice = "1" if choice.empty?
+
+          loop do
+            case choice.downcase
+            when "none", "1"
+              context.answer(:auth, :none)
+              break
+            when "rails8", "rails 8", "2"
+              context.answer(:auth, :rails8)
+              break
+            when "devise", "3"
+              context.answer(:auth, :devise)
+              break
+            else
+              shell.say("Invalid. Enter 'None', 'Rails8', 'Devise', 1, 2, or 3.", :red)
+              choice = shell.ask("Authentication (default: None):").to_s.strip
+              choice = "1" if choice.empty?
+            end
+          end
+        end
+
+        def generate(context)
+          strategy = api_only?(context) ? :none : (context.get(:auth) || :none)
+
+          case strategy
+          when :rails8
+            install_rails8_auth(context)
+          when :devise
+            install_devise(context)
+          else
+            context.set_output(:auth, { auth: :none })
+          end
+        end
+
+        def outputs(context)
+          context.output(:auth)
+        end
+
+        private
+
+        def api_only?(context) = context.output(:app_type, :app_type) == :api_only
+
+        def install_rails8_auth(context)
+          unless context.skip_bundle_install
+            command = [ "bundle", "exec", "rails", "generate", "authentication" ]
+
+            run_in_app(context, "bundle", "install", "--quiet") ||
+              raise(OpinionatedRails::Error, "bundle install failed")
+            run_in_app(context, *command) ||
+              raise(OpinionatedRails::Error, "rails generate authentication failed")
+          end
+
+          add_home_page(context) unless context.output(:frontend, :frontend) == :react
+
+          context.set_output(:auth, { auth: :rails8, user_model: "User" })
+        end
+
+        # Rails 8's generated SessionsController redirects to root_url after sign-in, but a new app has no
+        # root route, so signing in would raise NameError. (React apps get their root from the SPA step.)
+        def add_home_page(context)
+          routes_path = File.join(context.app_path, "config/routes.rb")
+          return unless File.exist?(routes_path)
+
+          routes = File.readlines(routes_path)
+          return if routes.any? { |line| line.match?(/^\s*root\b/) }
+
+          end_index = routes.rindex { |line| line.strip == "end" }
+          return unless end_index
+
+          routes.insert(end_index, "  root \"home#index\"\n")
+          File.write(routes_path, routes.join)
+
+          write_file(context, "app/controllers/home_controller.rb", "class HomeController < ApplicationController\n  def index\n  end\nend\n")
+          write_file(context, "app/views/home/index.html.erb", "<h1>Home</h1>\n")
+        end
+
+        def write_file(context, relative, content)
+          path = File.join(context.app_path, relative)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, content) unless File.exist?(path)
+        end
+
+        def install_devise(context)
+          model_name = context.get(:auth_model_name) || "User"
+
+          add_top_level_gem(context, "gem \"devise\", \"#{DEVISE_VERSION}\"")
+
+          unless context.skip_bundle_install
+            run_in_app(context, "bundle", "install", "--quiet") ||
+              raise(OpinionatedRails::Error, "bundle install failed")
+            run_in_app(context, "bundle", "exec", "rails", "generate", "devise:install") ||
+              raise(OpinionatedRails::Error, "devise:install failed")
+            run_in_app(context, "bundle", "exec", "rails", "generate", "devise", model_name) ||
+              raise(OpinionatedRails::Error, "devise generator failed")
+
+            run_in_app(context, "bundle", "exec", "rails", "generate", "devise:views") ||
+              raise(OpinionatedRails::Error, "devise:views failed")
+          end
+
+          context.set_output(:auth, { auth: :devise, user_model: model_name })
+        end
+
+        def run_in_app(context, *command)
+          Dir.chdir(context.app_path) do
+            if defined?(Bundler)
+              Bundler.with_unbundled_env { system(*command) }
+            else
+              system(*command)
+            end
+          end
+        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