seams 0.1.0

data/lib/seams/generators/dummy_app_writer.rb

@@ -0,0 +1,424 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Seams
+  module Generators
+    # Writes a slim spec/dummy/ Rails app inside a generated engine so
+    # the engine's specs can boot Rails and run against a real
+    # ActiveRecord database without requiring the host application.
+    #
+    # The boilerplate (application.rb, boot.rb, environment.rb,
+    # database.yml, environments/test.rb, application_record.rb,
+    # log/.gitkeep, spec_helper.rb, rails_helper.rb) is emitted by
+    # this helper. Engines supply the bits that vary: the schema, the
+    # optional host User model, and the routes block.
+    #
+    #   Seams::Generators::DummyAppWriter.write!(
+    #     engine_path:      "engines/auth",
+    #     engine_module:    "Auth",
+    #     mount_at:         "/auth",
+    #     schema:           "<schema body>",
+    #     host_user:        "<class User body>",      # optional
+    #     host_user_path:   "app/models/user.rb",     # optional, defaults to app/models/user.rb
+    #   )
+    #
+    # `host_user_path` lets engines whose dummy "user" model lives at a
+    # different autoload path (e.g. `app/models/auth/identity.rb`)
+    # write the file where Zeitwerk will find it.
+    module DummyAppWriter
+      module_function
+
+      def write!(engine_path:, engine_module:, schema:, mount_at: nil, host_user: nil,
+                 host_user_path: "app/models/user.rb")
+        ensure_directories(engine_path)
+        write_dummy_config(engine_path, engine_module, mount_at)
+        write_dummy_app(engine_path, host_user, host_user_path)
+        write_dummy_db(engine_path, schema)
+        write_dummy_meta(engine_path)
+        write_spec_helpers(engine_path)
+      end
+
+      def ensure_directories(engine_path)
+        %w[
+          spec/dummy/config/environments
+          spec/dummy/config/initializers
+          spec/dummy/db
+          spec/dummy/app/models
+          spec/dummy/app/controllers
+          spec/dummy/app/mailers
+          spec/dummy/app/jobs
+          spec/dummy/log
+          spec/dummy/tmp
+          spec/runtime
+        ].each { |dir| FileUtils.mkdir_p(File.join(engine_path, dir)) }
+      end
+
+      def write_dummy_config(engine_path, engine_module, mount_at)
+        write(File.join(engine_path, "spec/dummy/config/boot.rb"),         boot_rb)
+        write(File.join(engine_path, "spec/dummy/config/application.rb"),  application_rb(engine_module))
+        write(File.join(engine_path, "spec/dummy/config/environment.rb"),  environment_rb)
+        write(File.join(engine_path, "spec/dummy/config/database.yml"),    database_yml(engine_path))
+        write(File.join(engine_path, "spec/dummy/config/environments/test.rb"),       test_environment_rb)
+        write(File.join(engine_path, "spec/dummy/config/initializers/secret_key.rb"), secret_key_rb)
+        write(File.join(engine_path, "spec/dummy/config/routes.rb"), routes_rb(engine_module, mount_at))
+      end
+
+      def write_dummy_app(engine_path, host_user, host_user_path)
+        write(File.join(engine_path, "spec/dummy/app/models/application_record.rb"), application_record_rb)
+        write(File.join(engine_path, "spec/dummy/app/controllers/application_controller.rb"), application_controller_rb)
+        write(File.join(engine_path, "spec/dummy/app/mailers/application_mailer.rb"),         application_mailer_rb)
+        write(File.join(engine_path, "spec/dummy/app/jobs/application_job.rb"),               application_job_rb)
+        return unless host_user
+
+        full_user_path = File.join(engine_path, "spec/dummy", host_user_path)
+        FileUtils.mkdir_p(File.dirname(full_user_path))
+        write(full_user_path, host_user)
+      end
+
+      def write_dummy_db(engine_path, schema)
+        write(File.join(engine_path, "spec/dummy/db/schema.rb"), schema_rb(schema))
+      end
+
+      def write_dummy_meta(engine_path)
+        write(File.join(engine_path, "spec/dummy/log/.keep"), "")
+        write(File.join(engine_path, "spec/dummy/tmp/.keep"), "")
+        write(File.join(engine_path, "spec/dummy/Rakefile"), rakefile_rb)
+        write(File.join(engine_path, "spec/dummy/config.ru"), config_ru)
+      end
+
+      def write_spec_helpers(engine_path)
+        write(File.join(engine_path, "spec/spec_helper.rb"),  spec_helper_rb(engine_path))
+        write(File.join(engine_path, "spec/rails_helper.rb"), rails_helper_rb)
+      end
+
+      def write(path, content)
+        File.write(path, content)
+      end
+
+      def boot_rb
+        <<~RB
+          # frozen_string_literal: true
+
+          ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../../Gemfile", __dir__)
+          require "bundler/setup" if File.exist?(ENV["BUNDLE_GEMFILE"])
+        RB
+      end
+
+      def application_rb(engine_module)
+        <<~RB
+          # frozen_string_literal: true
+
+          require_relative "boot"
+
+          require "rails/all"
+
+          Bundler.require(*Rails.groups)
+
+          # The engine isn't a published gem; it lives at engines/<name>/.
+          # Put its lib/ on the load path before requiring its root file.
+          $LOAD_PATH.unshift File.expand_path("../../../lib", __dir__)
+          require "#{engine_module.downcase}"
+
+          module Dummy
+            class Application < Rails::Application
+              # Pin root to the dummy app so Rails doesn't walk up
+              # and pick up the host application's Rakefile/config.ru.
+              config.root = File.expand_path("..", __dir__)
+
+              config.load_defaults Rails::VERSION::STRING.to_f
+              config.eager_load = false
+              config.active_support.deprecation = :stderr
+              config.action_controller.include_all_helpers = false
+            end
+          end
+        RB
+      end
+
+      def environment_rb
+        <<~RB
+          # frozen_string_literal: true
+
+          require_relative "application"
+          Rails.application.initialize!
+        RB
+      end
+
+      def database_yml(engine_path)
+        # Postgres-only — engine schemas use jsonb columns. Per-engine
+        # database name keeps parallel test runs from clobbering each
+        # other. CI sets PG* env vars; locally they default to the
+        # current user with no password (Homebrew Postgres default).
+        db_name = "#{File.basename(engine_path)}_dummy_test"
+        <<~YML
+          test:
+            adapter: postgresql
+            database: #{db_name}
+            host:     <%= ENV.fetch("PGHOST",     "localhost") %>
+            port:     <%= ENV.fetch("PGPORT",     "5432") %>
+            username: <%= ENV.fetch("PGUSER",     ENV["USER"]) %>
+            password: <%= ENV.fetch("PGPASSWORD", "") %>
+            pool: 5
+            encoding: unicode
+        YML
+      end
+
+      def test_environment_rb
+        <<~RB
+          # frozen_string_literal: true
+
+          Rails.application.configure do
+            config.cache_classes               = true
+            config.eager_load                  = false
+            config.public_file_server.enabled  = true
+            config.consider_all_requests_local = true
+            config.action_controller.perform_caching = false
+            config.action_dispatch.show_exceptions   = :rescuable
+            config.action_controller.allow_forgery_protection = false
+            config.active_support.deprecation = :stderr
+
+            # Throwaway keys for the dummy app so models that declare
+            # `encrypts` can round-trip in specs. The dummy DB is wiped
+            # every run, so deterministic strings are safe here.
+            # Hosts use `bin/rails db:encryption:init` + Rails credentials.
+            config.active_record.encryption.primary_key            = "dummy_primary_key_for_tests_only"
+            config.active_record.encryption.deterministic_key      = "dummy_deterministic_key_for_tests_only"
+            config.active_record.encryption.key_derivation_salt    = "dummy_key_derivation_salt_for_tests_only"
+            config.active_record.encryption.support_unencrypted_data = true
+
+            # Mailer specs render views that call URL helpers (e.g.
+            # `edit_password_reset_url`). Without a host they raise
+            # "Missing host to link to!". `test.host` is the Rails
+            # test convention.
+            config.action_mailer.delivery_method     = :test
+            config.action_mailer.default_url_options = { host: "test.host" }
+          end
+        RB
+      end
+
+      def secret_key_rb
+        <<~RB
+          # frozen_string_literal: true
+
+          Rails.application.config.secret_key_base = "test_secret_key_base_for_dummy_app"
+        RB
+      end
+
+      def routes_rb(engine_module, mount_at)
+        body = mount_at ? %(  mount #{engine_module}::Engine, at: "#{mount_at}") : ""
+        <<~RB
+          # frozen_string_literal: true
+
+          Rails.application.routes.draw do
+          #{body}
+          end
+        RB
+      end
+
+      def schema_rb(schema_body)
+        # Match Rails::VERSION at write-time so schema-format defaults
+        # match the host's Rails. A 7.1 schema declared on Rails 8.x
+        # still loads, but column-default semantics drift. defined?
+        # check guards a Rails-loaded-but-VERSION-not-yet-required boot
+        # window the generator specs hit.
+        rails_version =
+          if defined?(Rails::VERSION::STRING)
+            Rails::VERSION::STRING.split(".")[0, 2].join(".")
+          else
+            "8.1"
+          end
+        <<~RB
+          # frozen_string_literal: true
+
+          ActiveRecord::Schema[#{rails_version}].define(version: 0) do
+          #{schema_body.lines.map { |l| "  #{l}" }.join.rstrip}
+          end
+        RB
+      end
+
+      def application_record_rb
+        <<~RB
+          # frozen_string_literal: true
+
+          class ApplicationRecord < ActiveRecord::Base
+            self.abstract_class = true
+          end
+        RB
+      end
+
+      def application_controller_rb
+        # Minimal host ApplicationController so engine controllers that
+        # inherit from ::ApplicationController (the seams:engine generator
+        # default) can boot inside a request spec. Real hosts will have
+        # their own; this is dummy-only.
+        <<~RB
+          # frozen_string_literal: true
+
+          class ApplicationController < ActionController::Base
+          end
+        RB
+      end
+
+      def application_mailer_rb
+        # Minimal host ApplicationMailer so engine mailers that inherit
+        # from ::ApplicationMailer (auth's PasswordsMailer,
+        # notifications' ApplicationMailer) can be autoloaded inside
+        # the dummy. Real hosts will have their own; this is
+        # dummy-only.
+        <<~RB
+          # frozen_string_literal: true
+
+          class ApplicationMailer < ActionMailer::Base
+            default from: "from@example.com"
+          end
+        RB
+      end
+
+      def application_job_rb
+        # Minimal host ApplicationJob so engine jobs that inherit from
+        # ::ApplicationJob (notifications' ApplicationJob, billing's
+        # ApplicationJob) can be autoloaded inside the dummy. Without
+        # this, the engine's spec suite raises NameError the moment a
+        # spec touches CreateNotificationJob / StartSubscriptionJob /
+        # any other job class.
+        <<~RB
+          # frozen_string_literal: true
+
+          class ApplicationJob < ActiveJob::Base
+          end
+        RB
+      end
+
+      def rakefile_rb
+        <<~RB
+          # frozen_string_literal: true
+
+          # Marker file so Rails::Engine.find_root anchors here, not
+          # in the parent host application.
+          require_relative "config/application"
+          Rails.application.load_tasks if defined?(Rails.application)
+        RB
+      end
+
+      def config_ru
+        <<~RB
+          # frozen_string_literal: true
+
+          require_relative "config/environment"
+          run Rails.application
+        RB
+      end
+
+      def spec_helper_rb(engine_path)
+        engine_name = File.basename(engine_path)
+        <<~RB
+          # frozen_string_literal: true
+
+          ENV["RAILS_ENV"] ||= "test"
+
+          # Rails has to load before the engine's lib/<name>.rb runs,
+          # because engine.rb references Rails::Engine. Specs that need
+          # ActiveRecord should `require "rails_helper"` instead — that
+          # ALSO boots the dummy app, defines the schema, and connects
+          # to the test DB.
+          require "rails"
+          $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+          require "#{engine_name}"
+
+          RSpec.configure do |config|
+            config.expect_with :rspec do |expectations|
+              expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+            end
+
+            config.mock_with :rspec do |mocks|
+              mocks.verify_partial_doubles = true
+            end
+
+            config.shared_context_metadata_behavior = :apply_to_host_groups
+            config.disable_monkey_patching!
+            config.order = :random
+            Kernel.srand config.seed
+          end
+        RB
+      end
+
+      def rails_helper_rb
+        <<~RB
+          # frozen_string_literal: true
+
+          require_relative "spec_helper"
+          ENV["RAILS_ENV"] ||= "test"
+
+          # Ensure the per-engine Postgres test database exists before
+          # the dummy app boots and tries to connect to it. We connect
+          # to the maintenance "postgres" database first, CREATE DATABASE
+          # if missing, then let the dummy app pick up its own config.
+          require "active_record"
+          require "yaml"
+          require "erb"
+          dummy_db_yml = File.expand_path("dummy/config/database.yml", __dir__)
+          db_config    = YAML.safe_load(ERB.new(File.read(dummy_db_yml)).result, aliases: true)["test"]
+          target_db    = db_config["database"]
+          admin_config = db_config.merge("database" => "postgres")
+          ActiveRecord::Base.establish_connection(admin_config)
+          unless ActiveRecord::Base.connection.execute(
+            "SELECT 1 FROM pg_database WHERE datname = '\#{target_db}'"
+          ).any?
+            ActiveRecord::Base.connection.execute(%(CREATE DATABASE "\#{target_db}"))
+          end
+          ActiveRecord::Base.remove_connection
+
+          require File.expand_path("dummy/config/environment", __dir__)
+          abort("Rails is in production mode!") if Rails.env.production?
+
+          require "rspec/rails"
+
+          # WebMock is optional — engines that stub outbound HTTP
+          # (billing's stub_stripe helpers, auth's OAuth adapter
+          # specs) bring in `webmock` via the host Gemfile. If
+          # available, require it so specs can call WebMock.stub_request
+          # without each one re-requiring it. We disable real HTTP
+          # connections to make missing stubs explicit instead of
+          # accidentally hitting the network.
+          begin
+            require "webmock/rspec"
+            WebMock.disable_net_connect!(allow_localhost: true)
+          rescue LoadError
+            # webmock isn't bundled — engines that don't stub HTTP
+            # don't need it.
+          end
+
+          # FactoryBot is optional — engines that ship factories add
+          # `factory_bot_rails` to the host Gemfile. If it's loaded, wire
+          # the syntax methods + auto-discover the engine's
+          # spec/factories/*.rb (default search paths look in the host's
+          # spec/factories which doesn't exist when running engine specs
+          # from the host root).
+          if defined?(FactoryBot)
+            require "factory_bot_rails"
+            engine_factories = File.expand_path("factories", __dir__)
+            FactoryBot.definition_file_paths = [engine_factories]
+            FactoryBot.find_definitions if FactoryBot.factories.none?
+          end
+
+          ActiveRecord::Schema.verbose = false
+          # Drop and reload the schema for a clean slate every run.
+          ActiveRecord::Base.connection.tables.each do |t|
+            ActiveRecord::Base.connection.drop_table(t, force: :cascade)
+          end
+          load File.expand_path("dummy/db/schema.rb", __dir__)
+
+          RSpec.configure do |config|
+            config.use_transactional_fixtures = true
+            config.infer_spec_type_from_file_location!
+            config.filter_rails_from_backtrace!
+
+            if defined?(FactoryBot)
+              config.include FactoryBot::Syntax::Methods
+            end
+          end
+        RB
+      end
+    end
+  end
+end

data/lib/seams/generators/eject_aware.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Seams
+  module Generators
+    # Mixin that lets a canonical engine generator (auth, accounts,
+    # billing, core, notifications, teams) cooperate with the
+    # `bin/seams resolve --eject` CLI introduced in Wave 10 Phase 2B.
+    #
+    # The contract is one-way: ejection happens in the host's working
+    # tree (the CLI prepends a `# seams:ejected from <engine>.<path>`
+    # header to a file the host wants to own). This module gives the
+    # generator the matching skip behaviour — when the destination
+    # file already starts with that header, the generator's
+    # `template_unless_ejected` helper logs a yellow "skip" line and
+    # leaves the file untouched.
+    #
+    # ## Eject-eligibility rule
+    #
+    # The CLI and this helper agree on a single eligibility rule:
+    #
+    # - Eligible: every templated file under `app/` and `lib/` and
+    #   `config/` (controllers, models, services, jobs, mailers,
+    #   views, concerns, lib classes, configuration.rb, routes.rb).
+    #   These are pieces a host might reasonably want to own outright
+    #   — to override behaviour, change copy, swap a layout, etc.
+    # - Eligible: spec files (spec/) and factories. The host owns
+    #   the regenerated specs the same way the host owns the engine
+    #   code; ejecting a spec is rare but legal.
+    # - INELIGIBLE: migrations under `db/migrate/`. Migrations run
+    #   exactly once on a host's timetable; ejecting a migration is
+    #   meaningless (it's already been run) and re-running the
+    #   generator never overwrites an existing migration anyway —
+    #   each run produces a new timestamp.
+    # - INELIGIBLE: framework-managed engine boot files —
+    #   `lib/<engine>/engine.rb`, `lib/<engine>/version.rb`, the
+    #   engine's Gemfile and gemspec. These are the contract between
+    #   the engine and the host's Rails boot; if the host wants
+    #   different behaviour they extend via insertion points or a
+    #   follow-up generator.
+    #
+    # The CLI enforces this rule at eject time. The
+    # `template_unless_ejected` helper is intentionally permissive —
+    # if a host has somehow stamped the eject header onto a
+    # framework-managed file, we skip rather than overwrite. The
+    # error path is loud at eject, not at generation.
+    #
+    # ## Usage
+    #
+    # In an engine generator:
+    #
+    #   class AuthGenerator < Rails::Generators::Base
+    #     include Seams::Generators::EjectAware
+    #
+    #     def create_models
+    #       template_unless_ejected "app/models/identity.rb.tt",
+    #                               engine_path("app/models/auth/identity.rb")
+    #     end
+    #   end
+    #
+    # `template_unless_ejected` accepts the same positional + keyword
+    # arguments as Thor's `template`, including `force: true`, so
+    # generators can adopt it incrementally without changing call sites.
+    module EjectAware
+      EJECT_HEADER_PREFIX = "# seams:ejected from"
+
+      # Drop-in replacement for Thor's `template`. If the destination
+      # exists and starts with the eject header, log a `skip` line and
+      # return without writing. Otherwise delegate to `template` —
+      # Thor handles `force: true` and conflict resolution as usual.
+      def template_unless_ejected(source, *args, **)
+        destination = args.first
+        if destination && File.exist?(destination) && ejected?(destination)
+          say_status :skip, ejected_say_message(destination), :yellow
+          return
+        end
+
+        template(source, *args, **)
+      end
+
+      # True when the file at `path` carries the eject header on its
+      # first line. Reads only the first 200 bytes — the header sits
+      # at the very top and we don't want to slurp megabytes for files
+      # under app/views/.
+      def ejected?(path)
+        return false unless File.exist?(path)
+
+        File.read(path, 200).to_s.start_with?(EJECT_HEADER_PREFIX)
+      end
+
+      private
+
+      def ejected_say_message(destination)
+        if respond_to?(:destination_root)
+          relative = destination.sub(%r{\A#{Regexp.escape(destination_root.to_s)}/?},
+                                     "")
+        end
+        relative ||= destination
+        "#{relative} (ejected — kept host version)"
+      end
+    end
+  end
+end

data/lib/seams/generators/follow_up_generator.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "seams/generators/splicer"
+
+module Seams
+  module Generators
+    # Base class for follow-up generators — net-new generators that
+    # extend an already-installed engine without re-templating the
+    # whole engine. Subclasses look like:
+    #
+    #   module Seams
+    #     module Generators
+    #       class AddPasskeysGenerator < FollowUpGenerator
+    #         engine_name "auth"
+    #
+    #         def add_event
+    #           splice(
+    #             file: "lib/auth/engine.rb",
+    #             marker: "auth.engine.events",
+    #             content: <<~RUBY
+    #               Seams::EventRegistry.register("identity.passkey_added.auth", emitted_by: "Auth")
+    #             RUBY
+    #           )
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # The base class supplies four primitives that every follow-up
+    # generator needs:
+    #
+    # - +engine_path(relative)+ — resolve a path inside the host's
+    #   `engines/<this_engine>/` directory.
+    # - +splice(file:, marker:, content:, ...)+ — wrap
+    #   +Splicer.splice_after_marker+ with a concise log line.
+    # - +assert_marker_exists!(file:, marker:)+ — fail fast with a
+    #   clear "this engine wasn't generated" message when a follow-up
+    #   generator runs against a host that hasn't installed the
+    #   target engine.
+    # - +report_summary+ — template method subclasses override to
+    #   print a "what just changed" message at the end.
+    class FollowUpGenerator < Rails::Generators::Base
+      class << self
+        # Sets the engine this follow-up generator targets. Used by
+        # +engine_path+ to resolve relative paths and by
+        # +assert_marker_exists!+ to build the recovery hint.
+        def engine_name(name = nil)
+          @engine_name = name if name
+          @engine_name || raise(ArgumentError,
+                                "#{self.name} must declare `engine_name \"<engine>\"` " \
+                                "(e.g. \"auth\") — the base class needs it to resolve " \
+                                "engines/<engine>/ paths.")
+        end
+      end
+
+      # The helpers below are wrapped in `no_tasks { ... }` so Thor
+      # treats them as plain instance methods, not generator
+      # commands. Without this wrapper, every public method becomes
+      # a task and `start` blows up trying to invoke `engine_path`
+      # with no arguments — and parent-class tasks invoke BEFORE
+      # subclass tasks (Thor's `all_commands` orders parents first),
+      # which would run `report_summary` before any of the
+      # subclass's actual work.
+      # The no_tasks block is naturally long — it groups every helper
+      # the FollowUpGenerator surface offers (engine_path, splice,
+      # assert_marker_exists!). Splitting them into separate blocks
+      # would obscure the "these are the public follow-up generator
+      # primitives" grouping. Disable BlockLength for this one block.
+      # rubocop:disable Metrics/BlockLength
+      no_tasks do
+        # Resolve a path inside the host's engines/<this_engine>/.
+        # Mirrors the canonical generators' +engine_path+ method but
+        # reads the engine name off the class accessor instead of
+        # hardcoding it per-generator.
+        def engine_path(relative)
+          File.join(destination_root, "engines", self.class.engine_name, relative)
+        end
+
+        # Splice `content` after `marker` in `file` (a path relative
+        # to the engine root). Logs:
+        #
+        #   splice  engines/auth/lib/auth/engine.rb @ auth.engine.events
+        #
+        # When `before:` is true, splices BEFORE the marker line instead.
+        # Returns the underlying +Splicer::Result+ so subclasses can
+        # branch on `result.ok?` if they want.
+        def splice(file:, marker:, content:, before: false, indent: nil)
+          full_path = engine_path(file)
+          result =
+            if before
+              Splicer.splice_before_marker(file_path: full_path, marker: marker, content: content, indent: indent)
+            else
+              Splicer.splice_after_marker(file_path: full_path, marker: marker, content: content, indent: indent)
+            end
+
+          if result.ok?
+            status = result.lines_added.zero? ? "exists" : "splice"
+            say "  #{status}  engines/#{self.class.engine_name}/#{file} @ #{marker}", :green
+          else
+            say "  error   #{result.error}", :red
+          end
+          result
+        end
+
+        # Raise a clear, actionable error if the marker isn't present.
+        # The most common cause is the host hasn't generated the target
+        # engine yet (or generated it from a pre-Wave-10 version of seams
+        # that didn't ship insertion points). Both cases get a single
+        # recovery hint: re-run the canonical generator.
+        def assert_marker_exists!(file:, marker:)
+          full_path = engine_path(file)
+          return if Splicer.find_marker(file_path: full_path, marker: marker)
+
+          engine = self.class.engine_name
+          raise Seams::GeneratorError, <<~MSG.chomp
+            [seams] cannot run #{self.class.name}: insertion-point marker
+              "#{marker}"
+            was not found in
+              engines/#{engine}/#{file}
+
+            Either this engine wasn't generated, or it was generated by
+            a pre-Wave-10 version of seams that didn't ship insertion
+            points. Run:
+
+              bin/rails generate seams:#{engine}
+
+            to (re)generate the engine with the current marker set, then
+            re-run this follow-up generator.
+          MSG
+        end
+      end
+      # rubocop:enable Metrics/BlockLength
+
+      # Subclass override-point. Subclasses define their own public
+      # method named `report_summary` (or any other end-of-run name);
+      # Thor invokes it as the last task because public methods on the
+      # subclass come after the parent's `no_tasks`-wrapped helpers
+      # in declaration order. The base-class default is a no-op,
+      # wrapped in `no_tasks` so it doesn't pre-empt subclass output.
+      no_tasks do
+        def report_summary
+          # Override in subclasses.
+        end
+      end
+    end
+  end
+end