rails_engine_toolkit 0.6.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2daf757686e083799345227ffbacbb0fe9d53915f764a82320049f23202aab1f
+  data.tar.gz: d0e663fa492f7f6f2992cd0b2f9ad7ec6e80c1c772baf385f4537410461b407e
+SHA512:
+  metadata.gz: b03b80e939f4e62b57471509c80241b4e7ca2157f8db29a6c7ae8b38e79df651633839bd50135546234418076b9d89f3e1c4de17a58b490372b54a81a440915c
+  data.tar.gz: c537ed36c0a79ac052eadeb992f38ddb5fcb526d5f057f855708feeee988b30188e704ed95f7a59318fd5742ec70e03b995d4230ac13b899092e8c9ef461e183

data/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  rspec:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3"]
+        rails: ["8.1.2"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle install
+      - run: bundle exec rspec
+      - run: bundle exec rubocop
+
+  host-app-smoke:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3"]
+        rails: ["8.1.2"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - run: gem install rails -v ${{ matrix.rails }}
+      - run: bundle install
+      - run: |
+          cp -R test/fixtures/host_app /tmp/host_app
+          cd /tmp/host_app
+          bundle config set local.rails_engine_toolkit "$GITHUB_WORKSPACE"
+          bundle install
+          bundle exec rails generate engine_toolkit:install <<'EOF'
+
+
+
+
+
+
+EOF
+          bundle exec engine-toolkit new_engine auth <<'EOF'
+
+EOF

data/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+      - run: gem build rails_engine_toolkit.gemspec
+      - run: gem push *.gem
+        env:
+          RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.72', require: false
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# Rails Engine Toolkit
+
+Reusable tooling for Rails projects that use internal engines.
+
+## What this gem provides
+
+- `rails generate engine_toolkit:install`
+- `engine-toolkit init`
+- `engine-toolkit new_engine ENGINE_NAME`
+- `engine-toolkit new_engine_model ENGINE_NAME MODEL_NAME [ATTRS...]`
+- `engine-toolkit new_engine_migration ENGINE_NAME MIGRATION_NAME [ATTRS...]`
+- `engine-toolkit install_engine_migrations ENGINE_NAME`
+- `engine-toolkit uninstall_engine_migrations ENGINE_NAME`
+- `engine-toolkit delete_engine_migration ENGINE_NAME PATTERN`
+- `engine-toolkit update_engine_readme ENGINE_NAME`
+- `engine-toolkit remove_engine ENGINE_NAME`
+
+## What is new in v6.3
+
+- RuboCop cleanup and sane project-level RuboCop configuration
+- action classes split into smaller private helpers where useful
+- long lines and unused arguments fixed
+- packaging polish for a cleaner public repository
+
+## Installation in a host Rails app
+
+```ruby
+gem "rails_engine_toolkit"
+```
+
+Then:
+
+```bash
+bundle install
+bin/rails generate engine_toolkit:install
+```
+
+The install generator creates:
+
+```text
+config/engine_toolkit.yml
+```
+
+and prints:
+
+- the generated default configuration
+- the full path of the file you should edit
+
+## CLI usage
+
+```bash
+bundle exec engine-toolkit new_engine auth
+bundle exec engine-toolkit new_engine_model auth credential email:string
+bundle exec engine-toolkit new_engine_migration auth CreateCredentials
+bundle exec engine-toolkit install_engine_migrations auth
+bundle exec engine-toolkit uninstall_engine_migrations auth
+bundle exec engine-toolkit update_engine_readme auth
+bundle exec engine-toolkit delete_engine_migration auth create_credentials
+bundle exec engine-toolkit remove_engine auth
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Publishing to RubyGems
+
+```bash
+gem build rails_engine_toolkit.gemspec
+gem push rails_engine_toolkit-0.6.3.gem
+```
+
+After it is published, consumers can install it with:
+
+```ruby
+gem "rails_engine_toolkit"
+```
+
+without `github:` or `path:`.

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/ARCHITECTURE.md

@@ -0,0 +1,18 @@
+# Architecture
+
+## Main components
+
+- `CLI`: command entrypoint powered by Thor
+- `Project`: host app path and mutation helper
+- `Config`: validated project configuration loader
+- `FileEditor`: small safe file mutation helpers
+- `Templates`: ERB renderer for generated content
+- `Actions::*`: business operations
+
+## Rails integration
+
+The gem ships a Railtie and a generator:
+
+- `rails generate engine_toolkit:install`
+
+That keeps the install experience close to tools such as `rspec:install`. The install generator creates the configuration file and prints a summary plus the exact path to edit.

data/docs/COMPATIBILITY.md

@@ -0,0 +1,18 @@
+# Compatibility strategy
+
+## Rails support
+
+The gem is intended to support Rails 8.1.x first.
+
+## Verification approach
+
+Compatibility is checked at four levels:
+
+1. unit specs
+2. integration-style specs on temporary directories
+3. install generator smoke test in a dummy host app fixture
+4. CI matrix across supported Ruby and Rails versions
+
+## Important limitation
+
+A true dynamic matrix that creates full temporary Rails apps at runtime is possible, but is best executed in CI rather than lightweight local scaffolding environments.

data/docs/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+## Local setup
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Main principles
+
+- keep project mutations explicit
+- prefer small action classes
+- keep route handling readable and testable
+- avoid hidden side effects during install and engine generation
+- prefer configuration over hardcoded project metadata
+
+## Test expectations
+
+Before opening a pull request, run:
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```

data/docs/END_TO_END.md

@@ -0,0 +1,26 @@
+# End-to-end smoke test
+
+A lightweight host app fixture is included under `test/fixtures/host_app`.
+
+## Typical smoke workflow
+
+From a temporary Rails app or the fixture app:
+
+```bash
+bundle install
+bin/rails generate engine_toolkit:install
+bundle exec engine-toolkit new_engine auth
+bundle exec engine-toolkit new_engine_model auth credential email:string
+bundle exec engine-toolkit install_engine_migrations auth
+bin/rails db:migrate
+```
+
+## Migration uninstall note
+
+If you later run:
+
+```bash
+bundle exec engine-toolkit uninstall_engine_migrations auth
+```
+
+the toolkit removes copied files from `db/migrate`, but it does **not** rollback the database automatically. Run your down/rollback flow manually first if needed.

data/docs/PUBLISHING.md

@@ -0,0 +1,24 @@
+# Publishing
+
+## Publish to RubyGems
+
+Create an account on RubyGems.org, then:
+
+```bash
+gem build rails_engine_toolkit.gemspec
+gem push rails_engine_toolkit-0.6.2.gem
+```
+
+Consumers can then use:
+
+```ruby
+gem "rails_engine_toolkit"
+```
+
+instead of `github:` or `path:`.
+
+## Trusted publishing
+
+You can also set up GitHub Actions with trusted publishing so that releases push automatically after tagging.
+
+See the RubyGems publishing guide and trusted publishing guide.

data/docs/RELEASE.md

@@ -0,0 +1,32 @@
+# Release workflow
+
+## Local release
+
+1. Update `lib/rails_engine_toolkit/version.rb`
+2. Commit your changes
+3. Tag the release
+4. Build and push the gem
+
+```bash
+gem build rails_engine_toolkit.gemspec
+gem push rails_engine_toolkit-0.3.0.gem
+git tag v0.3.0
+git push origin v0.3.0
+```
+
+## GitHub Actions release
+
+This repository includes a RubyGems release workflow template.
+
+### Required secret
+
+- `RUBYGEMS_API_KEY`
+
+### Trigger
+
+Push a version tag such as:
+
+```bash
+git tag v0.3.0
+git push origin v0.3.0
+```

data/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,49 @@
+# Release checklist
+
+## Before releasing
+
+- Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+- Run the linter:
+
+```bash
+bundle exec rubocop
+```
+
+- Verify the gem builds:
+
+```bash
+gem build rails_engine_toolkit.gemspec
+```
+
+- Review:
+  - `README.md`
+  - `docs/PUBLISHING.md`
+  - `docs/RELEASE.md`
+  - `lib/rails_engine_toolkit/version.rb`
+
+## Release steps
+
+1. Bump the version in `lib/rails_engine_toolkit/version.rb`
+2. Commit the changes
+3. Tag the release
+4. Push the tag
+5. Publish the gem manually or through GitHub Actions
+
+## Manual publish
+
+```bash
+gem build rails_engine_toolkit.gemspec
+gem push rails_engine_toolkit-0.6.2.gem
+```
+
+## Tag example
+
+```bash
+git tag v0.6.2
+git push origin v0.6.2
+```

data/docs/TESTING.md

@@ -0,0 +1,21 @@
+# Testing strategy
+
+## Layers
+
+The test suite is split into four layers:
+
+1. focused specs for utility classes and file mutation helpers
+2. action specs that exercise CLI-facing workflows on temporary directories
+3. integration-style specs for route insertion, removal, and migration installation/uninstallation
+4. host-app smoke checks through CI using a Rails 8.1 fixture app
+
+## Main scenarios covered
+
+- install generator creates configuration and prints summary
+- broken engine references in Gemfile are detected and can be removed
+- route mounts are inspected with parser-assisted detection
+- route mounts are inserted once and removed across multiple mount syntaxes
+- engine README owned tables are updated from engine migrations
+- engine migration files can be installed into the host app one engine at a time
+- copied root migrations can be uninstalled with explicit confirmation
+- engine removal cleans routes, Gemfile, and engine directory

data/exe/engine-toolkit

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'rails_engine_toolkit'
+
+exit RailsEngineToolkit::CLI.start(ARGV)

data/lib/rails_engine_toolkit/actions/delete_engine_migration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Actions
+    class DeleteEngineMigration
+      def initialize(argv, stdin:, stdout:, root:, stderr: nil)
+        @engine_name = argv[0]
+        @pattern = argv[1]
+        @stdin = stdin
+        @stdout = stdout
+        @stderr = stderr
+        @root = Pathname(root)
+        @project = Project.new(@root)
+      end
+
+      def call
+        @project.validate_root!
+        validate_args!
+
+        migrations_dir = @project.engine_path(@engine_name).join('db/migrate')
+        raise ValidationError, "Migrations path does not exist: #{migrations_dir}" unless migrations_dir.directory?
+
+        matches = migrations_dir.glob("*#{@pattern}*.rb").sort
+        raise ValidationError, "No migrations found matching '#{@pattern}'." if matches.empty?
+
+        confirmed = Utils.ask(
+          "Type '#{@engine_name}' to confirm deletion",
+          input: @stdin,
+          output: @stdout
+        )
+        raise ValidationError, 'Operation aborted.' unless confirmed == @engine_name
+
+        matches.each(&:delete)
+        UpdateEngineReadme.new([@engine_name], stdin: @stdin, stdout: @stdout, stderr: nil, root: @root).call
+        @stdout.puts("Deleted #{matches.size} migration(s)")
+      end
+
+      private
+
+      def validate_args!
+        raise ValidationError, 'Engine name is required.' if @engine_name.to_s.empty?
+        raise ValidationError, 'Migration match pattern is required.' if @pattern.to_s.empty?
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/actions/init.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Actions
+    class Init
+      def initialize(_argv, stdin:, stdout:, root:, stderr: nil)
+        @stdin = stdin
+        @stdout = stdout
+        @stderr = stderr
+        @root = Pathname(root)
+        @project = Project.new(@root)
+      end
+
+      def call
+        @project.validate_root!
+        answers = prompt_values
+
+        FileUtils.mkdir_p(@project.config_file.dirname)
+        @project.config_file.write(
+          Templates.render('engine_toolkit_yml', answers)
+        )
+
+        @stdout.puts("Created #{@project.config_file}")
+        @stdout.puts('Edit this file to customize the toolkit for your project:')
+        @stdout.puts("  #{@project.config_file}")
+      end
+
+      private
+
+      def prompt_values
+        slug_default = Utils.repo_slug_from_path(@root)
+        name_default = Utils.humanize_slug(slug_default)
+
+        {
+          project_slug: Utils.ask('Project slug', default: slug_default, input: @stdin, output: @stdout),
+          project_name: Utils.ask('Project name', default: name_default, input: @stdin, output: @stdout),
+          project_url: Utils.ask('Project URL', default: Utils.git_remote_url.to_s, input: @stdin, output: @stdout),
+          author_name: Utils.ask('Author name', default: Utils.git_config('user.name').to_s, input: @stdin,
+                                                output: @stdout),
+          author_email: Utils.ask('Author email', default: Utils.git_config('user.email').to_s, input: @stdin,
+                                                  output: @stdout),
+          database: Utils.ask('Default database adapter', default: 'postgresql', input: @stdin, output: @stdout),
+          api_only: Utils.ask_yes_no('Use API-only engines by default?', default: true, input: @stdin, output: @stdout),
+          skip_asset_pipeline: Utils.ask_yes_no('Skip asset pipeline by default?', default: true, input: @stdin,
+                                                                                   output: @stdout),
+          mount_routes: Utils.ask_yes_no('Mount engine routes automatically?', default: true, input: @stdin,
+                                                                               output: @stdout),
+          create_ddd_structure: Utils.ask_yes_no('Create DDD folders by default?', default: true, input: @stdin,
+                                                                                   output: @stdout)
+        }
+      end
+    end
+  end
+end

data/lib/rails_engine_toolkit/actions/install_engine_migrations.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RailsEngineToolkit
+  module Actions
+    class InstallEngineMigrations
+      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!
+
+        migrations_dir = engine_migrations_dir
+        FileUtils.mkdir_p(@project.root_migrations_dir)
+
+        copied = migrations_to_copy(migrations_dir).map do |source_file|
+          copy_migration(source_file)
+        end
+
+        report_result(copied)
+      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 engine_migrations_dir
+        migrations_dir = @project.engine_path(@engine_name).join('db/migrate')
+        unless migrations_dir.directory?
+          raise ValidationError,
+                "Engine migrations directory not found: #{migrations_dir}"
+        end
+
+        migrations_dir
+      end
+
+      def migrations_to_copy(migrations_dir)
+        existing = @project.root_migrations_dir.glob('*.rb').map do |file|
+          file.basename.to_s.sub(/^\d+_/, '')
+        end
+
+        migrations_dir.glob('*.rb').sort.reject do |file|
+          existing.include?(file.basename.to_s.sub(/^\d+_/, ''))
+        end
+      end
+
+      def copy_migration(source_file)
+        basename_without_version = source_file.basename.to_s.sub(/^\d+_/, '')
+        destination = @project.root_migrations_dir.join("#{next_timestamp}_#{basename_without_version}")
+        FileEditor.copy_file(source_file, destination)
+        destination
+      end
+
+      def report_result(copied)
+        if copied.empty?
+          @stdout.puts("No new migrations to install for engine '#{@engine_name}'.")
+          return
+        end
+
+        @stdout.puts("Installed #{copied.size} migration(s) for engine '#{@engine_name}':")
+        copied.each { |file| @stdout.puts("  #{file.relative_path_from(@root)}") }
+      end
+
+      def next_timestamp
+        @counter ||= 0
+        @counter += 1
+        (Time.now.utc + @counter).strftime('%Y%m%d%H%M%S')
+      end
+    end
+  end
+end