admin_suite 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f761dd4e5538b7fb655ce9a29c936bfa57d1cf56e06d3aa73e064e4721ec69a9
-  data.tar.gz: e4a584d9645f7f848ad48c6f94a47ce34d9a9820cbe1c6271c635b17f1176719
+  metadata.gz: 8a3f83815ccce6bcb0e0a38e07e0b90d6d969309b2e3302e1870135f02793762
+  data.tar.gz: 2564e620eaa8c66030d8f774b1d4246eaa4359955ce2a5670f62f069a88a58af
 SHA512:
-  metadata.gz: 9e0c72f5c7494b4a5378cd0895781bbbb41c8ed372788bf9cbcbeaa2830866f87c0636fce56872ee6998dbb516552f8bd105a828864ee29d7f23cc2ec77949e5
-  data.tar.gz: 4f2fc0a2d4d6edcb75ab99d7e888e8cd7abef38a9790e5ff45b74f8a8e6e9b6d7d657186776e2fc4132b59b051b21769ff966b2a33f050007505648116a74652
+  metadata.gz: '071608f05dc059b788b90350e9cfbd590d417bf124f3327dbf151202d32f2c71359f3c6ba442e13fba7138d8fc7b28d96e52687825bf64beb66c4058dd640eb9'
+  data.tar.gz: ac7a393a423342b228c9489492d361e34f98afaaf9e9527a1a71639ecc3d0ee7ce59ddfae3988d1d83ccac474a69764ce7b7d7afed0e346026642bd9c69bb3f2

data/app/controllers/admin_suite/application_controller.rb

@@ -35,12 +35,11 @@ module AdminSuite
       nil
     end
 
-    # Loads resource definition files in development when needed.
+    # Loads resource definition files when needed (runs in all environments).
     #
     # @return [void]
     def ensure_resources_loaded!
       require "admin/base/resource" unless defined?(Admin::Base::Resource)
-      return unless Rails.env.development?
       return if Admin::Base::Resource.registered_resources.any?
 
       Array(AdminSuite.config.resource_globs).flat_map { |g| Dir[g] }.uniq.each do |file|

data/docs/configuration.md

@@ -32,16 +32,27 @@ These are the defaults in `AdminSuite::Configuration` / `AdminSuite::Engine`:
 - `resource_globs`: defaults to:
   - `Rails.root/config/admin_suite/resources/*.rb`
   - `Rails.root/app/admin/resources/*.rb`
+- `action_globs`: defaults to:
+  - `Rails.root/config/admin_suite/actions/*.rb`
+  - `Rails.root/app/admin/actions/*.rb`
 - `portal_globs`: defaults to:
   - `Rails.root/config/admin_suite/portals/*.rb`
   - `Rails.root/app/admin/portals/*.rb`
   - `Rails.root/app/admin_suite/portals/*.rb`
 
