Install generator: warn on missing AdminUser wiring, print next steps

Two generator improvements driven by the demo-app testing session:

1. Soft-warn (`say_status :warning`) if app/models/admin_user.rb does
   not include `:omniauthable` or does not declare
   `omniauth_providers: [:oidc]`. Non-blocking because the user may
   be mid-refactor and know what they're doing.

2. Print a "next steps" checklist after a successful run covering
   the host-app wiring the generator cannot touch: uncommenting
   `config.authentication_method` / `config.current_user_method` in
   active_admin.rb, adding `:omniauthable, omniauth_providers: [:oidc]`
   to AdminUser, filling in issuer/client_id, and running db:migrate.

Both were footguns during end-to-end testing with a fresh ActiveAdmin
host — commented-out `authentication_method` left /admin publicly
accessible and rendered the utility nav without a logout button,
which is exactly the state this checklist now warns about.

Author: Fivell

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

@@ -78,6 +78,62 @@ def create_view_override
                     "app/views/active_admin/devise/sessions/new.html.erb"
         end
 
+        # Non-blocking: the generator completed successfully, but the
+        # host AdminUser may be missing the Devise modules the gem needs.
+        # We warn rather than hard-fail because a mid-refactor user may
+        # know exactly what they're doing.
+        def warn_missing_admin_user_wiring
+          admin_user_path = File.join(destination_root, "app/models/admin_user.rb")
+          return unless File.exist?(admin_user_path)
+
+          contents = File.read(admin_user_path)
+
+          unless contents.match?(/:omniauthable/)
+            say_status :warning,
+                       "app/models/admin_user.rb does not include :omniauthable — " \
+                       "add `:omniauthable, omniauth_providers: [:oidc]` to your `devise` call.",
+                       :yellow
+          end
+
+          unless contents.match?(/omniauth_providers\s*:\s*\[\s*:oidc/)
+            say_status :warning,
+                       "app/models/admin_user.rb does not declare `omniauth_providers: [:oidc]` — " \
+                       "the gem's callback controller will not be reachable without it.",
+                       :yellow
+          end
+        end
+
+        # Print a short checklist of the host-app wiring the generator
+        # can't do itself. These are the footguns that cost us an hour
+        # the first time we wired a fresh demo app: commented-out
+        # `authentication_method` / `current_user_method` in the
+        # ActiveAdmin initializer, and forgetting to migrate.
+        def print_next_steps
+          say ""
+          say "=" * 60, :green
+          say "activeadmin-oidc: next steps", :green
+          say "=" * 60, :green
+          say <<~STEPS
+            1. In config/initializers/active_admin.rb, uncomment:
+                 config.authentication_method = :authenticate_admin_user!
+                 config.current_user_method   = :current_admin_user
+               Without these, /admin is public and the utility nav
+               (including the logout button) renders empty.
+
+            2. In app/models/admin_user.rb, make sure the devise call
+               includes:
+                 :omniauthable, omniauth_providers: [:oidc]
+
+            3. Fill in the generated config/initializers/activeadmin_oidc.rb
+               with your issuer and client_id (plus client_secret if you
+               are NOT using PKCE public-client mode).
+
+            4. Apply the generated migration:
+                 bin/rails db:migrate
+          STEPS
+          say "=" * 60, :green
+        end
+
         private
 
         # Postgres gets `jsonb` (fast, indexable), everything else

spec/generators/install_generator_spec.rb

@@ -54,15 +54,18 @@ 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.
+    # "create file" log lines don't pollute rspec output, but capture
+    # it so tests can assert on warnings and next-steps output.
     generator = described_class.new(args, [], destination_root: destination_root)
     orig_stdout = $stdout
-    $stdout = StringIO.new
+    captured = StringIO.new
+    $stdout = captured
     begin
       generator.invoke_all
     ensure
       $stdout = orig_stdout
     end
+    captured.string
   end
 
   describe "initializer" do
@@ -190,4 +193,85 @@ def run_generator(args = [])
       expect { run_generator }.to raise_error(Thor::Error, /activeadmin/)
     end
   end
+
+  describe "warnings for AdminUser devise setup" do
+    # These are soft checks: the generator still runs to completion,
+    # but prints a warning pointing the user at the missing wiring.
+    # Hard-failing would be too aggressive — the user may be mid-refactor
+    # and know what they're doing.
+
+    it "warns when AdminUser does not include :omniauthable" do
+      File.write(
+        File.join(destination_root, "app/models/admin_user.rb"),
+        <<~RUBY
+          class AdminUser < ApplicationRecord
+            devise :database_authenticatable, :rememberable
+          end
+        RUBY
+      )
+
+      output = run_generator
+      expect(output).to match(/:omniauthable/)
+      expect(output).to match(/admin_user\.rb/i)
+    end
+
+    it "warns when AdminUser does not declare omniauth_providers: [:oidc]" do
+      File.write(
+        File.join(destination_root, "app/models/admin_user.rb"),
+        <<~RUBY
+          class AdminUser < ApplicationRecord
+            devise :database_authenticatable, :omniauthable
+          end
+        RUBY
+      )
+
+      output = run_generator
+      expect(output).to match(/omniauth_providers.*:oidc/)
+    end
+
+    it "does NOT warn when AdminUser is already wired for oidc omniauth" do
+      File.write(
+        File.join(destination_root, "app/models/admin_user.rb"),
+        <<~RUBY
+          class AdminUser < ApplicationRecord
+            devise :database_authenticatable,
+                   :omniauthable, omniauth_providers: [:oidc]
+          end
+        RUBY
+      )
+
+      output = run_generator
+      expect(output).not_to match(/warning.*omniauthable/i)
+      expect(output).not_to match(/warning.*omniauth_providers/i)
+    end
+  end
+
+  describe "post-install next-steps message" do
+    it "prints a next-steps section after a successful run" do
+      output = run_generator
+      expect(output).to match(/next steps/i)
+    end
+
+    it "reminds the host to uncomment authentication_method in active_admin.rb" do
+      output = run_generator
+      expect(output).to include("authentication_method")
+      expect(output).to include(":authenticate_admin_user!")
+    end
+
+    it "reminds the host to uncomment current_user_method in active_admin.rb" do
+      output = run_generator
+      expect(output).to include("current_user_method")
+      expect(output).to include(":current_admin_user")
+    end
+
+    it "reminds the host to run the generated migration" do
+      output = run_generator
+      expect(output).to match(/db:migrate|rails\s+db:migrate/)
+    end
+
+    it "reminds the host to set AdminUser :omniauthable with omniauth_providers: [:oidc]" do
+      output = run_generator
+      expect(output).to include("omniauth_providers: [:oidc]")
+    end
+  end
 end