igmarin/create-engine-installer

Create Engine Installer

Use this skill when the task is to design or review how a host app installs and configures a Rails engine — generating initializers, copying migrations, mounting routes, or exposing a single install command.

Quick Reference

| Component | Purpose | |-----------|----------| | Generator | Creates initializer, route mount, or setup files — must be idempotent | | Migrations | Copies engine migrations into host db/migrate | | Initializer | Provides configuration defaults; generated once, editable by host | | Routes | Adds mount Engine, at: '/path'; checks for existing mount before injecting |

Validation Workflow (HARD-GATE)

When building or reviewing an install generator, follow these steps in order. DO NOT ship a generator without completing steps 3 and 4.

1. GENERATE: Run the generator against a clean host app. Show command + terminal output labeled Observed output for the first run. Confirm files are created in correct host paths.
2. VERIFY: Check output files exist in the correct host paths. List shell commands confirming the initializer, routes, and migrations exist.
3. RERUN: Run the generator a second time; confirm no duplicate files, routes, or initializer blocks are inserted. Show command + terminal output labeled Observed output demonstrating idempotent behavior (skipping/conflict resolution). Use unique, scenario-specific values rather than copying verbatim from templates.
4. TEST: Cover both single-run and rerun behavior in generator specs (see spec template below). Confirm no duplicate inserts on rerun in specs.
5. DOCUMENT: List what was generated vs. what the user must do manually, including required env vars, rollback steps, and any install docs — verified against what the generator actually produces.

Key implementation rules:

• Configure only in initializers (avoid boot-time mutation).
• Document all required env vars alongside rollback steps.
• Use idiomatic Rails/Thor generator commands (inheriting from Rails::Generators::Base, with source_root, desc, etc.).
• Provide sensible defaults that are easy to edit.

Idempotency guards — check before creating or injecting:

def create_initializer
  return if File.exist?(File.join(destination_root, 'config/initializers/my_engine.rb'))
  create_file 'config/initializers/my_engine.rb', <<~RUBY
    MyEngine.configure do |config|
      config.user_class = "User"
    end
  RUBY
end

def mount_route
  # inject_into_file with force: false skips insertion if sentinel already present
  inject_into_file 'config/routes.rb',
    "\n  mount MyEngine::Engine, at: '/admin'\n",
    after: "Rails.application.routes.draw do",
    force: false
end

Minimal rerun spec (must always pass):

it 'does not duplicate the route mount on rerun' do
  2.times { run_generator }
  expect(File.read(file('config/routes.rb')).scan('mount MyEngine::Engine').size).to eq(1)
end

Integration

| Skill | When to chain | |-------|---------------| | create-engine | When designing the engine structure that installers will configure | | document-engine | When documenting install steps or upgrade instructions | | test-engine | When adding generator specs or dummy-app install coverage |