Module: Seams::Generators::EjectAware

Included in:
AccountsGenerator, AdminGenerator, AuthGenerator, BillingGenerator, CoreGenerator, NotificationsGenerator, TeamsGenerator
Defined in:
lib/seams/generators/eject_aware.rb

Overview

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.

Constant Summary collapse

EJECT_HEADER_PREFIX = 
"# seams:ejected from"

Instance Method Summary collapse

Instance Method Details

#ejected?(path) ⇒ Boolean

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/.

Returns:

  • (Boolean) 


84
85
86
87
88
 
# File 'lib/seams/generators/eject_aware.rb', line 84

def ejected?(path)
  return false unless File.exist?(path)

  File.read(path, 200).to_s.start_with?(EJECT_HEADER_PREFIX)
end

#template_unless_ejected(source, *args) ⇒ Object

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.



70
71
72
73
74
75
76
77
78
 
# File 'lib/seams/generators/eject_aware.rb', line 70

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