admin_suite 0.2.8 → 0.3.0

data/test/lib/resource_observability_extensions_test.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module AdminSuite
+  class ResourceObservabilityExtensionsTest < ActiveSupport::TestCase
+    FakeScope = Struct.new(:filters) do
+      def where(*arguments)
+        self.class.new(filters + [ arguments ])
+      end
+    end
+
+    class FilteredResource < Admin::Base::Resource
+      index do
+        filters do
+          filter :window, type: :select, default: "24h",
+            apply: ->(scope, value) { scope.where(window: value) }
+          filter :status, type: :select
+        end
+      end
+    end
+
+    class ReadOnlyResource < Admin::Base::Resource
+      read_only
+    end
+
+    test "resources are writable by default and may be declared read only" do
+      refute Admin::Base::Resource.read_only?
+      assert ReadOnlyResource.read_only?
+    end
+
+    test "filter defaults apply when the parameter is absent" do
+      scope = Admin::Base::FilterBuilder.new(FilteredResource, ActionController::Parameters.new)
+        .apply(FakeScope.new([]))
+
+      assert_equal [ [ { window: "24h" } ] ], scope.filters
+    end
+
+    test "filter defaults apply when the parameter is blank and compose with explicit filters" do
+      params = ActionController::Parameters.new(window: "", status: "failed")
+      scope = Admin::Base::FilterBuilder.new(FilteredResource, params).apply(FakeScope.new([]))
+
+      assert_equal [ [ { window: "24h" } ], [ { status: "failed" } ] ], scope.filters
+    end
+
+    test "an explicit filter overrides its default" do
+      params = ActionController::Parameters.new(window: "7d")
+      scope = Admin::Base::FilterBuilder.new(FilteredResource, params).apply(FakeScope.new([]))
+
+      assert_equal [ [ { window: "7d" } ] ], scope.filters
+    end
+  end
+end

data/test/test_helper.rb

@@ -22,3 +22,46 @@ require "action_dispatch/testing/integration"
 
 # Ensure the engine is loaded (and its initializers run).
 require "admin_suite"
+
+# The dummy app is intentionally database-free, while the generic controller
+# supports Active Record hosts. Supply only the exception type its lookup path
+# rescues so show-page behavior can be exercised with an in-memory fixture.
+unless defined?(ActiveRecord::RecordNotFound)
+  module ActiveRecord
+    class RecordNotFound < StandardError; end
+  end
+end
+
+module TurboFrameTestHelper
+  def turbo_frame_tag(name, **options, &block)
+    content_tag(:turbo_frame, capture(&block), id: name, **options)
+  end
+end
+
+ActionView::Base.include(TurboFrameTestHelper)
+
+module ReadOnlyResourceFixtures
+  class Relation
+    include Enumerable
+
+    def initialize(records)
+      @records = records
+    end
+
+    def each(&block)
+      @records.each(&block)
+    end
+
+    def count(*)
+      @records.count
+    end
+
+    def offset(*)
+      self
+    end
+
+    def limit(*)
+      self
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: admin_suite
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.3.0
 platform: ruby
 authors:
 - TechWright Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -173,23 +173,15 @@ files:
 - app/views/layouts/admin_suite/application.html.erb
 - config/importmap.rb
 - config/routes.rb
-- docs/README.md
-- docs/actions.md
-- docs/configuration.md
-- docs/development.md
-- docs/docs_viewer.md
-- docs/fields.md
-- docs/installation.md
-- docs/portals.md
-- docs/releasing.md
-- docs/resources.md
-- docs/theming.md
-- docs/troubleshooting.md
 - lib/admin/base/action_executor.rb
 - lib/admin/base/action_handler.rb
 - lib/admin/base/filter_builder.rb
 - lib/admin/base/resource.rb
 - lib/admin_suite.rb
+- lib/admin_suite/auth.rb
+- lib/admin_suite/auth/host_hook.rb
+- lib/admin_suite/auth/http_basic.rb
+- lib/admin_suite/auth/strategy.rb
 - lib/admin_suite/configuration.rb
 - lib/admin_suite/engine.rb
 - lib/admin_suite/markdown_renderer.rb
@@ -209,6 +201,7 @@ files:
 - lib/generators/admin_suite/scaffold/scaffold_generator.rb
 - lib/tasks/admin_suite_tailwind.rake
 - lib/tasks/admin_suite_test.rake
+- test/controllers/resources_controller_test.rb
 - test/dummy/Gemfile
 - test/dummy/README.md
 - test/dummy/Rakefile
@@ -233,6 +226,7 @@ files:
 - test/dummy/config/environments/development.rb
 - test/dummy/config/environments/production.rb
 - test/dummy/config/environments/test.rb
