TDD step 10: Install generator

`bin/rails generate active_admin:oidc:install` now produces the three
things a host app actually needs: a commented-out initializer (with
sample on_login snippets for Zitadel nested roles and for
department-style apps to prove the gem is authorization-agnostic),
a migration adding provider/uid/oidc_raw_info + unique index to
admin_users, and the published login view override.

Notable choices: migration is idempotent by file-glob (not by
timestamp), jsonb on Postgres / text elsewhere, and the generator
refuses to run without AdminUser / devise / activeadmin in the host
app so silent half-installs can't happen.

Author: Fivell

lib/generators/active_admin/oidc/install/install_generator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module ActiveAdmin
+  module Oidc
+    module Generators
+      # `bin/rails generate active_admin:oidc:install`
+      #
+      # Produces a working starting point for the host app:
+      #
+      #   * config/initializers/activeadmin_oidc.rb  (commented template)
+      #   * db/migrate/<ts>_add_oidc_to_admin_users.rb
+      #   * app/views/active_admin/devise/sessions/new.html.erb (override)
+      #
+      # Idempotent: running twice is a no-op for all three files (the
+      # migration is skipped if an *_add_oidc_to_admin_users.rb file
+      # already exists on disk, even with a different timestamp).
+      #
+      # Refuses to run if the host app is missing an `AdminUser` model
+      # or the `devise` / `activeadmin` gems — those are the sharp
+      # corners it can't work around, and silently succeeding would
+      # produce broken configuration.
+      class InstallGenerator < ::Rails::Generators::Base
+        include ::Rails::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Installs activeadmin-oidc into the host Rails app."
+
+        def self.next_migration_number(dirname)
+          ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+        end
+
+        def verify_host_app!
+          unless File.exist?(File.join(destination_root, "app/models/admin_user.rb"))
+            raise ::Thor::Error,
+                  "activeadmin-oidc: could not find app/models/admin_user.rb — " \
+                  "install activeadmin + devise first and make sure the AdminUser " \
+                  "model exists."
+          end
+
+          gemfile_lock = File.join(destination_root, "Gemfile.lock")
+          lock_contents = File.exist?(gemfile_lock) ? File.read(gemfile_lock) : ""
+
+          unless lock_contents.match?(/^\s+devise\b/)
+            raise ::Thor::Error,
+                  "activeadmin-oidc: devise not found in Gemfile.lock. " \
+                  "Add `gem \"devise\"` and run `bundle install` first."
+          end
+
+          unless lock_contents.match?(/^\s+activeadmin\b/)
+            raise ::Thor::Error,
+                  "activeadmin-oidc: activeadmin not found in Gemfile.lock. " \
+                  "Add `gem \"activeadmin\"` and run `bundle install` first."
+          end
+        end
+
+        def create_initializer
+          template "initializer.rb.tt", "config/initializers/activeadmin_oidc.rb"
+        end
+
+        def create_migration_file
+          # Idempotency: if a previous run already produced this
+          # migration (any timestamp), do nothing. We never want to
+          # stack up duplicate add_column migrations.
+          existing = Dir[File.join(destination_root, "db/migrate/*_add_oidc_to_admin_users.rb")]
+          return if existing.any?
+
+          @raw_info_type = raw_info_column_type
+          migration_template "migration.rb.tt",
+                             "db/migrate/add_oidc_to_admin_users.rb"
+        end
+
+        def create_view_override
+          copy_file "sessions_new.html.erb",
+                    "app/views/active_admin/devise/sessions/new.html.erb"
+        end
+
+        private
+
+        # Postgres gets `jsonb` (fast, indexable), everything else
+        # falls back to `:text` so sqlite/mysql hosts aren't left out.
+        def raw_info_column_type
+          adapter = (ActiveRecord::Base.connection_db_config.adapter rescue "sqlite3").to_s
+          adapter.start_with?("postgres") ? ":jsonb" : ":text"
+        end
+      end
+    end
+  end
+end

