opinionated_rails 0.1.4

data/lib/opinionated_rails/steps/core/frontend_step.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  module Steps
+    module Core
+      class FrontendStep < Step
+        def self.id = :frontend
+        def self.summary = "Choose the frontend stack"
+        def self.description = "Prompts for Stimulus+Hotwire, React, or no frontend for API-only apps."
+        def self.tier = :core
+        def self.prompts = "Frontend: Stimulus+Hotwire (1) or React (2), default Stimulus; React also asks for a bundler"
+
+        BABEL_CONFIG = <<~JSON
+          {
+            "presets": [
+              ["@babel/preset-env", { "modules": false }],
+              ["@babel/preset-react", { "runtime": "automatic" }]
+            ]
+          }
+        JSON
+
+        WEBPACK_CONFIG = <<~JS
+          const path    = require("path")
+          const webpack = require("webpack")
+
+          module.exports = {
+            mode: "production",
+            devtool: "source-map",
+            entry: {
+              application: "./app/javascript/application.jsx"
+            },
+            resolve: {
+              extensions: [".js", ".jsx"],
+              alias: { "@": path.resolve(__dirname, "app/javascript") }
+            },
+            module: {
+              rules: [
+                { test: /\.jsx?$/, exclude: /node_modules/, use: "babel-loader" }
+              ]
+            },
+            output: {
+              filename: "[name].js",
+              sourceMapFilename: "[file].map",
+              chunkFormat: "module",
+              path: path.resolve(__dirname, "app/assets/builds"),
+            },
+            plugins: [
+              new webpack.optimize.LimitChunkCountPlugin({
+                maxChunks: 1
+              })
+            ]
+          }
+        JS
+
+        BUNDLERS = %w[esbuild bun webpack].freeze
+
+        FRONTEND_OPTIONS = %w[stimulus react].freeze
+
+        def if_condition(context)
+          context.output(:app_type, :app_type) != :api_only
+        end
+
+        def prompt(context)
+          shell = context.shell
+          shell.say("Choose a frontend stack:")
+          shell.say("  1. Stimulus + Hotwire (default)")
+          shell.say("  2. React")
+
+          choice = shell.ask("Frontend (default: Stimulus):").to_s.strip
+          choice = "1" if choice.empty?
+
+          loop do
+            case choice.downcase
+            when "stimulus", "stimulus+hotwire", "1"
+              context.answer(:frontend, :stimulus_hotwire)
+              break
+            when "react", "2"
+              context.answer(:frontend, :react)
+              break
+            else
+              shell.say("Invalid. Enter 'Stimulus' or 'React', 1, or 2.", :red)
+              choice = shell.ask("Frontend (default: Stimulus):").to_s.strip
+              choice = "1" if choice.empty?
+            end
+          end
+
+          return unless context.get(:frontend) == :react
+
+          prompt_bundler(context)
+        end
+
+        def generate(context)
+          type = if if_condition(context)
+                   context.get(:frontend) || :none
+          else
+                   :none
+          end
+
+          data = { frontend: type }
+          data[:bundler] = context.get(:bundler) if type == :react
+
+          context.set_output(:frontend, data)
+
+          return if type == :none
+
+          install_react(context) if type == :react
+        end
+
+        def outputs(context)
+          context.output(:frontend)
+        end
+
+        private
+
+        def prompt_bundler(context)
+          shell = context.shell
+          shell.say("Choose a JavaScript bundler:")
+          BUNDLERS.each_with_index do |name, index|
+            shell.say("  #{index + 1}. #{name.capitalize}")
+          end
+
+          choice = shell.ask("Bundler (default: esbuild):").to_s.strip
+          choice = "esbuild" if choice.empty?
+
+          loop do
+            choice = BUNDLERS[choice.to_i - 1] if %w[1 2 3 4].include?(choice)
+
+            if BUNDLERS.include?(choice.downcase)
+              context.answer(:bundler, choice.downcase.to_sym)
+              break
+            end
+
+            shell.say("Invalid. Enter #{BUNDLERS.join(', ')}.", :red)
+            choice = shell.ask("Bundler (default: esbuild):").to_s.strip
+          end
+        end
+
+        def install_react(context)
+          bundler = context.output(:frontend, :bundler)
+
+          update_package_json(context, bundler)
+          add_esbuild_alias(context) if bundler == :esbuild
+          configure_webpack(context) if bundler == :webpack
+          configure_bun(context) if bundler == :bun
+          warn_non_esbuild_alias(context, bundler) if bundler == :bun
+          write_js_files(context)
+          write_jsconfig(context)
+          create_images_dir(context)
+        end
+
+        def update_package_json(context, bundler)
+          package_json_path = File.join(context.app_path, "package.json")
+          package = if File.exist?(package_json_path)
+                      JSON.parse(File.read(package_json_path))
+          else
+                      { "scripts" => {}, "dependencies" => {} }
+          end
+
+          package["dependencies"] ||= {}
+          package["dependencies"]["react"] = "18.2.0"
+          package["dependencies"]["react-dom"] = "18.2.0"
+          package["dependencies"]["react-router-dom"] = "6.23.1"
+
+          if bundler == :esbuild && package["scripts"]["build"].nil?
+            package["scripts"]["build"] = "esbuild app/javascript/*.* --bundle --sourcemap --outdir=app/assets/builds --public-path=assets"
+          end
+
+          File.write(package_json_path, JSON.pretty_generate(package))
+        end
+
+        def add_esbuild_alias(context)
+          package_json_path = File.join(context.app_path, "package.json")
+          package = JSON.parse(File.read(package_json_path))
+          package["scripts"] ||= {}
+          build = package["scripts"]["build"]
+
+          if build && !build.include?("--alias:@=app/javascript")
+            package["scripts"]["build"] = "#{build} --alias:@=app/javascript"
+          end
+
+          File.write(package_json_path, JSON.pretty_generate(package))
+        end
+
+        # Rails' webpack config only knows application.js and has no JSX transform; the React files
+        # are .jsx, so the build would fail. Add Babel, the .jsx entry, and the @ alias.
+        def configure_webpack(context)
+          package_json_path = File.join(context.app_path, "package.json")
+          package = JSON.parse(File.read(package_json_path))
+          package["devDependencies"] ||= {}
+          package["devDependencies"]["@babel/core"] = "8.0.7"
+          package["devDependencies"]["@babel/preset-env"] = "8.0.7"
+          package["devDependencies"]["@babel/preset-react"] = "8.0.1"
+          package["devDependencies"]["babel-loader"] = "10.1.1"
+          File.write(package_json_path, JSON.pretty_generate(package))
+
+          File.write(File.join(context.app_path, "babel.config.json"), BABEL_CONFIG)
+          File.write(File.join(context.app_path, "webpack.config.js"), WEBPACK_CONFIG)
+        end
+
+        # Rails' bun.config.js bundles app/javascript/application.js; the React files are .jsx, which Bun
+        # builds natively once it is pointed at the right entry.
+        BUN_ENTRY = 'entrypoints: ["app/javascript/application.js"]'
+        BUN_ENTRY_JSX = 'entrypoints: ["app/javascript/application.jsx"]'
+
+        def configure_bun(context)
+          path = File.join(context.app_path, "bun.config.js")
+          content = File.exist?(path) ? File.read(path) : ""
+          return if content.include?(BUN_ENTRY_JSX)
+
+          unless content.include?(BUN_ENTRY)
+            context.shell.say(
+              "Warning: could not find `#{BUN_ENTRY}` in bun.config.js; set the entry point to " \
+              "app/javascript/application.jsx by hand.",
+              :yellow
+            )
+            return
+          end
+
+          File.write(path, content.sub(BUN_ENTRY, BUN_ENTRY_JSX))
+        end
+
+        def warn_non_esbuild_alias(context, bundler)
+          context.shell.say(
+            "Warning: the @ import alias is configured for editor/TypeScript tooling only and won't resolve " \
+            "at build time until a bundler-specific config is added (current bundler: #{bundler}).",
+            :yellow
+          )
+        end
+
+        def write_js_files(context)
+          application_js = File.join(context.app_path, "app/javascript/application.js")
+          File.delete(application_js) if File.exist?(application_js)
+
+          FileUtils.mkdir_p(File.join(context.app_path, "app/javascript"))
+
+          File.write(
+            File.join(context.app_path, "app/javascript/application.jsx"),
+            <<~'JS'
+              import React from "react";
+              import { createRoot } from "react-dom/client";
+              import { RouterProvider } from "react-router-dom";
+              import router from "./router";
+
+              const root = createRoot(document.getElementById("root"));
+              root.render(<RouterProvider router={router} />);
+            JS
+          )
+
+          File.write(
+            File.join(context.app_path, "app/javascript/router.jsx"),
+            <<~'JS'
+              import React from "react";
+              import { createBrowserRouter } from "react-router-dom";
+
+              const router = createBrowserRouter([
+                { path: "/", element: <h1>Welcome</h1> }
+              ]);
+
+              export default router;
+            JS
+          )
+        end
+
+        def write_jsconfig(context)
+          jsconfig = {
+            "compilerOptions" => {
+              "baseUrl" => ".",
+              "paths" => {
+                "@/*" => [ "app/javascript/*" ]
+              }
+            }
+          }
+          File.write(File.join(context.app_path, "jsconfig.json"), JSON.pretty_generate(jsconfig))
+        end
+
+        def create_images_dir(context)
+          FileUtils.mkdir_p(File.join(context.app_path, "app/javascript/images"))
+        end
+      end
+    end
+  end
+end