+- test/dummy/config/initializers/admin_suite_auth.rb
 - test/dummy/config/initializers/assets.rb
 - test/dummy/config/initializers/content_security_policy.rb
 - test/dummy/config/initializers/filter_parameter_logging.rb
@@ -251,11 +245,18 @@ files:
 - test/dummy/public/robots.txt
 - test/dummy/test/test_helper.rb
 - test/fixtures/docs/progress/PROGRESS_REPORT.md
+- test/integration/authentication_test.rb
+- test/integration/authorization_test.rb
 - test/integration/dashboard_test.rb
 - test/integration/docs_test.rb
+- test/integration/read_only_resource_test.rb
 - test/integration/theme_test.rb
 - test/lib/action_executor_test.rb
+- test/lib/auth_http_basic_test.rb
+- test/lib/auth_resolution_test.rb
+- test/lib/auth_test.rb
 - test/lib/markdown_renderer_test.rb
+- test/lib/resource_observability_extensions_test.rb
 - test/lib/theme_palette_test.rb
 - test/lib/zeitwerk_integration_test.rb
 - test/test_helper.rb

data/docs/README.md

@@ -1,26 +0,0 @@
-# AdminSuite Documentation
-
-AdminSuite is a mountable Rails engine that provides:
-
-- A **resource DSL** for CRUD + search/sort/filter + show/form configuration
-- A **portal system** (navigation + optional portal dashboards)
-- A built-in **docs viewer** (renders Markdown from your host app filesystem)
-- A small baseline **UI layer** (Tailwind optional)
-
-## Getting started
-
-- [Installation](installation.md)
-- [Configuration](configuration.md)
-- [Portals & dashboards](portals.md)
-- [Resources](resources.md)
-- [Fields](fields.md)
-- [Actions](actions.md)
-- [Theming & assets](theming.md)
-- [Docs viewer](docs_viewer.md)
-- [Troubleshooting](troubleshooting.md)
-
-## Contributing / maintainers
-
-- [Development](development.md)
-- [Releasing](releasing.md)
-

data/docs/actions.md

@@ -1,98 +0,0 @@
-# Actions
-
-AdminSuite supports three action “shapes” in the resource DSL:
-
-- `action` (member action on a single record)
-- `bulk_action` (runs across selected records)
-- `collection_action` (runs on a scope / collection)
-
-## Defining actions
-
-```ruby
-actions do
-  action :reindex, label: "Reindex", method: :post, confirm: "Reindex this record?"
-  bulk_action :archive, label: "Archive", confirm: "Archive selected records?"
-end
-```
-
-Supported action options:
-
-- `method:` HTTP method (default `:post`)
-- `label:` button label (default is humanized action name)
-- `icon:` lucide icon name (optional)
-- `color:` (optional)
-- `confirm:` string confirmation (optional)
-- `type:` reserved (default `:button`)
-- `if:` Proc condition (member actions only)
-- `unless:` Proc condition (member actions only)
-
-## How actions execute
-
-When you trigger an action, AdminSuite resolves behavior in this order:
-
-1. **Model method**: if the target responds to `action_name`, it calls that method.
-2. **Bang model method**: else if it responds to `action_name!`, it calls that.
-3. **Action handler class**: else it tries to find a handler class.
-
-### Handler class naming convention
-
-By default, AdminSuite looks for:
-
-```ruby
-Admin::Actions::<ResourceName><ActionName>Action
-```
-
-Example for `UserResource` + `:reset_password`:
-
-```ruby
-Admin::Actions::UserResetPasswordAction
-```
-
-Handlers should inherit from `Admin::Base::ActionHandler`:
-
-```ruby
-# app/admin/actions/user_reset_password_action.rb
-module Admin
-  module Actions
-    class UserResetPasswordAction < Admin::Base::ActionHandler
-      def call
-        # record is available as `record`, actor as `actor`, request params as `params`
-        record.send_reset_password_instructions!
-        success "Reset email sent."
-      rescue StandardError => e
-        failure "Failed to send reset: #{e.message}"
-      end
-    end
-  end
-end
-```
-
-## Overriding handler resolution (`config.resolve_action_handler`)
-
-If your app doesn’t want to follow the default naming convention, you can provide a resolver:
-
-```ruby
-AdminSuite.configure do |config|
-  config.resolve_action_handler = ->(resource_class, action_name) do
-    # return a Class or nil
-    if resource_class.name == "Admin::Resources::UserResource" && action_name.to_sym == :reset_password
-      Admin::Actions::UserResetPasswordAction
-    end
-  end
-end
-```
-
-## Auditing hook (`config.on_action_executed`)
-
-You can record or log all actions after they run:
-
-```ruby
-AdminSuite.configure do |config|
-  config.on_action_executed = ->(actor:, action_name:, resource_class:, subject:, params:, result:) do
-    Rails.logger.info(
-      "[admin_suite] actor=#{actor&.id} action=#{resource_class.name}##{action_name} success=#{result.success?}"
-    )
-  end
-end
-```
-

