create-engine-installer

Create Engine Installer

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 (initializer at config/initializers/, migrations at db/migrate/, route mount in config/routes.rb).
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).
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.
• Provide sensible defaults that are easy to edit.

Idempotency Guards

All generator actions must be safe to run multiple times. Guard every file creation and injection at the point of use:

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:

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

For larger installers, extract extended guard patterns and spec templates into a dedicated companion file alongside the generator (e.g. lib/generators/my_engine/install/install_generator_patterns.rb) to keep the generator lean and this skill focused on workflow. Reference that file explicitly in your generator's comments so future maintainers know where to find the shared patterns.

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