-Note: portal files are DSL side-effects (they don't define constants). If your host app
-autoloads `app/admin` as `Admin::*` with Zeitwerk, AdminSuite will ignore
-`app/admin/portals` for Zeitwerk to prevent eager-load `Zeitwerk::NameError`s.
-We recommend placing portal DSL files under `config/admin_suite/portals` or
-`app/admin_suite/portals` when possible.
+Note: AdminSuite definition files (resources, actions, portals) often don't follow 
+Zeitwerk's path-to-constant naming conventions. To prevent eager-load `Zeitwerk::NameError`s 
+in production, the engine only configures Zeitwerk to ignore these directories and load them via globs instead:
+- `app/admin_suite`
+- `app/admin/portals` (when portal DSL usage is detected)
+
+Other `app/admin/*` directories (such as `app/admin/resources`, `app/admin/actions`, and `app/admin/base`) are
+not ignored by default and may be treated as normal Zeitwerk autoload paths if they are added to the loader
+(for example, via `loader.push_dir("app/admin")` in the host app). Do not rely on these directories being
+ignored for autoloading; instead, keep files there Zeitwerk-compatible.
+
+We recommend placing non-Zeitwerk-compatible definition files under `config/admin_suite/*` or `app/admin_suite/*` 
+for clearer separation from standard Rails autoloading.
 - `portals`: default portal metadata for `:ops`, `:email`, `:ai`, `:assistant`
 - `custom_renderers`: `{}`
 - `icon_renderer`: `nil` (uses lucide-rails by default when available)
@@ -95,6 +106,20 @@ config.resource_globs = [
 ]
 ```
 
+### `action_globs`
+
+Where AdminSuite should load action handler files from (files that define custom action handlers, typically subclasses of `Admin::Base::ActionHandler`).
+
+- **Type**: `Array<String>`
+
+Example:
+
+```ruby
+config.action_globs = [
+  Rails.root.join("app/admin/actions/**/*.rb").to_s
+]
+```
+
 ### `portal_globs`
 
 Where AdminSuite should load portal definition files from (files typically call `AdminSuite.portal(:key) { ... }`).

data/lib/admin/base/action_executor.rb

@@ -12,6 +12,13 @@ module Admin
         def failure? = !success
       end
 
+      # Track whether action handlers have been loaded to avoid repeated expensive globs
+      @handlers_loaded = false
+
+      class << self
+        attr_accessor :handlers_loaded
+      end
+
       def initialize(resource_class, action_name, actor)
         @resource_class = resource_class
         @action_name = action_name
@@ -116,6 +123,17 @@ module Admin
           return resolved if resolved
         end
 
+        handler_name = "#{resource_class.resource_name.camelize}#{action.name.to_s.camelize}Action"
+        handler_constant = "Admin::Actions::#{handler_name}"
+        handler_constant.constantize
+      rescue NameError
+        # In many host apps, action handlers live under `app/admin/actions/**`.
+        # Rails treats `app/admin` as a Zeitwerk root, which means Zeitwerk expects
+        # top-level constants (e.g. `Actions::Foo`) unless the host configures
+        # a namespace mapping. AdminSuite avoids requiring host Zeitwerk setup by
+        # loading handler files via `AdminSuite.config.action_globs` when needed.
+        load_action_handlers_for_admin_suite!
+
         handler_name = "#{resource_class.resource_name.camelize}#{action.name.to_s.camelize}Action"
         "Admin::Actions::#{handler_name}".constantize
       rescue NameError
@@ -150,6 +168,57 @@ module Admin
       rescue StandardError
         nil
       end
+
+      def load_action_handlers_for_admin_suite!
+        return unless defined?(AdminSuite)
+
+        # Track whether we've already loaded handlers to avoid expensive repeated globs.
+        # In development, this flag is reset by the Rails reloader (see engine.rb).
+        # In production/test, it persists for the process lifetime.
+        return if self.class.handlers_loaded
+
+        files = Array(AdminSuite.config.action_globs).flat_map { |g| Dir[g] }.uniq
+
+        # Set the flag even if no files found - we've done the glob and shouldn't repeat it
+        if files.empty?
+          self.class.handlers_loaded = true
+          return
+        end
+
+        files.each do |file|
+          begin
+            if Rails.env.development?
+              load file
+            else
+              require file
+            end
+          rescue StandardError, ScriptError => e
+            log_action_handler_load_error(file, e)
+
+            # Fail fast in dev/test so broken handler files are immediately discoverable.
+            raise if Rails.env.development? || Rails.env.test?
+          end
+        end
+
+        # We attempted to load the configured handlers. Avoid repeating expensive globs
+        # and file loads for the rest of the process lifetime.
+        self.class.handlers_loaded = true
+      end
+
+      def log_action_handler_load_error(file, error)
+        message = "[AdminSuite] Failed to load action handler file #{file}: #{error.class}: #{error.message}"
+
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.error(message)
+
+          backtrace = Array(error.backtrace).take(20).join("\n")
+          Rails.logger.error(backtrace) unless backtrace.empty?
+        else
+          warn(message)
+        end
+      rescue StandardError
+        nil
+      end
     end
   end
 end

data/lib/admin_suite/configuration.rb

@@ -7,6 +7,7 @@ module AdminSuite
       :current_actor,
       :authorize,
       :resource_globs,
+      :action_globs,
       :portal_globs,
       :portals,
       :custom_renderers,
@@ -25,6 +26,7 @@ module AdminSuite
       @current_actor = nil
       @authorize = nil
       @resource_globs = []
+      @action_globs = []
       @portal_globs = []
       @portals = {}
       @custom_renderers = {}

data/lib/admin_suite/engine.rb

@@ -13,41 +13,65 @@ module AdminSuite
       end
     end
 
-    initializer "admin_suite.host_dsl_ignore" do
-      # Host apps sometimes store AdminSuite DSL files under `app/admin_suite/**`
-      # and/or `app/admin/portals/**`.
+    initializer "admin_suite.host_dsl_ignore", before: :setup_main_autoloader do |app|
+      # Host apps may store AdminSuite DSL files under `app/admin_suite/**` and
+      # `app/admin/portals/**`.
       #
-      # These are *side-effect* DSL files (e.g. `AdminSuite.portal :ops do ... end`),
-      # not constant definitions. If a host app adds those dirs to Zeitwerk (common
-      # when autoloading `app/admin` as `Admin::*`), eager loading will crash with:
-      #   expected file ... to define constant ...
-      #
-      # So we proactively ignore these directories for all Zeitwerk loaders.
-      host_dsl_dirs = [ Rails.root.join("app/admin_suite") ]
-
-      # `app/admin/portals` is a more common location in host apps and could also
-      # contain real constants. Only ignore it if it appears to contain AdminSuite
-      # portal DSL definitions.
-      host_admin_portals_dir = Rails.root.join("app/admin/portals")
-      if host_admin_portals_dir.exist?
-        portal_files = Dir[host_admin_portals_dir.join("**/*.rb").to_s]
-        contains_admin_suite_portals =
-          portal_files.any? do |file|
-            content = File.binread(file)
-            content = content.encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
-            portal_dsl_pattern = /(::)?AdminSuite\s*\.\s*portal\b/
-            portal_dsl_pattern.match?(content)
-          rescue StandardError
-            false
-          end
-
-        host_dsl_dirs << host_admin_portals_dir if contains_admin_suite_portals
+      # These are side-effect DSL files (they do not define constants), so Zeitwerk
+      # must ignore them to avoid eager-load `Zeitwerk::NameError`s in production.
+
+      admin_suite_app_dir = Rails.root.join("app/admin_suite")
+      admin_dir = Rails.root.join("app/admin")
+      admin_portals_dir = Rails.root.join("app/admin/portals")
+
+      # If the host uses `Admin::*` constants inside `app/admin/**`, Rails' default
+      # autoload root (`app/admin`) would expect top-level constants like
+      # `Resources::UserResource`. We fix that by mapping `app/admin` to `Admin`.
+      # This avoids requiring host apps to add their own Zeitwerk initializer.
+      if admin_dir.exist? && self.class.host_admin_namespace_files?(admin_dir)
+        admin_dir_s = admin_dir.to_s
+        app.config.autoload_paths.delete(admin_dir_s)
+        app.config.eager_load_paths.delete(admin_dir_s)
+
+        # Ensure `Admin` exists so Zeitwerk can use it as a namespace.
+        module ::Admin; end
+
+        Rails.autoloaders.main.push_dir(admin_dir, namespace: ::Admin)
       end
 
       Rails.autoloaders.each do |loader|
-        host_dsl_dirs.each do |dir|
-          loader.ignore(dir) if dir.exist?
-        end
+        loader.ignore(admin_suite_app_dir) if admin_suite_app_dir.exist?
+
+        next unless admin_portals_dir.exist?
+
+        loader.ignore(admin_portals_dir) if self.class.contains_admin_suite_portal_dsl?(admin_portals_dir)
+      end
+    end
+
+    def self.host_admin_namespace_files?(admin_dir)
+      # True if any file under app/admin appears to define `Admin::*` constants.
+      Dir[admin_dir.join("**/*.rb").to_s].any? do |file|
+        next false if file.include?("/portals/")
+
+        content = File.binread(file)
+        content = content.encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+
+        content.match?(/\b(module|class)\s+Admin\b/) ||
+          content.match?(/\b(module|class)\s+Admin::/)
+      rescue StandardError
+        false
+      end
+    end
+
+    def self.contains_admin_suite_portal_dsl?(admin_portals_dir)
+      portal_files = Dir[admin_portals_dir.join("**/*.rb").to_s]
+      portal_files.any? do |file|
+        content = File.binread(file)
+        content = content.encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+        portal_dsl_pattern = /(::)?AdminSuite\s*\.\s*portal\b/
+        portal_dsl_pattern.match?(content)
+      rescue StandardError
+        false
       end
     end
 
@@ -59,6 +83,17 @@ module AdminSuite
       require "admin/base/action_handler"
     end
 
+    initializer "admin_suite.reloader" do |app|
+      # Reset the handlers_loaded flag in development so handlers are reloaded
+      # when code changes. This ensures the expensive glob operation happens at
+      # most once per request (or code reload) rather than on every NameError.
+      if Rails.env.development?
+        app.reloader.to_prepare do
+          Admin::Base::ActionExecutor.handlers_loaded = false
+        end
+      end
+    end
+
     initializer "admin_suite.watchable_dirs" do |app|
       next unless Rails.env.development?
 
@@ -91,6 +126,13 @@ module AdminSuite
           ]
         end
 
+        if config.action_globs.blank?
+          config.action_globs = [
+            Rails.root.join("config/admin_suite/actions/*.rb").to_s,
+            Rails.root.join("app/admin/actions/*.rb").to_s
+          ]
+        end
+
         if config.portal_globs.blank?
           config.portal_globs = [
             Rails.root.join("config/admin_suite/portals/*.rb").to_s,

data/lib/admin_suite/version.rb

@@ -2,7 +2,7 @@
 
 module AdminSuite
   module Version
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 
   # Backward-compatible constant.

data/lib/generators/admin_suite/install/templates/admin_suite.rb

@@ -20,6 +20,14 @@ AdminSuite.configure do |config|
     Rails.root.join("app/admin/resources/*.rb").to_s
   ]
 
+  # Action handler file globs (host app can override).
+  #
+  # Files typically define `Admin::Actions::<Resource><Action>Action` handlers.
+  config.action_globs = [
+    Rails.root.join("config/admin_suite/actions/*.rb").to_s,
+    Rails.root.join("app/admin/actions/*.rb").to_s
+  ]
+
   # Portal dashboard DSL globs (host app can override).
   # Files typically call `AdminSuite.portal :ops do ... end`
   config.portal_globs = [