data/docs/configuration.md

@@ -1,284 +0,0 @@
-# Configuration
-
-AdminSuite is configured via an initializer:
-
-- `config/initializers/admin_suite.rb` (generated by `bin/rails g admin_suite:install`)
-
-All configuration lives on `AdminSuite.config` (an `AdminSuite::Configuration` instance).
-
-## Minimal secure configuration
-
-```ruby
-# config/initializers/admin_suite.rb
-AdminSuite.configure do |config|
-  config.authenticate = ->(controller) do
-    # Example: require an admin user
-    controller.redirect_to(controller.main_app.root_path) unless controller.respond_to?(:current_user) && controller.current_user&.admin?
-  end
-
-  config.current_actor = ->(controller) do
-    controller.respond_to?(:current_user) ? controller.current_user : nil
-  end
-end
-```
-
-## Defaults
-
-These are the defaults in `AdminSuite::Configuration` / `AdminSuite::Engine`:
-
-- `authenticate`: `nil`
-- `current_actor`: `nil`
-- `authorize`: `nil`
-- `logout_path`: `nil`
-- `logout_method`: `:delete`
-- `logout_label`: `"Log out"`
-- `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`
-- `dashboard_globs`: defaults to:
-  - `Rails.root/config/admin_suite/dashboard.rb`
-  - `Rails.root/config/admin_suite/dashboard/*.rb`
-  - `Rails.root/app/admin_suite/dashboard.rb`
-  - `Rails.root/app/admin_suite/dashboard/*.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)
-- `docs_url`: `nil`
-- `docs_path`: `Rails.root.join("docs")`
-- `partials`: `{}`
-- `theme`: `{ primary: :indigo, secondary: :purple }`
-- `host_stylesheet`: `nil`
-- `tailwind_cdn`: `true`
-- `on_action_executed`: `nil`
-- `resolve_action_handler`: `nil`
-
-## Options
-
-### `authenticate`
-
-Called as a `before_action` inside the engine.
-
-- **Type**: `Proc` or `nil`
-- **Signature**: `->(controller) { ... }`
-
-If you don’t set it, AdminSuite will be accessible to any user that can reach the mounted route.
-
-### `current_actor`
-
-Used by actions/auditing hooks to identify “who initiated this”.
-
-- **Type**: `Proc` or `nil`
-- **Signature**: `->(controller) { current_user }`
-
-### `authorize`
-
-Optional authorization hook (you can wire Pundit/CanCan/ActionPolicy/etc).
-
-- **Type**: `Proc` or `nil`
-- **Signature**: `->(actor, action:, subject:, resource:, controller:) { true/false }`
-
-Note: this hook is available, but your app must call it from resource definitions / custom actions as needed (AdminSuite will not guess your authorization policy).
-
-### `logout_path`
-
-Optional sign-out action shown in the top bar.
-
-- **Type**: `Proc`, `String`, `Symbol`, or `nil`
-- **Proc signature**: `->(view_context) { ... }`
-
-Example:
-
-```ruby
-config.logout_path = ->(view) { view.main_app.internal_developer_logout_path }
-```
-
-### `logout_method`
-
-HTTP method for the topbar sign-out button.
-
-- **Type**: `Symbol` or `String`
-- **Default**: `:delete`
-
-### `logout_label`
-
-Button label for the topbar sign-out action.
-
-- **Type**: `String` (or `Proc` for dynamic label)
-- **Default**: `"Log out"`
-
-### `resource_globs`
-
-Where AdminSuite should load resource definition files from.
-
-- **Type**: `Array<String>`
-
-Example:
-
-```ruby
-config.resource_globs = [
-  Rails.root.join("app/admin/resources/**/*.rb").to_s
-]
-```
-
-### `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) { ... }`).
-
-- **Type**: `Array<String>`
-
-### `dashboard_globs`
-
-Where AdminSuite should load the root dashboard definition file(s) from (files typically call `AdminSuite.root_dashboard { ... }`).
-
-- **Type**: `Array<String>`
-
-### `root_dashboard_title`
-
-Optional title shown on the root dashboard.
-
-- **Type**: `String`, `Proc`, or `nil`
-- **Proc signature**: `->(controller) { "Admin Suite" }`
-
-### `root_dashboard_description`
-
-Optional description shown on the root dashboard.
-
-- **Type**: `String`, `Proc`, or `nil`
-- **Proc signature**: `->(controller) { "..." }`
-
-### `portals`
-
-Portal metadata used for navigation (label/icon/color/order). This is separate from the portal DSL and can be used alone.
-
-- **Type**: `Hash{Symbol => Hash}`
-
-Example:
-
-```ruby
-config.portals = {
-  ops: { label: "Ops", icon: "settings", color: :amber, order: 10 },
-  billing: { label: "Billing", icon: "credit-card", color: :emerald, order: 20 }
-}
-```
-
-### `theme`
-
-Two-color theme used to set CSS variables scoped to AdminSuite.
-
-- **Type**: `Hash` with `:primary` and `:secondary`
-- **Values**: Tailwind-ish color names (`:indigo`, `:emerald`, …) or a hex string (`"#4f46e5"`)
-
-See [Theming & assets](theming.md).
-
-### `host_stylesheet`
-
-If set, AdminSuite will include your host app stylesheet **after** its own styles in the engine layout.
-
-- **Type**: `Symbol` or `String` (passed to `stylesheet_link_tag`)
-- **Example**: `config.host_stylesheet = :app`
-
-### `tailwind_cdn`
-
-Reserved for host setups that want a CDN fallback. (AdminSuite already builds its own Tailwind CSS into your host app during `assets:precompile`.)
-
-- **Type**: `true/false`
-
-### `docs_url`
-
-If set, shows a “Docs” link in the AdminSuite sidebar.
-
-- **Type**: `String` or `nil`
-
-### `docs_path`
-
-Filesystem path where the docs viewer reads markdown from.
-
-- **Type**: `Pathname`, `String`, or `Proc`
-- **Proc signature**: `->(controller) { Rails.root.join("docs") }`
-
-### `partials`
-
-Override specific engine partials.
-
-- **Type**: `Hash`
-
-Example:
-
-```ruby
-config.partials[:flash] = "shared/flash"
-config.partials[:panel_stat] = "admin/panels/stat"
-```
-
-### `custom_renderers`
-
-Register custom show-section renderers (used when a show panel uses `render: :your_key`).
-
-- **Type**: `Hash{Symbol => Proc}`
-- **Proc signature**: `->(record, view_context) { ... }`
-
-Example:
-
-```ruby
-config.custom_renderers[:billing_snapshot] = ->(record, view) do
-  view.render(partial: "admin/billing_snapshot", locals: { record: record })
-end
-```
-
-### `icon_renderer`
-
-Replace the default icon provider (lucide-rails).
-
-- **Type**: `Proc` or `nil`
-- **Proc signature**: `->(name, view_context, **opts) { ... }`
-
-### `resolve_action_handler`
-
-Override how AdminSuite finds action handler classes.
-
-- **Type**: `Proc` or `nil`
-- **Proc signature**: `->(resource_class, action_name) { handler_class_or_nil }`
-
-See [Actions](actions.md).
-
-### `on_action_executed`
-
-Hook called after action execution (success or failure).
-
-- **Type**: `Proc` or `nil`
-- **Proc signature**: `->(actor:, action_name:, resource_class:, subject:, params:, result:) { ... }`
-

data/docs/development.md

@@ -1,64 +0,0 @@
-# Development
-
-This page is intended for contributors/maintainers working on the engine itself.
-
-## Setup
-
-From the gem root:
-
-```bash
-bundle install
-```
-
-## Run tests
-
-```bash
-bundle exec rake test
-```
-
-## Dummy app
-
-AdminSuite uses a Rails “dummy” app under `test/dummy` for integration tests and to
-exercise routing/assets in a host-like environment.
-
-Useful commands (from the gem root):
-
-```bash
-cd test/dummy
-bin/rails s
-```
-
-## Assets / Tailwind
-
-AdminSuite ships:
-
-- `app/assets/admin_suite.css` (baseline CSS)
-- `app/assets/tailwind/admin_suite.css` (Tailwind input)
-
-The engine Tailwind build task writes the compiled CSS into the **host app** builds folder:
-
-- Output: `Rails.root/app/assets/builds/admin_suite_tailwind.css`
-
-In a host app, this is run automatically during `assets:precompile`:
-
-```bash
-bin/rails admin_suite:tailwind:build
-```
-
-When developing inside the engine repo itself, you can run it from the dummy app:
-
-```bash
-cd test/dummy
-bin/rails admin_suite:tailwind:build
-```
-
-## Docs
-
-Engine docs live under:
-
-- `docs/`
-
-The docs viewer feature in the engine reads from the host app by default:
-
-- `Rails.root/docs` (configurable via `AdminSuite.config.docs_path`)
-