data/lib/opinionated_rails/steps/core/testing_step.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  module Steps
+    module Core
+      class TestingStep < Step
+        def self.id = :testing
+        def self.summary = "Choose the test framework"
+        def self.description = "Prompts for RSpec or Minitest as the test framework."
+        def self.tier = :core
+        def self.prompts = "Test framework: RSpec or Minitest (default: Minitest)"
+
+        RSPEC_VERSION = "8.0.4".freeze
+
+        def prompt(context)
+          shell = context.shell
+          shell.say("Choose a test framework:")
+          shell.say("  1. Minitest")
+          shell.say("  2. RSpec")
+
+          choice = shell.ask("Test framework (default: Minitest):").to_s.strip
+          choice = "minitest" if choice.empty?
+
+          loop do
+            case choice.downcase
+            when "minitest", "1"
+              context.answer(:testing, :minitest)
+              break
+            when "rspec", "2"
+              context.answer(:testing, :rspec)
+              break
+            else
+              shell.say("Invalid. Enter 'Minitest', 'RSpec', 1, or 2.", :red)
+              choice = shell.ask("Test framework (default: Minitest):").to_s.strip
+              choice = "minitest" if choice.empty?
+            end
+          end
+        end
+
+        def generate(context)
+          framework = context.get(:testing)
+          raise ArgumentError, "No test framework answer" unless framework
+
+          context.set_output(:testing, { test_framework: framework })
+          install_rspec(context) if framework == :rspec
+        end
+
+        def outputs(context)
+          context.output(:testing)
+        end
+
+        private
+
+        def install_rspec(context)
+          gemfile = File.join(context.app_path, "Gemfile")
+          unless File.read(gemfile).include?("gem \"rspec-rails\"")
+            File.open(gemfile, "a") do |f|
+              f.puts("\ngroup :development, :test do\n  gem \"rspec-rails\", \"#{RSPEC_VERSION}\"\nend")
+            end
+          end
+
+          return if 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", "rspec:install") ||
+            raise(OpinionatedRails::Error, "rspec:install failed")
+        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
+      end
+    end
+  end
+end

