rails_engine_toolkit 0.6.3

data/lib/rails_engine_toolkit/actions/new_engine.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Actions
+    class NewEngine
+      def initialize(argv, stdin:, stdout:, root:, stderr: nil)
+        @engine_name = argv[0]
+        @stdin = stdin
+        @stdout = stdout
+        @stderr = stderr
+        @root = Pathname(root)
+        @project = Project.new(@root)
+      end
+
+      def call
+        @project.validate_root!
+        validate_engine_name!
+
+        config = @project.config
+        handle_broken_references!
+        ensure_engine_does_not_exist!
+
+        description = prompt_description(config.project_name)
+        engine_class = Utils.classify(@engine_name)
+
+        generate_engine!(config)
+        rewrite_engine_files!(config, description, engine_class)
+        create_ddd_structure!(config)
+        mount_engine_route(engine_class) if config.mount_routes?
+        Utils.safe_system('bundle', 'install', chdir: @root)
+
+        @stdout.puts("Engine created: engines/#{@engine_name}")
+      end
+
+      private
+
+      def validate_engine_name!
+        raise ValidationError, 'Engine name is required.' if @engine_name.to_s.empty?
+        raise ValidationError, 'Engine name must be snake_case.' unless Utils.snake_case?(@engine_name)
+      end
+
+      def handle_broken_references!
+        broken = @project.broken_engine_references
+        return if broken.empty?
+
+        message = "Broken engine references found in Gemfile (#{broken.join(', ')}). Remove them automatically?"
+        remove = Utils.ask_yes_no(
+          message,
+          default: false,
+          input: @stdin,
+          output: @stdout
+        )
+        raise ValidationError, 'Please fix the Gemfile before creating a new engine.' unless remove
+
+        @project.remove_broken_engine_references!(broken)
+      end
+
+      def ensure_engine_does_not_exist!
+        engine_path = @project.engine_path(@engine_name)
+        raise ValidationError, "Engine already exists: #{engine_path}" if engine_path.exist?
+      end
+
+      def prompt_description(project_name)
+        default = "Provides #{@engine_name} domain for #{project_name}"
+        Utils.ask('Engine description', default: default, input: @stdin, output: @stdout)
+      end
+
+      def generate_engine!(config)
+        args = ['bundle', 'exec', 'rails', 'plugin', 'new', "engines/#{@engine_name}", '--mountable', '-d',
+                config.default_database]
+        args << '--api' if config.api_only?
+        args.concat(config.skip_flags)
+        Utils.safe_system(*args, chdir: @root)
+      end
+
+      def rewrite_engine_files!(config, description, engine_class)
+        engine_path = @project.engine_path(@engine_name)
+        engine_path.join('Gemfile').write("source \"https://rubygems.org\"\n\ngemspec\n")
+        engine_path.join("#{@engine_name}.gemspec").write(
+          Templates.render(
+            'gemspec',
+            engine_name: @engine_name,
+            engine_class: engine_class,
+            author_name: config.author_name,
+            author_email: config.author_email,
+            summary: "#{engine_class} domain engine",
+            description: description,
+            project_url: config.project_url,
+            ruby_version: config.ruby_version,
+            rails_version: config.rails_version,
+            license: config.license
+          )
+        )
+        engine_path.join('MIT-LICENSE').write(
+          Templates.render(
+            'license',
+            year: Time.now.year,
+            author_name: config.author_name,
+            license: config.license
+          )
+        )
+        engine_path.join('README.md').write(
+          Templates.render(
+            'engine_readme',
+            engine_name: @engine_name,
+            engine_class: engine_class,
+            description: description
+          )
+        )
+      end
+
+      def create_ddd_structure!(config)
+        return unless config.create_ddd_structure?
+
+        engine_path = @project.engine_path(@engine_name)
+        config.ddd_folders.each { |folder| FileUtils.mkdir_p(engine_path.join(folder)) }
+      end
+
+      def mount_engine_route(engine_class)
+        return unless @project.routes_file.file?
+
+        rewriter = RoutesRewriter.new(@project.routes_file)
+        rewriter.add_mount(engine_class: engine_class, mount_path: "/#{@engine_name}")
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/actions/new_engine_migration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Actions
+    class NewEngineMigration
+      def initialize(argv, stdout:, root:, stdin: nil, stderr: nil)
+        @engine_name = argv.shift
+        @generator_args = argv
+        @stdout = stdout
+        @stdin = stdin
+        @stderr = stderr
+        @root = Pathname(root)
+        @project = Project.new(@root)
+      end
+
+      def call
+        @project.validate_root!
+        raise ValidationError, 'Engine name is required.' if @engine_name.to_s.empty?
+        raise ValidationError, 'Migration name is required.' if @generator_args.empty?
+
+        engine_path = @project.engine_path(@engine_name)
+        raise ValidationError, "Engine does not exist: #{engine_path}" unless engine_path.directory?
+
+        Utils.safe_system('bin/rails', 'g', 'migration', *@generator_args, chdir: engine_path)
+        UpdateEngineReadme.new([@engine_name], stdin: nil, stdout: @stdout, stderr: nil, root: @root).call
+        @stdout.puts("Migration created inside #{engine_path}")
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/actions/new_engine_model.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Actions
+    class NewEngineModel
+      def initialize(argv, stdout:, root:, stdin: nil, stderr: nil)
+        @engine_name = argv.shift
+        @generator_args = argv
+        @stdout = stdout
+        @stdin = stdin
+        @stderr = stderr
+        @root = Pathname(root)
+        @project = Project.new(@root)
+      end
+
+      def call
+        @project.validate_root!
+        raise ValidationError, 'Engine name is required.' if @engine_name.to_s.empty?
+        raise ValidationError, 'Model name is required.' if @generator_args.empty?
+
+        engine_path = @project.engine_path(@engine_name)
+        raise ValidationError, "Engine does not exist: #{engine_path}" unless engine_path.directory?
+
+        Utils.safe_system('bin/rails', 'g', 'model', *@generator_args, chdir: engine_path)
+        UpdateEngineReadme.new([@engine_name], stdin: nil, stdout: @stdout, stderr: nil, root: @root).call
+        @stdout.puts("Model created inside #{engine_path}")
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/actions/remove_engine.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Actions
+    class RemoveEngine
+      def initialize(argv, stdin:, stdout:, root:, stderr: nil)
+        @engine_name = argv[0]
+        @stdin = stdin
+        @stdout = stdout
+        @stderr = stderr
+        @root = Pathname(root)
+        @project = Project.new(@root)
+      end
+
+      def call
+        @project.validate_root!
+        validate_engine!
+
+        warn_if_root_migrations_exist!
+        confirm_deletion!
+
+        remove_mounts
+        remove_gemfile_entry
+        FileUtils.rm_rf(@project.engine_path(@engine_name))
+        Utils.safe_system('bundle', 'install', chdir: @root)
+        @stdout.puts("Removed engine: #{@engine_name}")
+      end
+
+      private
+
+      def validate_engine!
+        raise ValidationError, 'Engine name is required.' if @engine_name.to_s.empty?
+        raise ValidationError, 'Engine name must be snake_case.' unless Utils.snake_case?(@engine_name)
+
+        engine_path = @project.engine_path(@engine_name)
+        raise ValidationError, "Engine does not exist: #{engine_path}" unless engine_path.directory?
+      end
+
+      def warn_if_root_migrations_exist!
+        installed = @project.matching_root_migrations_for_engine(@engine_name)
+        return if installed.empty?
+
+        proceed = Utils.ask_yes_no(
+          'Root migrations may belong to this engine. Continue anyway?',
+          default: false,
+          input: @stdin,
+          output: @stdout
+        )
+        raise ValidationError, 'Operation aborted.' unless proceed
+      end
+
+      def confirm_deletion!
+        confirmed = Utils.ask(
+          "Type '#{@engine_name}' to confirm deletion",
+          input: @stdin,
+          output: @stdout
+        )
+        raise ValidationError, 'Operation aborted.' unless confirmed == @engine_name
+      end
+
+      def remove_mounts
+        return unless @project.routes_file.file?
+
+        RoutesRewriter.new(@project.routes_file).remove_mount(
+          engine_class: Utils.classify(@engine_name),
+          mount_path: "/#{@engine_name}"
+        )
+      end
+
+      def remove_gemfile_entry
+        FileEditor.remove_lines_matching(
+          @project.gemfile,
+          %r{path:\s*["']engines/#{Regexp.escape(@engine_name)}["']}
+        )
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/actions/uninstall_engine_migrations.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Actions
+    class UninstallEngineMigrations
+      def initialize(argv, stdin:, stdout:, root:, stderr: nil)
+        @engine_name = argv[0]
+        @stdin = stdin
+        @stdout = stdout
+        @stderr = stderr
+        @root = Pathname(root)
+        @project = Project.new(@root)
+      end
+
+      def call
+        @project.validate_root!
+        validate_engine!
+
+        root_matches = matching_root_migrations
+        if root_matches.empty?
+          @stdout.puts("No installed root migrations found for engine '#{@engine_name}'.")
+          return
+        end
+
+        print_matches(root_matches)
+        confirm_uninstall!
+        root_matches.each(&:delete)
+
+        @stdout.puts("Removed #{root_matches.size} root migration file(s) for engine '#{@engine_name}'.")
+      end
+
+      private
+
+      def validate_engine!
+        raise ValidationError, 'Engine name is required.' if @engine_name.to_s.empty?
+        raise ValidationError, 'Engine name must be snake_case.' unless Utils.snake_case?(@engine_name)
+
+        engine_path = @project.engine_path(@engine_name)
+        migrations_dir = engine_path.join('db/migrate')
+        raise ValidationError, "Engine does not exist: #{engine_path}" unless engine_path.directory?
+
+        return if migrations_dir.directory?
+
+        raise ValidationError,
+              "Engine migrations directory not found: #{migrations_dir}"
+      end
+
+      def matching_root_migrations
+        return [] unless @project.root_migrations_dir.directory?
+
+        engine_basenames = @project.engine_path(@engine_name).join('db/migrate').glob('*.rb').map do |file|
+          file.basename.to_s.sub(/^\d+_/, '')
+        end.sort
+
+        @project.root_migrations_dir.glob('*.rb').select do |file|
+          engine_basenames.include?(file.basename.to_s.sub(/^\d+_/, ''))
+        end.sort
+      end
+
+      def print_matches(root_matches)
+        @stdout.puts("The following root migrations match engine '#{@engine_name}':")
+        root_matches.each { |file| @stdout.puts("  #{file.relative_path_from(@root)}") }
+        @stdout.puts('')
+        @stdout.puts('This only removes copied migration files from db/migrate.')
+        @stdout.puts('It does NOT rollback the database automatically.')
+        @stdout.puts('Run your rollback or down migrations manually if needed.')
+      end
+
+      def confirm_uninstall!
+        confirmed = Utils.ask(
+          "Type '#{@engine_name}' to confirm uninstall",
+          input: @stdin,
+          output: @stdout
+        )
+        raise ValidationError, 'Operation aborted.' unless confirmed == @engine_name
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/actions/update_engine_readme.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Actions
+    class UpdateEngineReadme
+      def initialize(argv, stdout:, root:, stdin: nil, stderr: nil)
+        @engine_name = argv[0]
+        @stdout = stdout
+        @stdin = stdin
+        @stderr = stderr
+        @root = Pathname(root)
+        @project = Project.new(@root)
+      end
+
+      def call
+        @project.validate_root!
+        validate_args!
+
+        engine_path = @project.engine_path(@engine_name)
+        readme = engine_path.join('README.md')
+        migrations_dir = engine_path.join('db/migrate')
+
+        raise ValidationError, "README not found: #{readme}" unless readme.file?
+
+        owned_tables_block = tables_from(migrations_dir).then do |tables|
+          tables.empty? ? '- None defined yet.' : tables.map { |table| "- #{table}" }.join("\n")
+        end
+
+        content = readme.read
+        unless content.match?(/^## Owned tables$/)
+          raise ValidationError,
+                "Could not find '## Owned tables' section in #{readme}"
+        end
+
+        updated = content.sub(/^## Owned tables$.*?(?=^## |\z)/m, "## Owned tables\n#{owned_tables_block}\n\n")
+        readme.write(updated)
+
+        @stdout.puts("Updated README: #{readme}")
+      end
+
+      private
+
+      def validate_args!
+        raise ValidationError, 'Engine name is required.' if @engine_name.to_s.empty?
+        raise ValidationError, 'Engine name must be snake_case.' unless Utils.snake_case?(@engine_name)
+
+        engine_path = @project.engine_path(@engine_name)
+        raise ValidationError, "Engine does not exist: #{engine_path}" unless engine_path.directory?
+      end
+
+      def tables_from(migrations_dir)
+        return [] unless migrations_dir.directory?
+
+        migrations_dir.glob('*.rb').flat_map do |file|
+          file.read.scan(/create_table\s+:?"?([a-zA-Z0-9_]+)"?/).flatten
+        end.uniq.sort
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/cli.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  class CLI < Thor
+    class_option :root, type: :string
+
+    KNOWN_COMMANDS = %w[
+      help
+      init
+      new_engine
+      update_engine_readme
+      new_engine_migration
+      delete_engine_migration
+      new_engine_model
+      install_engine_migrations
+      uninstall_engine_migrations
+      remove_engine
+    ].freeze
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'init', 'Create config/engine_toolkit.yml'
+    def init
+      run_action(Actions::Init, [])
+    end
+
+    desc 'new_engine ENGINE_NAME', 'Create a new internal Rails engine'
+    def new_engine(engine_name)
+      run_action(Actions::NewEngine, [engine_name])
+    end
+
+    desc 'update_engine_readme ENGINE_NAME', 'Refresh the README owned tables section'
+    def update_engine_readme(engine_name)
+      run_action(Actions::UpdateEngineReadme, [engine_name])
+    end
+
+    desc 'new_engine_migration ENGINE_NAME MIGRATION_NAME [ARGS...]', 'Create a migration inside an engine'
+    def new_engine_migration(engine_name, migration_name, *args)
+      run_action(Actions::NewEngineMigration, [engine_name, migration_name, *args])
+    end
+
+    desc 'delete_engine_migration ENGINE_NAME PATTERN', 'Delete matching engine migration files'
+    def delete_engine_migration(engine_name, pattern)
+      run_action(Actions::DeleteEngineMigration, [engine_name, pattern])
+    end
+
+    desc 'new_engine_model ENGINE_NAME MODEL_NAME [ATTRS...]', 'Create a model inside an engine'
+    def new_engine_model(engine_name, model_name, *attrs)
+      run_action(Actions::NewEngineModel, [engine_name, model_name, *attrs])
+    end
+
+    desc 'install_engine_migrations ENGINE_NAME', "Copy only one engine's migrations into the host app"
+    def install_engine_migrations(engine_name)
+      run_action(Actions::InstallEngineMigrations, [engine_name])
+    end
+
+    desc 'uninstall_engine_migrations ENGINE_NAME', 'Remove root migrations that were installed from one engine'
+    def uninstall_engine_migrations(engine_name)
+      run_action(Actions::UninstallEngineMigrations, [engine_name])
+    end
+
+    desc 'remove_engine ENGINE_NAME', 'Remove an internal engine'
+    def remove_engine(engine_name)
+      run_action(Actions::RemoveEngine, [engine_name])
+    end
+
+    def self.start(argv)
+      first = argv.first
+      if first && !first.start_with?('-') && !KNOWN_COMMANDS.include?(first)
+        puts(command_help_text)
+        return 1
+      end
+
+      super
+      0
+    rescue Error => e
+      warn("Error: #{e.message}")
+      1
+    end
+
+    def self.command_help_text
+      <<~TEXT
+        Commands:
+          init
+          new_engine ENGINE_NAME
+          update_engine_readme ENGINE_NAME
+          new_engine_migration ENGINE_NAME MIGRATION_NAME [ARGS...]
+          delete_engine_migration ENGINE_NAME PATTERN
+          new_engine_model ENGINE_NAME MODEL_NAME [ATTRS...]
+          install_engine_migrations ENGINE_NAME
+          uninstall_engine_migrations ENGINE_NAME
+          remove_engine ENGINE_NAME
+      TEXT
+    end
+
+    private
+
+    def run_action(klass, argv)
+      klass.new(
+        argv,
+        stdin: $stdin,
+        stdout: $stdout,
+        stderr: $stderr,
+        root: options[:root] || Pathname.pwd
+      ).call
+    end
+  end
+end

data/lib/rails_engine_toolkit/config.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  class Config
+    DEFAULT_PATH = 'config/engine_toolkit.yml'
+
+    REQUIRED_TOP_LEVEL_KEYS = %w[project author defaults metadata].freeze
+    VALID_DATABASES = %w[postgresql mysql2 sqlite3].freeze
+    DEFAULT_DDD_FOLDERS = [
+      'app/use_cases',
+      'app/services',
+      'app/policies',
+      'app/serializers',
+      'app/repositories',
+      'app/contracts'
+    ].freeze
+    SKIP_FLAG_MAPPING = {
+      'skip_asset_pipeline' => '--skip-asset-pipeline',
+      'skip_action_mailbox' => '--skip-action-mailbox',
+      'skip_action_text' => '--skip-action-text',
+      'skip_active_storage' => '--skip-active-storage',
+      'skip_hotwire' => '--skip-hotwire',
+      'skip_jbuilder' => '--skip-jbuilder',
+      'skip_system_test' => '--skip-system-test'
+    }.freeze
+
+    attr_reader :data
+
+    def self.load(project_root, path: DEFAULT_PATH)
+      full_path = Pathname(project_root).join(path)
+      raise ValidationError, "Configuration file not found: #{full_path}" unless full_path.exist?
+
+      new(YAML.safe_load(full_path.read, aliases: true) || {}, path: full_path).tap(&:validate!)
+    end
+
+    def initialize(data, path:)
+      @data = data
+      @path = path
+    end
+
+    def validate!
+      REQUIRED_TOP_LEVEL_KEYS.each do |key|
+        raise ValidationError, "Missing config section: #{key} in #{@path}" unless data.key?(key)
+      end
+
+      validate_string('project', 'name')
+      validate_string('project', 'slug')
+      validate_string('author', 'name')
+      validate_string('author', 'email')
+
+      raise ValidationError, 'project.slug must be snake_case' unless Utils.snake_case?(project_slug)
+      return true if VALID_DATABASES.include?(default_database)
+
+      raise ValidationError, "defaults.database must be one of: #{VALID_DATABASES.join(', ')}"
+    end
+
+    def project_name = fetch('project', 'name')
+    def project_slug = fetch('project', 'slug')
+    def project_url = fetch('project', 'url', default: '')
+    def author_name = fetch('author', 'name')
+    def author_email = fetch('author', 'email')
+    def license = fetch('metadata', 'license', default: 'MIT')
+    def ruby_version = fetch('metadata', 'ruby_version', default: '>= 3.2')
+    def rails_version = fetch('metadata', 'rails_version', default: '>= 8.1.2')
+    def default_database = fetch('defaults', 'database', default: 'postgresql')
+    def api_only? = !!fetch('defaults', 'api_only', default: true)
+    def mount_routes? = !!fetch('defaults', 'mount_routes', default: true)
+    def create_ddd_structure? = !!fetch('defaults', 'create_ddd_structure', default: true)
+
+    def skip_flags
+      defaults = data.fetch('defaults', {})
+      SKIP_FLAG_MAPPING.filter_map do |key, flag|
+        flag if defaults.fetch(key, true)
+      end
+    end
+
+    def ddd_folders
+      fetch('ddd', 'folders', default: DEFAULT_DDD_FOLDERS)
+    end
+
+    private
+
+    def validate_string(*keys)
+      value = fetch(*keys)
+      raise ValidationError, "Missing config value: #{keys.join('.')}" if value.to_s.strip.empty?
+    end
+
+    def fetch(*keys, default: nil)
+      cursor = data
+      keys.each do |key|
+        return default unless cursor.is_a?(Hash) && cursor.key?(key)
+
+        cursor = cursor[key]
+      end
+      cursor.nil? ? default : cursor
+    end
+  end
+end

data/lib/rails_engine_toolkit/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  class Error < StandardError; end
+  class ValidationError < Error; end
+  class CommandError < Error; end
+end

data/lib/rails_engine_toolkit/file_editor.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  class FileEditor
+    def self.remove_lines_matching(path, regex)
+      return false unless path.exist?
+
+      original = path.read
+      updated = original.lines.grep_v(regex).join
+      changed = original != updated
+      path.write(updated) if changed
+      changed
+    end
+
+    def self.insert_after_first_match(path, match_regex, text)
+      content = path.read
+      updated = content.sub(match_regex) { |m| "#{m}#{text}" }
+      changed = updated != content
+      path.write(updated) if changed
+      changed
+    end
+
+    def self.ensure_line_after_draw_block(path, line)
+      return false unless path.exist?
+
+      content = path.read
+      return false if content.include?(line.strip)
+
+      updated = content.sub(/Rails\.application\.routes\.draw do\s*\n/, "Rails.application.routes.draw do\n#{line}")
+      changed = updated != content
+      path.write(updated) if changed
+      changed
+    end
+
+    def self.copy_file(path_from, path_to)
+      FileUtils.mkdir_p(path_to.dirname)
+      FileUtils.cp(path_from, path_to)
+    end
+  end
+end