admin_suite 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f7c1be0b2abc25afb2d0e162c35694d27c03acb1c0db9aa5f7c75fdf9f5a0de
-  data.tar.gz: 5f969a9e650ccc2e135334658c00bda4fe59918d8b4f8402a43c7207ffd5b0cb
+  metadata.gz: fa02eb4d89f039fb322c1d967a8a8183d7a8d08073a1ca5efa3162722a44d4ad
+  data.tar.gz: e266e08457f21f178029a2321b0bef62826ae2ff17ff4ddee5163a856aabc807
 SHA512:
-  metadata.gz: afadac82d6a9e20a8b6416c1299e3cba56fc4f0cab22ca33987498c7809e44167743636dc991acf08d2d6d142b5eac4132a8f8fafb3f79cd7c1dd697b12ba861
-  data.tar.gz: d2dac896f3b213c9058ec702a9673201d4561a793105c2f552afa6a79c7d4896b716372737a08db4eb0c5230b5a7a1d719f9d98f20c994143f9393c8b52005dc
+  metadata.gz: 5180c720a4df074f35dfe87133beb75cdaca7e0b37d104d98bfd362366fd52c79f531510e8f6af1c149fce616687d9515727d5238c29881564658c2a4f51c831
+  data.tar.gz: 92a32f372ae2a098421b322da249fd8139710d8ebd1c9b598c105305ae95c8b0340c2d0976190dba529687e089877c8d4f703aa3ea66d8524837ca915d71aa29

data/.gitignore

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

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-04
+
+### Added
+
+- Initial extraction of the AdminSuite Rails engine.
+- Resource/portal DSL, docs viewer, and theming primitives.
+- Isolated gem test suite with a dummy Rails app.
+

data/README.md

@@ -1,7 +1,143 @@
 # AdminSuite
 
-A mountable Rails engine that provides a resource-based admin UI and generators.
+A mountable Rails engine that provides a **resource-based admin UI** (CRUD + search/filter/sort),
+a **portal/dashboard system**, and a built-in **Markdown docs viewer**.
 
 This engine is currently extracted from the Gleania app and is intended to be reused
 across other products.
 
+## Features
+
+- **Portals**: group resources by portal + section, optional per-portal dashboards
+- **Resources DSL**: index (columns/filters/stats), form fields, show panels/associations, actions
+- **Docs viewer**: renders `*.md` from your host app filesystem at `/docs`
+- **UI**: baseline CSS + engine Tailwind build; host overrides optional
+
+## Documentation
+
+Start here:
+
+- `docs/README.md` (index)
+
+Read more:
+
+- `docs/installation.md`
+- `docs/configuration.md`
+- `docs/portals.md`
+- `docs/resources.md`
+- `docs/fields.md`
+- `docs/actions.md`
+- `docs/theming.md`
+- `docs/docs_viewer.md`
+- `docs/troubleshooting.md`
+
+## Quickstart
+
+Add the gem:
+
+```ruby
+# Gemfile
+gem "admin_suite"
+```
+
+Install and generate the initializer + mount:
+
+```bash
+bundle install
+bin/rails g admin_suite:install
+```
+
+By default, the engine mounts at `/internal/admin`. You can customize it:
+
+```bash
+bin/rails g admin_suite:install --mount-path=/internal/admin
+```
+
+### Secure it (recommended)
+
+Set `config.authenticate` so only authorized users can access AdminSuite:
+
+```ruby
+# config/initializers/admin_suite.rb
+AdminSuite.configure do |config|
+  config.authenticate = ->(controller) do
+    user = controller.respond_to?(:current_user) ? controller.current_user : nil
+    controller.head(:forbidden) unless user&.admin?
+  end
+end
+```
+
+Read more: `docs/configuration.md`
+
+### Add portals (navigation metadata)
+
+```ruby
+AdminSuite.configure do |config|
+  config.portals = {
+    ops: { label: "Ops", icon: "settings", color: :amber, order: 10 },
+    ai: { label: "AI", icon: "cpu", color: :cyan, order: 20 }
+  }
+end
+```
+
+Read more: `docs/portals.md`
+
+### Add a resource
+
+Place resource definitions under one of the default globs (recommended):
+
+- `config/admin_suite/resources/*.rb`
+
+Example:
+
+```ruby
+# config/admin_suite/resources/user.rb
+module Admin
+  module Resources
+    class UserResource < Admin::Base::Resource
+      model ::User
+      portal :ops
+      section :accounts
+
+      index do
+        searchable :email, :name
+        sortable :created_at, default: :created_at, direction: :desc
+
+        columns do
+          column :id
+          column :email
+          column :created_at
+        end
+      end
+
+      form do
+        field :email, type: :email, required: true
+        field :name, required: true
+      end
+    end
+  end
+end
+```
+
+Read more: `docs/resources.md` and `docs/fields.md`
+
+### Add docs (optional)
+
+Create markdown files in your host app:
+
+- `docs/*.md` (or set `config.docs_path`)
+
+Then visit:
+
+- `/internal/admin/docs`
+
+Read more: `docs/docs_viewer.md`
+
+## Contributing
+
+See:
+
+- `CONTRIBUTING.md`
+- `docs/development.md`
+- `docs/releasing.md`
+