data/lib/opinionated_rails/templates/docs/STYLE.md

@@ -0,0 +1,39 @@
+# Project Style Guide
+
+Conventions for this codebase. Follow the shape of existing code before inventing something new.
+
+## General
+
+- Ruby style is enforced by RuboCop. Run `bin/rubocop` (add `-a` to autocorrect) before committing. Do not disable cops inline without a comment explaining why.
+- Keep controllers thin: parse params, call one object, render or redirect. Put business rules in models or services.
+- Prefer small, named methods over long ones. Comment the *why*, not the *what*.
+
+## Services (if `app/services` exists)
+
+- Services inherit from `ApplicationService`, expose a single public `call`, and return a `Result`.
+- Call them as `MyService.call(...)`. Check `result.success?` / `result.failure?`; read `result.data` and `result.errors`.
+- Wrap multi-record writes in `transaction { ... }`. Add an error to the result to roll back.
+- Services must not render, redirect or touch `params`. Pass plain arguments in.
+
+## Models and database
+
+- Add database constraints (null, unique, foreign keys) and indexes in the migration, not only validations in the model.
+- Never edit a migration that has been merged. Add a new one.
+- Avoid N+1 queries: use `includes`/`preload` when iterating associations.
+
+## Testing
+
+- Every behaviour change ships with a test. Fix a bug by writing the failing test first.
+- Keep tests independent and deterministic. Do not hit real external services; stub or record them.
+- Run the full suite and `bin/rubocop` before opening a pull request.
+
+## Security
+
+- Never commit secrets. Use Rails credentials (`bin/rails credentials:edit`) or environment variables, and keep `.env*` files out of git.
+- Always use strong parameters. Never build SQL with string interpolation.
+- Run `bin/brakeman` and `bin/bundler-audit` regularly. CI should fail on new warnings.
+
+## Git and pull requests
+
+- Small, focused commits with imperative-mood messages ("Add invoice export").
+- Pull requests describe the problem, the approach and how it was verified.

data/lib/opinionated_rails/templates/github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Report a problem with the application
+title: "[Bug] "
+labels: bug
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+## Actual behavior
+
+## Environment
+
+- Version:
+- OS:

data/lib/opinionated_rails/templates/github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[Feature] "
+labels: enhancement
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed solution
+
+Describe the solution you'd like.
+
+## Alternatives considered
+

data/lib/opinionated_rails/templates/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Summary
+
+Describe what this PR changes and why.
+
+## Checklist
+
+- [ ] Tests added or updated
+- [ ] Documentation updated if needed
+- [ ] No unrelated changes included

data/lib/opinionated_rails/templates/rubocop/custom_overrides.yml

@@ -0,0 +1,5 @@
+# Example overrides — edit to taste after generation.
+#
+# Use `[a, [b, c]]` not `[ a, [ b, c ] ]`
+# Layout/SpaceInsideArrayLiteralBrackets:
+#   Enabled: false

data/lib/opinionated_rails/templates/services/application_service.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class ApplicationService
+  def self.call(params: {}, context: {}, **args)
+    new(params: params, context: context).call(**args)
+  end
+
+  attr_reader :result, :params, :context
+
+  def initialize(params: {}, context: {})
+    @params = params
+    @context = context
+    @result = Result.new
+  end
+
+  delegate :assign_data, to: :result
+  delegate :add_error, to: :result
+  delegate :success?, to: :result
+  delegate :failure?, to: :result
+  alias add_errors add_error
+
+  # Steps are usually private methods, so this deliberately uses send; never pass user input.
+  def step(method)
+    return unless success?
+
+    send(method)
+  end
+
+  def preload(*methods)
+    methods.map { |method| send(method) }
+  end
+
+  def call
+    raise NotImplementedError, "#call method must be implemented"
+  end
+
+  # Rolls back when the result has errors. ActiveRecord::Base.transaction swallows
+  # ActiveRecord::Rollback itself, and the errors are already on the result.
+  def transaction
+    ActiveRecord::Base.transaction do
+      yield
+      raise ActiveRecord::Rollback unless success?
+    end
+  end
+
+  ## Setup solidqueue first
+  # def self.call_async(params: {}, context: {})
+  #   AsyncJob.perform_later(name, params, context)
+  # end
+end

data/lib/opinionated_rails/templates/services/result.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class Result
+  attr_reader :errors, :data, :status
+
+  def self.failure(*errors, status: :unprocessable_entity)
+    new(errors: errors, status: status)
+  end
+
+  def self.success(data = nil, status: :ok)
+    new(data: data, status: status)
+  end
+
+  def initialize(errors: [], data: nil, status: :ok)
+    @errors = Array(errors)
+    @data = data
+    @status = status
+  end
+
+  def assign_data(object)
+    @data = object
+  end
+
+  def add_error(message, status_name = nil)
+    @status = status_name || :unprocessable_entity
+    if message.is_a?(Array)
+      @errors += message
+    else
+      @errors << message
+    end
+  end
+
+  def success?
+    !failure?
+  end
+
+  def failure?
+    errors.present? || status == :unprocessable_entity
+  end
+
+  def error_string
+    errors.compact.join(" ")
+  end
+end

data/lib/opinionated_rails/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpinionatedRails
+  VERSION = "0.1.4"
+end

data/lib/opinionated_rails.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+require "json"
+require "fileutils"
+require "tempfile"
+# Bundler.with_unbundled_env runs the generators outside this gem's own bundle; the constant is
+# not loaded when the installed gem runs without `bundle exec`.
+require "bundler"
+require "thor"
+
+# Templates and generated files contain non-ASCII (em dashes); a C/POSIX locale
+# (CI, Docker) would otherwise make File.read raise on them.
+Encoding.default_external = Encoding::UTF_8
+
+require_relative "opinionated_rails/version"
+require_relative "opinionated_rails/error"
+require_relative "opinionated_rails/context"
+require_relative "opinionated_rails/answer_shell"
+require_relative "opinionated_rails/step"
+require_relative "opinionated_rails/step_graph"
+require_relative "opinionated_rails/manifest"
+require_relative "opinionated_rails/rails_version_guard"
+require_relative "opinionated_rails/prerequisites"
+require_relative "opinionated_rails/kamal_config"
+require_relative "opinionated_rails/cli"
+require_relative "opinionated_rails/generators/rails_new_invoker"
+require_relative "opinionated_rails/generators/file_writer"
+
+Dir[File.expand_path("opinionated_rails/steps/**/*.rb", __dir__)].sort.each do |file|
+  require file
+end
+
+module OpinionatedRails
+  def self.step_classes
+    [ Steps::Core, Steps::Addons ].flat_map do |mod|
+      mod.constants.map { |name| mod.const_get(name) }
+    end
+  end
+end