lib/generators/active_admin/oidc/install/templates/initializer.rb.tt

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# activeadmin-oidc initializer — generated by
+#   bin/rails generate active_admin:oidc:install
+#
+# Uncomment and fill in the values for your identity provider.
+
+ActiveAdmin::Oidc.configure do |c|
+  # --- Transport-layer defaults for Zitadel ---------------------------
+  # Sets `scope = "openid email profile"` and enables PKCE automatically
+  # when no client_secret is configured (public-client mode).
+  # c.preset :zitadel
+
+  # --- Provider ---------------------------------------------------------
+  # c.issuer        = ENV.fetch("OIDC_ISSUER")
+  # c.client_id     = ENV.fetch("OIDC_CLIENT_ID")
+  # c.client_secret = ENV.fetch("OIDC_CLIENT_SECRET", nil) # blank = PKCE public client
+
+  # --- Identity lookup --------------------------------------------------
+  # Which AdminUser column to match against when a (provider, uid) lookup
+  # misses and we need to migrate an existing row to SSO, and which claim
+  # on the id_token/userinfo to read it from.
+  # c.identity_attribute = :email
+  # c.identity_claim     = :email
+
+  # --- Login button label ----------------------------------------------
+  # c.login_button_label = "Sign in with Corporate SSO"
+
+  # --- on_login hook ---------------------------------------------------
+  # Called with (admin_user, claims) after identity lookup and before
+  # save. Mutate admin_user in place, return truthy to allow sign-in,
+  # return falsy to deny. This is the ONLY place authorization lives —
+  # the gem does not ship a role model.
+  #
+  # Example A — Zitadel with nested project roles claim:
+  #
+  #   c.on_login = ->(admin_user, claims) {
+  #     roles = claims["urn:zitadel:iam:org:project:roles"]&.keys || []
+  #     return false if roles.empty?
+  #     admin_user.roles = roles
+  #     true
+  #   }
+  #
+  # Example B — department-style authorization:
+  #
+  #   KNOWN_DEPARTMENTS = %w[ops eng support].freeze
+  #   c.on_login = ->(admin_user, claims) {
+  #     dept = claims["department"]
+  #     return false unless KNOWN_DEPARTMENTS.include?(dept)
+  #     admin_user.department = dept
+  #     true
+  #   }
+end

lib/generators/active_admin/oidc/install/templates/migration.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class AddOidcToAdminUsers < ActiveRecord::Migration[7.0]
+  def change
+    add_column :admin_users, :provider,      :string
+    add_column :admin_users, :uid,           :string
+    add_column :admin_users, :oidc_raw_info, <%= @raw_info_type %>
+
+    add_index  :admin_users, [:provider, :uid], unique: true
+  end
+end

lib/generators/active_admin/oidc/install/templates/sessions_new.html.erb

@@ -0,0 +1,9 @@
+<div id="login">
+  <h2><%%= active_admin_application.site_title(self) %></h2>
+
+  <%%= button_to ActiveAdmin::Oidc.config.login_button_label,
+                "/admin/auth/oidc",
+                method: :post,
+                class: "activeadmin-oidc-login-button",
+                data: { turbo: false } %>
+</div>