data/docs/README.md

@@ -0,0 +1,26 @@
+# 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

@@ -0,0 +1,98 @@
+# 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

@@ -0,0 +1,198 @@
+# 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`
+- `resource_globs`: defaults to:
+  - `Rails.root/config/admin_suite/resources/*.rb`
+  - `Rails.root/app/admin/resources/*.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`
+- `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).
+
+### `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
+]
+```
+
+### `portal_globs`
+
+Where AdminSuite should load portal definition files from (files typically call `AdminSuite.portal(:key) { ... }`).
+
+- **Type**: `Array<String>`
+
+### `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

@@ -0,0 +1,64 @@
+# 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`)
+

data/docs/docs_viewer.md

@@ -0,0 +1,79 @@
+# Docs viewer
+
+AdminSuite includes a built-in docs viewer at:
+
+- `/docs` (relative to the mount path)
+
+It renders Markdown (`.md`) files from a folder on your host app filesystem.
+
+## Quick start
+
+1. Create `docs/` in your host app:
+
+```bash
+mkdir -p docs
+```
+
+2. Add a markdown file:
+
+```md
+<!-- docs/getting_started.md -->
+# Getting started
+
+Hello from AdminSuite docs.
+```
+
+3. Visit:
+
+- `/internal/admin/docs`
+
+## Configuring the docs root (`config.docs_path`)
+
+By default:
+
+- `AdminSuite.config.docs_path = Rails.root.join("docs")`
+
+You can point it somewhere else:
+
+```ruby
+AdminSuite.configure do |config|
+  config.docs_path = Rails.root.join("admin_docs")
+end
+```
+
+Or compute per-request:
+
+```ruby
+AdminSuite.configure do |config|
+  config.docs_path = ->(_controller) { Rails.root.join("docs") }
+end
+```
+
+## Sidebar “Docs” link (`config.docs_url`)
+
+If you want a persistent docs link in the AdminSuite sidebar, set:
+
+```ruby
+AdminSuite.configure do |config|
+  config.docs_url = "/internal/admin/docs"
+end
+```
+
+This can also point to external docs.
+
+## Organization
+
+Docs are grouped by their first folder name. For example:
+
+- `docs/ops/runbooks.md` → group “Ops”
+- `docs/api/authentication.md` → group “API”
+- `docs/getting_started.md` → group “Docs”
+
+## Security notes
+
+The docs viewer defends against path traversal:
+
+- Rejects any path containing `..`
+- Requires a `.md` extension
+- Resolves realpaths and ensures the requested file stays under the docs root
+