admin_suite 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbd2bda3cff05667e7f164b70d06c7f91e4ba7cde4dfe720291720fe589cfde6
-  data.tar.gz: c2fea65bd3721677eee67904174664038c9e256d347770775bbfc3a3714bceb2
+  metadata.gz: 8a3f83815ccce6bcb0e0a38e07e0b90d6d969309b2e3302e1870135f02793762
+  data.tar.gz: 2564e620eaa8c66030d8f774b1d4246eaa4359955ce2a5670f62f069a88a58af
 SHA512:
-  metadata.gz: 68580753a81e6e77b5a3cda22038f5d62919ab22e3bb00746504e18578847119528872f0bf94960c6d7d0df3ceb06a7df723ae872e8cce7d6d240fc0a5c08ab6
-  data.tar.gz: b342407db536c0cd5f7264aff7ea6fa57f224b03b66d2675b1b928394490ee743424ea7608ff9845e71e391765ecac7da0823e101b1922cea9c8613dae44c48a
+  metadata.gz: '071608f05dc059b788b90350e9cfbd590d417bf124f3327dbf151202d32f2c71359f3c6ba442e13fba7138d8fc7b28d96e52687825bf64beb66c4058dd640eb9'
+  data.tar.gz: ac7a393a423342b228c9489492d361e34f98afaaf9e9527a1a71639ecc3d0ee7ce59ddfae3988d1d83ccac474a69764ce7b7d7afed0e346026642bd9c69bb3f2

data/.gitignore

@@ -8,4 +8,5 @@
 !/test/dummy/log/.keep
 /test/dummy/tmp/
 /test/dummy/storage/
-admin_suite-*.gem
+admin_suite-*.gem
+/.bundle/

data/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to AdminSuite
+
+Thank you for your interest in contributing to AdminSuite!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork locally
+3. Install dependencies: `bundle install`
+4. Run the test suite: `bundle exec rake test`
+5. (Optional) Run tests with coverage: `COVERAGE=true bundle exec rake test`
+
+## Development
+
+See `docs/development.md` for detailed information on:
+- Setting up your development environment
+- Running tests
+- Code style guidelines
+
+## Pull Requests
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Add or update tests as needed
+4. Ensure all tests pass: `bundle exec rake test`
+5. Push your branch and create a pull request
+
+### CI Checks
+
+All pull requests must pass the following checks before merging:
+- **Tests**: Automated test suite runs on Ruby 3.2 and 3.3
+- **Coverage**: Code coverage is automatically generated and uploaded to Codecov
+- **Code Review**: At least one maintainer approval required
+
+The CI workflow runs automatically on every pull request.
+
+## Releasing
+
+See `docs/releasing.md` for information on how releases are managed.
+
+Releases are automated via GitHub Actions when changes are merged to `main` with a version bump.
+
+### Required Secrets for Maintainers
+
+The repository requires the following secrets to be configured:
+- **`RUBYGEMS_API_KEY`**: Required for automated gem publishing to RubyGems
+- **`CODECOV_TOKEN`**: Optional, for uploading code coverage reports to Codecov (workflow continues without it)
+
+## Questions?
+
+Feel free to open an issue for questions or discussion.

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,10 +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: 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)
@@ -89,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/docs/releasing.md

@@ -2,15 +2,39 @@
 
 This page is intended for maintainers publishing `admin_suite` to RubyGems.
 
-## Checklist
+## Automated Release Process (Recommended)
 
-1. Bump the version
+The gem is automatically published to RubyGems when changes are merged to `main`, provided the version has been bumped.
 
-- Update `lib/admin_suite/version.rb`
+### Steps
 
-2. Update changelog
+1. **Bump the version**
+   - Update `lib/admin_suite/version.rb`
+
+2. **Update changelog**
+   - Add an entry to `CHANGELOG.md`
+
+3. **Create a PR and get it merged**
+   - The CI workflow will run tests automatically on the PR
+   - Once merged to `main`, after CI passes, the publish workflow will:
+     - Check if the version already exists on RubyGems
+     - Build and publish the gem (if it's a new version)
+     - Create a Git tag for the release (if it doesn't already exist)
+
+### Requirements
+
+- The `RUBYGEMS_API_KEY` secret must be configured in the repository settings
+- The version in `lib/admin_suite/version.rb` must be unique (not already published)
 
-- Add an entry to `CHANGELOG.md`
+## Manual Release Process
+
+If you need to publish manually:
+
+1. Bump the version
+   - Update `lib/admin_suite/version.rb`
+
+2. Update changelog
+   - Add an entry to `CHANGELOG.md`
 
 3. Run tests and build the gem
 
@@ -19,7 +43,7 @@ bundle exec rake test
 gem build admin_suite.gemspec
 ```
 
-4. (Recommended) Tag the release
+4. Tag the release
 
 ```bash
 git tag -a "vX.Y.Z" -m "AdminSuite vX.Y.Z"
@@ -32,7 +56,10 @@ git push --tags
 gem push "admin_suite-X.Y.Z.gem"
 ```
 
-Notes:
+## Notes
 
-- RubyGems commonly requires MFA/OTP for pushes (this gem is configured with `rubygems_mfa_required`).
+- RubyGems commonly requires MFA/OTP for pushes (this gem is configured with `rubygems_mfa_required`)
+- The automated workflow uses a GitHub Actions bot to push tags
+- The publish workflow only runs after the CI workflow completes successfully
+- You can manually trigger the publish workflow from the GitHub Actions tab if needed
 

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,15 +13,65 @@ module AdminSuite
       end
     end
 
-    initializer "admin_suite.host_dsl_ignore" do
-      # Host apps sometimes store AdminSuite DSL files under `app/admin_suite/**`.
-      # Those are not constant definitions, so we must prevent Zeitwerk from
-      # expecting constants like `Portals::Ai` during eager load.
-      host_dsl_dir = Rails.root.join("app/admin_suite")
-      next unless host_dsl_dir.exist?
+    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 (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|
-        loader.ignore(host_dsl_dir)
+        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
 
@@ -33,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?
 
@@ -65,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.1.2"
+    VERSION = "0.2.1"
   end
 
   # Backward-compatible constant.

data/lib/admin_suite.rb

@@ -34,7 +34,10 @@ module AdminSuite
 
     # Defines (or updates) a portal using a Ruby DSL.
     #
-    # Host apps typically place these in `app/admin/portals/*.rb`.
+    # Host apps typically place these in:
+    # - `config/admin_suite/portals/*.rb` (recommended; not a Zeitwerk autoload path)
+    # - `app/admin_suite/portals/*.rb` (supported; AdminSuite ignores for Zeitwerk)
+    # - `app/admin/portals/*.rb` (supported; AdminSuite will ignore for Zeitwerk if files contain `AdminSuite.portal`)
     #
     # @param key [Symbol, String]
     # @yield Portal definition DSL

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

@@ -20,10 +20,23 @@ 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 = [
     Rails.root.join("config/admin_suite/portals/*.rb").to_s,
+    # Prefer `app/admin_suite/portals` for DSL files so Zeitwerk never expects
+    # application constants (e.g. `Admin::Portals::OpsPortal` for
+    # `app/admin/portals/ops_portal.rb`) during eager load.
+    Rails.root.join("app/admin_suite/portals/*.rb").to_s,
+    # Legacy/fallback: still support portals defined under app/admin/portals.
     Rails.root.join("app/admin/portals/*.rb").to_s
   ]