rails_engine_toolkit 0.6.3

data/lib/rails_engine_toolkit/generators/install/install_generator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RailsEngineToolkit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      namespace 'engine_toolkit:install'
+
+      def create_config_file
+        require 'rails_engine_toolkit'
+
+        root_path = Pathname(destination_root)
+        slug_default = RailsEngineToolkit::Utils.repo_slug_from_path(root_path)
+        name_default = RailsEngineToolkit::Utils.humanize_slug(slug_default)
+
+        say_status :info, 'Creating engine toolkit configuration', :blue
+
+        project_slug = ask_with_default('Project slug', slug_default)
+        project_name = ask_with_default('Project name', name_default)
+        project_url = ask_with_default('Project URL', RailsEngineToolkit::Utils.git_remote_url.to_s)
+        author_name = ask_with_default('Author name', RailsEngineToolkit::Utils.git_config('user.name').to_s)
+        author_email = ask_with_default('Author email', RailsEngineToolkit::Utils.git_config('user.email').to_s)
+        database = ask_with_default('Default database adapter', 'postgresql')
+
+        api_only = yes?('Use API-only engines by default? [Y/n] ', :green)
+        skip_asset_pipeline = yes?('Skip asset pipeline by default? [Y/n] ', :green)
+        mount_routes = yes?('Mount engine routes automatically? [Y/n] ', :green)
+        create_ddd_structure = yes?('Create DDD folders by default? [Y/n] ', :green)
+
+        config_content = RailsEngineToolkit::Templates.render('engine_toolkit_yml', {
+                                                                project_slug: project_slug,
+                                                                project_name: project_name,
+                                                                project_url: project_url,
+                                                                author_name: author_name,
+                                                                author_email: author_email,
+                                                                database: database,
+                                                                api_only: api_only,
+                                                                skip_asset_pipeline: skip_asset_pipeline,
+                                                                mount_routes: mount_routes,
+                                                                create_ddd_structure: create_ddd_structure
+                                                              })
+
+        create_file 'config/engine_toolkit.yml', config_content
+
+        say ''
+        say 'Default configuration created:', :green
+        say "  project.slug: #{project_slug}"
+        say "  project.name: #{project_name}"
+        say "  defaults.database: #{database}"
+        say "  defaults.api_only: #{api_only}"
+        say "  defaults.mount_routes: #{mount_routes}"
+        say "  defaults.create_ddd_structure: #{create_ddd_structure}"
+        say ''
+        say 'Edit this file to customize the toolkit for your project:', :yellow
+        say "  #{File.join(destination_root, 'config/engine_toolkit.yml')}", :yellow
+      end
+
+      private
+
+      def ask_with_default(label, default)
+        value = ask("#{label} [#{default}]")
+        value.present? ? value : default
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/project.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  class Project
+    attr_reader :root
+
+    def initialize(root = Pathname.pwd)
+      @root = Pathname(root).expand_path
+    end
+
+    def validate_root!
+      raise ValidationError, 'You must run this command from the Rails project root.' unless gemfile.file?
+
+      true
+    end
+
+    def config
+      @config ||= Config.load(root)
+    end
+
+    def gemfile = root.join('Gemfile')
+    def routes_file = root.join('config/routes.rb')
+    def root_migrations_dir = root.join('db/migrate')
+    def config_file = root.join(Config::DEFAULT_PATH)
+
+    def engine_path(engine_name)
+      root.join("engines/#{engine_name}")
+    end
+
+    def engine_exists?(engine_name)
+      engine_path(engine_name).directory?
+    end
+
+    def broken_engine_references
+      return [] unless gemfile.file?
+
+      gemfile.read.lines.filter_map do |line|
+        match = line.match(%r{path:\s*["']engines/([^"']+)["']})
+        next unless match
+
+        engine_name = match[1]
+        engine_name unless engine_exists?(engine_name)
+      end.uniq
+    end
+
+    def remove_broken_engine_references!(engine_names)
+      return if engine_names.empty?
+
+      content = gemfile.read
+      engine_names.each do |name|
+        content = content.lines.grep_v(%r{path:\s*["']engines/#{Regexp.escape(name)}["']}).join
+      end
+      gemfile.write(content)
+    end
+
+    def route_inspector
+      return nil unless routes_file.file?
+
+      RouteInspector.new(routes_file.read)
+    end
+
+    def matching_root_migrations_for_engine(engine_name)
+      return [] unless root_migrations_dir.directory?
+
+      engine_class = Utils.classify(engine_name)
+      root_migrations_dir.glob('*.rb').select do |file|
+        file.read.include?(engine_class) || file.read.include?("#{engine_name}_")
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  class Railtie < Rails::Railtie
+    generators do
+      require_relative 'generators/install/install_generator'
+    end
+  end
+end

data/lib/rails_engine_toolkit/route_inspector.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  class RouteInspector
+    Mount = Struct.new(:engine_class, :path, :line)
+
+    def initialize(content)
+      @content = content
+    end
+
+    def mounts
+      return [] unless syntax_valid?
+
+      @content.lines.each_with_index.flat_map do |line, index|
+        extract_mounts_from_line(line, index + 1)
+      end
+    end
+
+    def includes_mount?(engine_class, path)
+      mounts.any? { |mount| mount.engine_class == engine_class && mount.path == path }
+    end
+
+    def syntax_valid?
+      !Ripper.sexp(@content).nil?
+    end
+
+    private
+
+    def extract_mounts_from_line(line, line_number)
+      patterns = [
+        /^\s*mount\s+([A-Z][A-Za-z0-9_:]+)::Engine,\s+at:\s+["']([^"']+)["']\s*$/,
+        /^\s*mount\(([^,]+)::Engine,\s*at:\s+["']([^"']+)["']\s*\)\s*$/,
+        /^\s*mount\s+([A-Z][A-Za-z0-9_:]+)::Engine\s*=>\s*["']([^"']+)["']\s*$/
+      ]
+
+      patterns.filter_map do |pattern|
+        match = line.match(pattern)
+        next unless match
+
+        Mount.new(engine_class: match[1], path: match[2], line: line_number)
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/routes_rewriter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  class RoutesRewriter
+    def initialize(path)
+      @path = Pathname(path)
+    end
+
+    def add_mount(engine_class:, mount_path:)
+      raise ValidationError, "Routes file not found: #{@path}" unless @path.file?
+
+      content = @path.read
+      inspector = RouteInspector.new(content)
+      return false if inspector.includes_mount?(engine_class, mount_path)
+
+      mount_line = %(  mount #{engine_class}::Engine, at: "#{mount_path}"\n)
+
+      updated = content.sub(/^(\s*Rails\.application\.routes\.draw do\s*\n)/) do |match|
+        "#{match}#{mount_line}"
+      end
+      raise CommandError, "Could not find Rails.application.routes.draw block in #{@path}" if updated == content
+
+      @path.write(updated)
+      true
+    end
+
+    def remove_mount(engine_class:, mount_path:)
+      raise ValidationError, "Routes file not found: #{@path}" unless @path.file?
+
+      original = @path.read
+      lines = original.lines.reject do |line|
+        mount_line?(line, engine_class: engine_class, mount_path: mount_path)
+      end
+      updated = lines.join
+      changed = updated != original
+      @path.write(updated) if changed
+      changed
+    end
+
+    private
+
+    def mount_line?(line, engine_class:, mount_path:)
+      regexes = [
+        mount_comma_regex(engine_class, mount_path),
+        mount_parenthesized_regex(engine_class, mount_path),
+        mount_hash_rocket_regex(engine_class, mount_path)
+      ]
+      regexes.any? { |regex| line.match?(regex) }
+    end
+
+    def mount_comma_regex(engine_class, mount_path)
+      /^\s*mount\s+#{Regexp.escape(engine_class)}::Engine,\s+at:\s+["']#{Regexp.escape(mount_path)}["']\s*$/
+    end
+
+    def mount_parenthesized_regex(engine_class, mount_path)
+      /^\s*mount\(\s*#{Regexp.escape(engine_class)}::Engine\s*,\s*at:\s+["']#{Regexp.escape(mount_path)}["']\s*\)\s*$/
+    end
+
+    def mount_hash_rocket_regex(engine_class, mount_path)
+      /^\s*mount\s+#{Regexp.escape(engine_class)}::Engine\s*=>\s*["']#{Regexp.escape(mount_path)}["']\s*$/
+    end
+  end
+end

data/lib/rails_engine_toolkit/templates/engine_readme.erb

@@ -0,0 +1,37 @@
+# <%= engine_class %>
+
+## Purpose
+<%= description %>
+
+## Responsibilities
+- Describe the main responsibilities of this bounded context.
+
+## Owned tables
+- None defined yet.
+
+## Public endpoints
+- None defined yet.
+
+## Integration points
+- None defined yet.
+
+## Dependencies
+- Rails
+- PostgreSQL
+
+## Commands
+
+### Generate a model
+```bash
+bundle exec engine-toolkit new_engine_model <%= engine_name %> example_entity name:string
+```
+
+### Generate a migration
+```bash
+bundle exec engine-toolkit new_engine_migration <%= engine_name %> CreateExampleEntities
+```
+
+### Update owned tables
+```bash
+bundle exec engine-toolkit update_engine_readme <%= engine_name %>
+```

data/lib/rails_engine_toolkit/templates/engine_toolkit_yml.erb

@@ -0,0 +1,35 @@
+project:
+  name: "<%= project_name %>"
+  slug: "<%= project_slug %>"
+  url: "<%= project_url %>"
+
+author:
+  name: "<%= author_name %>"
+  email: "<%= author_email %>"
+
+defaults:
+  database: "<%= database %>"
+  api_only: <%= api_only %>
+  skip_asset_pipeline: <%= skip_asset_pipeline %>
+  skip_action_mailbox: true
+  skip_action_text: true
+  skip_active_storage: true
+  skip_hotwire: true
+  skip_jbuilder: true
+  skip_system_test: true
+  mount_routes: <%= mount_routes %>
+  create_ddd_structure: <%= create_ddd_structure %>
+
+metadata:
+  license: "MIT"
+  ruby_version: ">= 3.2"
+  rails_version: ">= 8.1.2"
+
+ddd:
+  folders:
+    - app/use_cases
+    - app/services
+    - app/policies
+    - app/serializers
+    - app/repositories
+    - app/contracts

data/lib/rails_engine_toolkit/templates/gemspec.erb

@@ -0,0 +1,25 @@
+require_relative "lib/<%= engine_name %>/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "<%= engine_name %>"
+  spec.version     = <%= engine_class %>::VERSION
+  spec.authors     = ["<%= author_name %>"]
+  spec.email       = ["<%= author_email %>"]
+  spec.summary     = "<%= summary %>"
+  spec.description = "<%= description %>"
+
+  spec.homepage    = "<%= project_url %>"
+  spec.license     = "<%= license %>"
+
+  spec.required_ruby_version = "<%= ruby_version %>"
+
+  spec.metadata["homepage_uri"]     = spec.homepage
+  spec.metadata["source_code_uri"]  = "<%= project_url %>"
+  spec.metadata["changelog_uri"]    = "<%= project_url %>"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md"]
+  end
+
+  spec.add_dependency "rails", "<%= rails_version %>"
+end

data/lib/rails_engine_toolkit/templates/license.erb

@@ -0,0 +1,3 @@
+<%= license %> License
+
+Copyright (c) <%= year %> <%= author_name %>

data/lib/rails_engine_toolkit/templates.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Templates
+    module_function
+
+    def render(name, locals = {})
+      template = Pathname(__dir__).join("templates/#{name}.erb").read
+      ERB.new(template, trim_mode: '-').result_with_hash(locals)
+    end
+  end
+end

data/lib/rails_engine_toolkit/utils.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Utils
+    module_function
+
+    def snake_case?(value)
+      value.is_a?(String) && value.match?(/\A[a-z0-9_]+\z/)
+    end
+
+    def classify(snake_name)
+      snake_name.split('_').map(&:capitalize).join
+    end
+
+    def humanize_slug(slug)
+      slug.split('_').map(&:capitalize).join(' ')
+    end
+
+    def repo_slug_from_path(pathname)
+      File.basename(Pathname(pathname).expand_path.to_s)
+    end
+
+    def ask(prompt, default: nil, input: $stdin, output: $stdout)
+      shown = default.nil? || default.to_s.empty? ? "#{prompt}: " : "#{prompt} [#{default}]: "
+      output.print(shown)
+      answer = input.gets&.chomp
+      return default if answer.nil? || answer.empty?
+
+      answer
+    end
+
+    def ask_yes_no(prompt, default: false, input: $stdin, output: $stdout)
+      suffix = default ? ' [Y/n]: ' : ' [y/N]: '
+      output.print("#{prompt}#{suffix}")
+      answer = input.gets&.chomp.to_s.strip.downcase
+      return default if answer.empty?
+
+      %w[y yes].include?(answer)
+    end
+
+    def safe_system(*cmd, chdir:)
+      success = system(*cmd, chdir: chdir.to_s)
+      raise CommandError, "Command failed: #{cmd.join(' ')}" unless success
+    end
+
+    def git_config(key)
+      value = `git config #{key} 2>/dev/null`.to_s.strip
+      value.empty? ? nil : value
+    end
+
+    def git_remote_url
+      value = `git remote get-url origin 2>/dev/null`.to_s.strip
+      value.empty? ? nil : value
+    end
+  end
+end

data/lib/rails_engine_toolkit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  VERSION = '0.6.3'
+end

data/lib/rails_engine_toolkit.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'erb'
+require 'pathname'
+require 'fileutils'
+require 'thor'
+require 'ripper'
+
+require_relative 'rails_engine_toolkit/version'
+require_relative 'rails_engine_toolkit/errors'
+require_relative 'rails_engine_toolkit/utils'
+require_relative 'rails_engine_toolkit/config'
+require_relative 'rails_engine_toolkit/file_editor'
+require_relative 'rails_engine_toolkit/route_inspector'
+require_relative 'rails_engine_toolkit/routes_rewriter'
+require_relative 'rails_engine_toolkit/project'
+require_relative 'rails_engine_toolkit/templates'
+require_relative 'rails_engine_toolkit/actions/init'
+require_relative 'rails_engine_toolkit/actions/new_engine'
+require_relative 'rails_engine_toolkit/actions/update_engine_readme'
+require_relative 'rails_engine_toolkit/actions/new_engine_migration'
+require_relative 'rails_engine_toolkit/actions/delete_engine_migration'
+require_relative 'rails_engine_toolkit/actions/new_engine_model'
+require_relative 'rails_engine_toolkit/actions/install_engine_migrations'
+require_relative 'rails_engine_toolkit/actions/uninstall_engine_migrations'
+require_relative 'rails_engine_toolkit/actions/remove_engine'
+require_relative 'rails_engine_toolkit/cli'
+
+module RailsEngineToolkit
+end
+
+require_relative 'rails_engine_toolkit/railtie' if defined?(Rails::Railtie)

data/rails_engine_toolkit.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/rails_engine_toolkit/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'rails_engine_toolkit'
+  spec.version       = RailsEngineToolkit::VERSION
+  spec.authors       = ['Your Name']
+  spec.email         = ['you@example.com']
+
+  spec.summary       = 'Reusable CLI and generators for Rails engines'
+  spec.description   =
+    'Creates and manages internal Rails engines with configurable conventions, safe file mutations, parser-assisted route inspection, engine-specific migration installation, and Rails install generators.'
+  spec.homepage      = 'https://github.com/your-org/rails_engine_toolkit'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/releases"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.glob('{exe,lib,spec,test,docs,.github}/**/*') +
+               %w[README.md LICENSE.txt rails_engine_toolkit.gemspec Gemfile Rakefile]
+  spec.bindir = 'exe'
+  spec.executables = ['engine-toolkit']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'railties', '>= 8.1.0'
+  spec.add_dependency 'thor', '>= 1.3'
+end

data/spec/rails_engine_toolkit/cli_spec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RailsEngineToolkit::CLI do
+  it 'shows help for unknown commands' do
+    expect do
+      described_class.start(['unknown'])
+    end.to output(/Commands:/).to_stdout
+  end
+end

data/spec/rails_engine_toolkit/config_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RailsEngineToolkit::Config do
+  it 'loads valid configuration' do
+    in_tmpdir do |dir|
+      write(dir.join('config/engine_toolkit.yml'), <<~YAML)
+        project:
+          name: "Transport System"
+          slug: "transport_system"
+          url: "https://example.test/repo"
+        author:
+          name: "Juan"
+          email: "juan@example.com"
+        defaults:
+          database: "postgresql"
+          api_only: true
+          mount_routes: true
+          create_ddd_structure: true
+        metadata:
+          license: "MIT"
+          ruby_version: ">= 3.2"
+          rails_version: ">= 8.1.2"
+      YAML
+
+      config = described_class.load(dir)
+      expect(config.project_name).to eq('Transport System')
+      expect(config.project_slug).to eq('transport_system')
+    end
+  end
+
+  it 'rejects invalid database adapter' do
+    in_tmpdir do |dir|
+      write(dir.join('config/engine_toolkit.yml'), <<~YAML)
+        project:
+          name: "Transport System"
+          slug: "transport_system"
+          url: ""
+        author:
+          name: "Juan"
+          email: "juan@example.com"
+        defaults:
+          database: "oracle"
+        metadata:
+          license: "MIT"
+      YAML
+
+      expect { described_class.load(dir) }.to raise_error(RailsEngineToolkit::ValidationError, /defaults.database/)
+    end
+  end
+end

data/spec/rails_engine_toolkit/file_editor_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RailsEngineToolkit::FileEditor do
+  it 'removes matching lines safely' do
+    in_tmpdir do |dir|
+      path = dir.join('routes.rb')
+      write(path, "a\nb\nc\n")
+      changed = described_class.remove_lines_matching(path, /^b$/)
+      expect(changed).to be(true)
+      expect(path.read).to eq("a\nc\n")
+    end
+  end
+
+  it 'inserts content after first match' do
+    in_tmpdir do |dir|
+      path = dir.join('routes.rb')
+      write(path, "Rails.application.routes.draw do\nend\n")
+      changed = described_class.insert_after_first_match(path, /Rails\.application\.routes\.draw do\s*\n/,
+                                                         "  mount Auth::Engine, at: \"/auth\"\n")
+      expect(changed).to be(true)
+      expect(path.read).to include('mount Auth::Engine, at: "/auth"')
+    end
+  end
+end

data/spec/rails_engine_toolkit/install_engine_migrations_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RailsEngineToolkit::Actions::InstallEngineMigrations do
+  it 'copies only the selected engine migrations into root db/migrate' do
+    in_tmpdir do |dir|
+      write(dir.join('Gemfile'), "source \"https://rubygems.org\"\n")
+      write(dir.join('engines/auth/db/migrate/20260101000000_create_auth_credentials.rb'),
+            'class CreateAuthCredentials; end')
+      write(dir.join('engines/billing/db/migrate/20260101000001_create_billing_invoices.rb'),
+            'class CreateBillingInvoices; end')
+
+      out = StringIO.new
+      described_class.new(['auth'], stdin: StringIO.new, stdout: out, stderr: StringIO.new, root: dir).call
+
+      root_migrations = dir.join('db/migrate').glob('*.rb').map { |f| f.basename.to_s }
+      expect(root_migrations.any? { |name| name.end_with?('create_auth_credentials.rb') }).to be(true)
+      expect(root_migrations.any? { |name| name.end_with?('create_billing_invoices.rb') }).to be(false)
+    end
+  end
+
+  it 'does not duplicate already installed migrations' do
+    in_tmpdir do |dir|
+      write(dir.join('Gemfile'), "source \"https://rubygems.org\"\n")
+      write(dir.join('engines/auth/db/migrate/20260101000000_create_auth_credentials.rb'),
+            'class CreateAuthCredentials; end')
+      write(dir.join('db/migrate/20260102000000_create_auth_credentials.rb'), 'class CreateAuthCredentials; end')
+
+      out = StringIO.new
+      described_class.new(['auth'], stdin: StringIO.new, stdout: out, stderr: StringIO.new, root: dir).call
+
+      expect(out.string).to include('No new migrations')
+    end
+  end
+end

data/spec/rails_engine_toolkit/install_generator_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'rails_engine_toolkit/generators/install/install_generator'
+
+RSpec.describe RailsEngineToolkit::Generators::InstallGenerator do
+  it 'creates config and prints summary in a host app' do
+    in_tmpdir do |dir|
+      write(dir.join('Gemfile'), "source \"https://rubygems.org\"\n")
+
+      generator = described_class.new
+      allow(generator).to receive(:destination_root).and_return(dir.to_s)
+      allow(generator).to receive(:ask).and_return('', '', '', '', '', 'postgresql')
+      allow(generator).to receive(:yes?).and_return(true, true, true, true)
+      output = StringIO.new
+      allow(generator).to receive(:say) { |message = '', *_args| output.puts(message) }
+      allow(generator).to receive(:say_status) { |_status, message, *_args| output.puts(message) }
+
+      generator.create_config_file
+
+      expect(dir.join('config/engine_toolkit.yml')).to exist
+      expect(output.string).to include('Default configuration created:')
+      expect(output.string).to include('config/engine_toolkit.yml')
+    end
+  end
+end