spec/generators/install_generator_spec.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require "rails/generators"
+require "generators/active_admin/oidc/install/install_generator"
+
+# The install generator is what a host app runs once:
+#
+#   bundle add activeadmin-oidc
+#   bin/rails generate active_admin:oidc:install
+#
+# It must produce a working, editable starting point — initializer with
+# a commented-out Zitadel preset and sample `on_login` snippets, a
+# migration adding `provider`/`uid`/`oidc_raw_info` + a unique index to
+# `admin_users`, and a published login view override. It must be
+# idempotent (running twice does nothing bad) and refuse to run if the
+# host app doesn't have `AdminUser` or `devise`/`activeadmin`.
+RSpec.describe ActiveAdmin::Oidc::Generators::InstallGenerator do
+  let(:destination_root) { File.expand_path("../../tmp/generator_test", __dir__) }
+
+  before do
+    FileUtils.rm_rf(destination_root)
+    FileUtils.mkdir_p(destination_root)
+    # Stand up a minimal fake host-app tree so the generator can find
+    # config/routes.rb, config/initializers, db/migrate, Gemfile.lock
+    # and the AdminUser model it needs to refuse-to-run without.
+    FileUtils.mkdir_p(File.join(destination_root, "config/initializers"))
+    FileUtils.mkdir_p(File.join(destination_root, "db/migrate"))
+    FileUtils.mkdir_p(File.join(destination_root, "app/models"))
+    File.write(
+      File.join(destination_root, "config/routes.rb"),
+      <<~RUBY
+        Rails.application.routes.draw do
+          ActiveAdmin.routes(self)
+        end
+      RUBY
+    )
+    File.write(
+      File.join(destination_root, "app/models/admin_user.rb"),
+      "class AdminUser < ApplicationRecord; end\n"
+    )
+    File.write(
+      File.join(destination_root, "Gemfile.lock"),
+      <<~LOCK
+        GEM
+          specs:
+            devise (5.0.3)
+            activeadmin (3.5.1)
+      LOCK
+    )
+  end
+
+  def run_generator(args = [])
+    # Instantiate directly rather than going through `start` so that
+    # `Thor::Error` raised in preflight propagates to the spec instead
+    # of being caught by Thor's CLI wrapper. Redirect $stdout so the
+    # "create file" log lines don't pollute rspec output.
+    generator = described_class.new(args, [], destination_root: destination_root)
+    orig_stdout = $stdout
+    $stdout = StringIO.new
+    begin
+      generator.invoke_all
+    ensure
+      $stdout = orig_stdout
+    end
+  end
+
+  describe "initializer" do
+    before { run_generator }
+
+    let(:initializer) do
+      File.read(File.join(destination_root, "config/initializers/activeadmin_oidc.rb"))
+    end
+
+    it "creates the initializer at config/initializers/activeadmin_oidc.rb" do
+      expect(File).to exist(
+        File.join(destination_root, "config/initializers/activeadmin_oidc.rb")
+      )
+    end
+
+    it "contains an ActiveAdmin::Oidc.configure block" do
+      expect(initializer).to include("ActiveAdmin::Oidc.configure do |c|")
+    end
+
+    it "includes a commented-out Zitadel preset line" do
+      expect(initializer).to match(/^\s*#\s*c\.preset\s+:zitadel/)
+    end
+
+    it "includes commented-out ENV reads for issuer/client_id/client_secret" do
+      expect(initializer).to match(/#\s*c\.issuer\s*=\s*ENV/)
+      expect(initializer).to match(/#\s*c\.client_id\s*=\s*ENV/)
+      expect(initializer).to match(/#\s*c\.client_secret\s*=\s*ENV/)
+    end
+
+    it "includes a sample on_login snippet for Zitadel nested roles claim" do
+      expect(initializer).to include("urn:zitadel:iam:org:project:roles")
+    end
+
+    it "includes a sample on_login snippet for a department-style assignment" do
+      expect(initializer).to match(/department/i)
+    end
+  end
+
+  describe "migration" do
+    before { run_generator }
+
+    let(:migration_path) do
+      Dir[File.join(destination_root, "db/migrate/*_add_oidc_to_admin_users.rb")].first
+    end
+
+    let(:migration) { File.read(migration_path) }
+
+    it "creates a timestamped migration adding oidc columns to admin_users" do
+      expect(migration_path).not_to be_nil
+    end
+
+    it "adds provider, uid, and oidc_raw_info columns" do
+      expect(migration).to match(/add_column\s+:admin_users,\s*:provider,\s*:string/)
+      expect(migration).to match(/add_column\s+:admin_users,\s*:uid,\s*:string/)
+      expect(migration).to match(/add_column\s+:admin_users,\s*:oidc_raw_info/)
+    end
+
+    it "does not add any authorization column (no :role, :roles, :department)" do
+      expect(migration).not_to match(/:roles?\b/)
+      expect(migration).not_to match(/:department/)
+    end
+
+    it "adds a unique index on (provider, uid)" do
+      expect(migration).to match(
+        /add_index\s+:admin_users,\s*\[:provider,\s*:uid\],\s*unique:\s*true/
+      )
+    end
+  end
+
+  describe "login view override" do
+    before { run_generator }
+
+    it "publishes app/views/active_admin/devise/sessions/new.html.erb" do
+      expect(File).to exist(
+        File.join(destination_root, "app/views/active_admin/devise/sessions/new.html.erb")
+      )
+    end
+  end
+
+  describe "idempotency" do
+    it "does not duplicate the initializer when run twice" do
+      run_generator
+      initializer_path = File.join(destination_root, "config/initializers/activeadmin_oidc.rb")
+      first = File.read(initializer_path)
+
+      run_generator
+      second = File.read(initializer_path)
+
+      expect(second).to eq(first)
+    end
+
+    it "does not create a second migration when run twice" do
+      run_generator
+      first_migrations = Dir[File.join(destination_root, "db/migrate/*_add_oidc_to_admin_users.rb")]
+      expect(first_migrations.size).to eq(1)
+
+      run_generator
+      second_migrations = Dir[File.join(destination_root, "db/migrate/*_add_oidc_to_admin_users.rb")]
+      expect(second_migrations.size).to eq(1)
+    end
+  end
+
+  describe "preflight checks" do
+    it "aborts with a clear error if AdminUser model is missing" do
+      FileUtils.rm(File.join(destination_root, "app/models/admin_user.rb"))
+
+      expect { run_generator }.to raise_error(Thor::Error, /AdminUser/)
+    end
+
+    it "aborts with a clear error if devise is not in Gemfile.lock" do
+      File.write(
+        File.join(destination_root, "Gemfile.lock"),
+        "GEM\n  specs:\n    activeadmin (3.5.1)\n"
+      )
+
+      expect { run_generator }.to raise_error(Thor::Error, /devise/)
+    end
+
+    it "aborts with a clear error if activeadmin is not in Gemfile.lock" do
+      File.write(
+        File.join(destination_root, "Gemfile.lock"),
+        "GEM\n  specs:\n    devise (5.0.3)\n"
+      )
+
+      expect { run_generator }.to raise_error(Thor::Error, /activeadmin/)
+    end
+  end
+end