ruby_ui_admin 0.1.0

data/lib/generators/ruby_ui_admin/install/install_generator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RubyUIAdmin
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      namespace "ruby_ui_admin:install"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the RubyUI Admin initializer and mounts the engine."
+
+      class_option :path, type: :string, default: "admin",
+        desc: "Path to mount the admin at (default: admin)"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/ruby_ui_admin.rb"
+      end
+
+      def mount_engine
+        route %(mount_ruby_ui_admin at: "/#{options[:path]}")
+      end
+
+      def done
+        say "\nRubyUI Admin: initializer created and engine mounted.", :green
+        warn_if_ruby_ui_missing
+        say "\nThe admin renders your app's RubyUI components + assets, so finish wiring them:", :yellow
+        say "  1. Install RubyUI and generate its components (if you haven't). Run phlex:install"
+        say "     FIRST — RubyUI's installer skips it when phlex-rails is present (it is, via this"
+        say "     gem) and then aborts on a missing app/components/base.rb:"
+        say "       bin/rails generate phlex:install"
+        say "       bin/rails generate ruby_ui:install"
+        say "     Then generate the components the admin needs (drives ruby_ui:component for you):"
+        say "       bin/rails generate ruby_ui_admin:components"
+        say "  2. Tailwind: extract the admin's classes into your app and @source the result:"
+        say "       bin/rails ruby_ui_admin:tailwind_source   # writes app/assets/tailwind/ruby_ui_admin_classes.html"
+        say %(       @source "./ruby_ui_admin_classes.html";  # in your Tailwind entry CSS (commit the file))
+        say "  3. Stimulus: copy the admin's controllers into your app with"
+        say "       bin/rails generate ruby_ui_admin:assets"
+        say "     then add the one import line it prints to app/javascript/application.js."
+        say "  4. Set config.head_assets in config/initializers/ruby_ui_admin.rb (see the comment there)."
+        say "\nFull guide: docs/getting-started/installation.md", :green
+        say "Then generate your first resource:"
+        say "  bin/rails generate ruby_ui_admin:resource <Model>\n"
+      end
+
+      private
+
+      # RubyUI's installer aborts (leaving RubyUI::Base ungenerated) if it runs before
+      # phlex:install on an app that already has phlex-rails — which every ruby_ui_admin app does.
+      # Surface that here so a half-installed RubyUI doesn't show up later as a cryptic Zeitwerk error.
+      def warn_if_ruby_ui_missing
+        return if File.exist?(Rails.root.join("app/components/ruby_ui/base.rb"))
+
+        say "\n⚠️  RubyUI doesn't look fully installed (app/components/ruby_ui/base.rb is missing).", :red
+        say "    RubyUI's `ruby_ui:install` aborts on a missing app/components/base.rb when phlex-rails", :red
+        say "    is already present (it is, via this gem). Run `bin/rails generate phlex:install` first,", :red
+        say "    then re-run `bin/rails generate ruby_ui:install`.", :red
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/install/templates/initializer.rb.tt

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+RubyUIAdmin.configure do |config|
+  # The name shown in the sidebar and page titles.
+  config.app_name = "<%= Rails.application.class.module_parent_name %> Admin"
+
+  # Where the engine is mounted (keep in sync with config/routes.rb).
+  config.root_path = "/<%= options[:path] %>"
+
+  # Records per page on index views.
+  config.per_page = 24
+
+  # Resolve the signed-in admin. The block runs in the controller context.
+  config.current_user_method { current_user }
+
+  # Optional gate run before every admin request, e.g.:
+  # config.authenticate_with { redirect_to main_app.login_path unless current_user&.admin? }
+
+  # Authorization adapter: :action_policy (default), :pundit, :cancancan, or a custom adapter
+  # class. Set to nil to disable. See docs/authorization/adapters.md.
+  config.authorization_client = :action_policy
+
+  # When true, rules a policy doesn't define (and missing policies) are denied.
+  config.explicit_authorization = false
+
+  # The admin renders your app's RubyUI components, so it uses your app's CSS + JS. Point the
+  # layout's <head> at them here (a proc evaluated in the Rails view context). Make sure your
+  # Tailwind build covers app/components/ruby_ui/** and the admin views, and that your bundler
+  # registers RubyUI's Stimulus controllers + the admin's rua--* controllers.
+  # config.head_assets = lambda do
+  #   safe_join([
+  #     stylesheet_link_tag("application", "data-turbo-track": "reload"),
+  #     javascript_importmap_tags
+  #   ])
+  # end
+
+  # In-app docs browser at <mount>/docs (renders the gem's docs/*.md). Defaults to :local
+  # (development/test only, open). Set to true to expose it in production too (behind your auth
+  # gate), or false to disable. Needs kramdown + kramdown-parser-gfm in the target environment.
+  # config.docs_enabled = :local
+end

data/lib/generators/ruby_ui_admin/locales/locales_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RubyUIAdmin
+  module Generators
+    # Copies the bundled locale files into the host app so they can be edited/extended.
+    class LocalesGenerator < Rails::Generators::Base
+      namespace "ruby_ui_admin:locales"
+      source_root RubyUIAdmin::Engine.root.to_s
+
+      desc "Copies RubyUI Admin's locale files into config/locales."
+
+      def copy_locales
+        Dir[File.join(self.class.source_root, "config", "locales", "*.yml")].each do |file|
+          relative = File.join("config", "locales", File.basename(file))
+          copy_file relative, relative
+        end
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/policy/policy_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module RubyUIAdmin
+  module Generators
+    class PolicyGenerator < Rails::Generators::NamedBase
+      namespace "ruby_ui_admin:policy"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a RubyUI Admin action_policy policy."
+
+      def create_policy
+        template "policy.rb.tt", File.join("app/ruby_ui_admin/policies", "#{file_path}_policy.rb")
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/policy/templates/policy.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Policies
+    class <%= class_name %>Policy < RubyUIAdmin::BasePolicy
+      def index? = true
+
+      def show? = true
+
+      def create? = true
+
+      def update? = true
+
+      def destroy? = true
+
+      def act_on? = true
+
+      # Scope records on the index view:
+      # relation_scope do |relation|
+      #   relation
+      # end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/resource/resource_generator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module RubyUIAdmin
+  module Generators
+    class ResourceGenerator < Rails::Generators::NamedBase
+      namespace "ruby_ui_admin:resource"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a RubyUI Admin resource (with fields derived from the model)."
+
+      class_option :model_class, type: :string, desc: "Override the inferred model class name"
+
+      def create_resource
+        template "resource.rb.tt", File.join("app/ruby_ui_admin/resources", "#{singular_name}.rb")
+      end
+
+      private
+
+      def resource_class_name
+        class_name.demodulize
+      end
+
+      def model_class_name
+        options[:model_class]
+      end
+
+      def model_klass
+        (model_class_name || class_name).safe_constantize
+      end
+
+      # Builds the body of `def fields`, one `field ...` line per column/association.
+      def fields_block
+        indent = "        "
+        lines = ["#{indent}field :id, as: :id"]
+
+        if (model = model_klass)
+          model.columns.each do |column|
+            next if column.name == "id" || column.name.end_with?("_id")
+
+            type = column_field_type(column)
+            # Keep the index lean: long-form fields (textarea/code) are noisy in a table, so show
+            # them only on the record's show/new/edit pages by default. Tweak or drop `only_on:`.
+            suffix = hidden_from_index?(type) ? ", only_on: %i[show new edit]" : ""
+            lines << "#{indent}field :#{column.name}, as: :#{type}#{suffix}"
+          end
+
+          model.reflect_on_all_associations.each do |association|
+            type = association_field_type(association)
+            lines << "#{indent}field :#{association.name}, as: :#{type}" if type
+          end
+        end
+
+        lines.join("\n")
+      rescue
+        "        field :id, as: :id"
+      end
+
+      def column_field_type(column)
+        return :password if column.name.match?(/password/)
+        return :text if column.name == "email"
+
+        {
+          string: :text, text: :textarea, integer: :number, float: :number,
+          decimal: :number, boolean: :boolean, date: :date, datetime: :date_time,
+          timestamp: :date_time, json: :code, jsonb: :code
+        }.fetch(column.type, :text)
+      end
+
+      # Long-form field types are hidden from the index by default (still on show/new/edit).
+      def hidden_from_index?(type)
+        %i[textarea code].include?(type)
+      end
+
+      def association_field_type(association)
+        {
+          belongs_to: :belongs_to, has_one: :has_one,
+          has_many: :has_many, has_and_belongs_to_many: :has_and_belongs_to_many
+        }[association.macro]
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/resource/templates/resource.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Resources
+    class <%= resource_class_name %> < RubyUIAdmin::BaseResource
+<% if model_class_name -%>
+      self.model_class = <%= model_class_name %>
+
+<% end -%>
+      def fields
+<%= fields_block %>
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/scope/scope_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module RubyUIAdmin
+  module Generators
+    class ScopeGenerator < Rails::Generators::NamedBase
+      namespace "ruby_ui_admin:scope"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a RubyUI Admin named index scope."
+
+      def create_scope
+        template "scope.rb.tt", File.join("app/ruby_ui_admin/scopes", "#{file_path}.rb")
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/scope/templates/scope.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Scopes
+    class <%= class_name %> < RubyUIAdmin::Scopes::BaseScope
+      self.name = "<%= human_name %>"
+      self.scope = -> { query.all }
+      # self.default = true
+    end
+  end
+end

data/lib/ruby_ui_admin/authorization/action_policy_adapter.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "action_policy"
+
+module RubyUIAdmin
+  module Authorization
+    # action_policy-backed adapter (the default). Bridges the admin's authorization onto
+    # action_policy: `allowed_to?`, `authorized_scope`, `policy_for`. Rules the policy doesn't
+    # define fall back to its default rule (`manage?`), which `RubyUIAdmin::BasePolicy` ties to
+    # `explicit_authorization`; a missing policy is decided by `explicit_authorization` too.
+    class ActionPolicyAdapter < Adapter
+      include ActionPolicy::Behaviour
+
+      # Declares the authorization context required by policies (resolved via the readers on Adapter).
+      authorize :user
+      authorize :true_user
+
+      def authorize_action(rule, record: nil, raise_exception: true)
+        return true unless RubyUIAdmin.configuration.authorization_enabled?
+
+        target = record.nil? ? @record : record
+        normalized = normalize_rule(rule)
+
+        begin
+          result = allowed_to?(normalized, target, with: policy_class)
+        rescue ActionPolicy::NotFound
+          return handle_missing_policy(raise_exception)
+        end
+
+        if !result && raise_exception
+          raise NotAuthorizedError, "Not authorized to #{normalized} on #{target.inspect}"
+        end
+
+        result
+      end
+
+      def apply_policy(scope)
+        return scope unless RubyUIAdmin.configuration.authorization_enabled?
+
+        authorized_scope(scope, with: policy_class)
+      rescue ActionPolicy::UnknownScopeType,
+             ActionPolicy::UnknownNamedScope,
+             ActionPolicy::UnrecognizedScopeTarget,
+             ActionPolicy::NotFound
+        scope
+      end
+
+      def has_rule?(rule, record: nil)
+        target = record.nil? ? @record : record
+        policy = policy_for(record: target, with: policy_class, allow_nil: true)
+        return false if policy.nil?
+
+        policy.respond_to?(normalize_rule(rule))
+      rescue ActionPolicy::NotFound
+        false
+      end
+
+      # Whether the policy CLASS explicitly defines this rule as a public method (i.e. not satisfied
+      # only by the `manage?` default). Used for field-level authorization.
+      def defines_rule?(rule)
+        return false if policy_class.nil?
+
+        policy_class.public_method_defined?(normalize_rule(rule))
+      rescue
+        false
+      end
+    end
+  end
+end

data/lib/ruby_ui_admin/authorization/adapter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Authorization
+    # Interface every authorization adapter implements. `Services::AuthorizationService` resolves the
+    # configured adapter (`config.authorization_client`) and delegates to it, so call sites stay
+    # backend-agnostic. An adapter bridges the admin's rule vocabulary (`index?`/`show?`/`update?`/
+    # `destroy?`/`act_on?`/`view_<field>?`, with the `manage?` + `explicit_authorization` fallback)
+    # onto a backend (action_policy, Pundit, CanCanCan, …).
+    #
+    # Subclasses must implement: #authorize_action, #apply_policy, #has_rule?, #defines_rule?.
+    # The shared context (#user, #true_user, #record, #policy_class), #allowed? and #normalize_rule
+    # live here.
+    class Adapter
+      attr_reader :user, :record, :policy_class
+
+      def initialize(user, record = nil, policy_class: nil, true_user: nil)
+        @user = user
+        @record = record
+        @policy_class = policy_class
+        @true_user = true_user
+      end
+
+      # The real (impersonating) user. Defaults to `Current.true_user`, falling back to `user`.
+      def true_user
+        @true_user || RubyUIAdmin::Current.true_user || @user
+      end
+
+      def set_record(record)
+        @record = record
+        self
+      end
+
+      # Authorizes a single rule. Returns a boolean; raises `NotAuthorizedError` when denied and
+      # `raise_exception` is true.
+      def authorize_action(_rule, record: nil, raise_exception: true)
+        raise NotImplementedError, "#{self.class} must implement #authorize_action"
+      end
+
+      def allowed?(rule, record: nil)
+        authorize_action(rule, record: record, raise_exception: false)
+      end
+
+      # Applies the policy's record scope to a relation; returns it unchanged when none applies.
+      def apply_policy(_scope)
+        raise NotImplementedError, "#{self.class} must implement #apply_policy"
+      end
+
+      # Whether the resolved policy/instance responds to the rule (for the given record).
+      def has_rule?(_rule, record: nil)
+        raise NotImplementedError, "#{self.class} must implement #has_rule?"
+      end
+
+      # Whether the policy CLASS explicitly defines the rule (field-level auth: an undefined rule
+      # means "no opinion" → the field stays visible).
+      def defines_rule?(_rule)
+        raise NotImplementedError, "#{self.class} must implement #defines_rule?"
+      end
+
+      private
+
+      def normalize_rule(rule)
+        string = rule.to_s
+        string.end_with?("?") ? string.to_sym : :"#{string}?"
+      end
+
+      # Shared "no policy / undefined rule" fallback: `explicit_authorization` decides — denied when
+      # true (raising if requested), allowed when false. Used by every adapter so the
+      # missing-policy/undefined-rule semantics stay identical across backends.
+      def handle_missing_policy(raise_exception)
+        if RubyUIAdmin.configuration.explicit_authorization
+          raise NotAuthorizedError, "No policy found" if raise_exception
+          false
+        else
+          true
+        end
+      end
+    end
+  end
+end

data/lib/ruby_ui_admin/authorization/can_can_can_adapter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+begin
+  require "cancancan"
+rescue LoadError
+  raise LoadError, "config.authorization_client = :cancancan requires the `cancancan` gem. Add `gem \"cancancan\"` to your Gemfile."
+end
+
+module RubyUIAdmin
+  module Authorization
+    # CanCanCan-backed adapter. Maps the admin's CRUD rules onto `Ability#can?(action, subject)` and
+    # the index scope onto `relation.accessible_by(ability)`.
+    #
+    # ⚠️ PARTIAL by design (CanCanCan is action/subject-based, not policy-class-based):
+    #   * No `policy_class` — a single global Ability (`config.cancancan_ability_class`, default
+    #     `Ability`) decides everything; `authorization_policy` per resource is ignored.
+    #   * **No field-level authorization** — CanCanCan has no per-rule "is it defined?" concept, so
+    #     `defines_rule?`/`has_rule?` return false (every field stays visible). Use action_policy or
+    #     Pundit if you need field-level rules.
+    #   * **`explicit_authorization` has no effect** — CanCanCan denies whatever the Ability doesn't
+    #     grant; there's no `manage?`/undefined-rule fallback. Grant access in your Ability.
+    #   * `true_user` (impersonation) is not passed to the Ability.
+    #   * The index scope follows the Ability's rules for the action (e.g. `can :read, Post, ...`);
+    #     with no matching rule it resolves to an empty relation, the CanCanCan way.
+    class CanCanCanAdapter < Adapter
+      def authorize_action(rule, record: nil, raise_exception: true)
+        return true unless RubyUIAdmin.configuration.authorization_enabled?
+
+        target = record.nil? ? @record : record
+        action = cancan_action(rule)
+        result = ability.can?(action, target)
+
+        if !result && raise_exception
+          raise NotAuthorizedError, "Not authorized to #{action} on #{target.inspect}"
+        end
+
+        result
+      end
+
+      def apply_policy(scope)
+        return scope unless RubyUIAdmin.configuration.authorization_enabled?
+
+        scope.accessible_by(ability)
+      rescue CanCan::Error
+        scope
+      end
+
+      # Field-level authorization is not supported by CanCanCan (no per-rule definition concept).
+      def has_rule?(_rule, record: nil) = false
+
+      def defines_rule?(_rule) = false
+
+      private
+
+      def ability
+        @ability ||= ability_class.new(user)
+      end
+
+      def ability_class
+        configured = RubyUIAdmin.configuration.cancancan_ability_class || "Ability"
+        configured.is_a?(Class) ? configured : Object.const_get(configured.to_s)
+      end
+
+      # Admin rule (`show?`, `update?`, …) → CanCanCan action (`:show`, `:update`, …).
+      def cancan_action(rule)
+        rule.to_s.delete_suffix("?").to_sym
+      end
+    end
+  end
+end

data/lib/ruby_ui_admin/authorization/pundit_adapter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+begin
+  require "pundit"
+rescue LoadError
+  raise LoadError, "config.authorization_client = :pundit requires the `pundit` gem. Add `gem \"pundit\"` to your Gemfile."
+end
+
+module RubyUIAdmin
+  module Authorization
+    # Pundit-backed adapter. Maps the admin's rules onto a Pundit policy (`policy.show?`), record
+    # scopes onto the policy's `Scope`, and uses `respond_to?`/`public_method_defined?` for the
+    # field-level "is this rule defined?" check. A rule the policy doesn't define (or a missing
+    # policy) falls back to `explicit_authorization`, keeping the same semantics as action_policy.
+    #
+    # The resource's `authorization_policy` is used as the policy class when given; otherwise Pundit
+    # infers it (`Pundit::PolicyFinder`). Pundit policies receive only `user` — `true_user`
+    # (impersonation) is not passed to them.
+    class PunditAdapter < Adapter
+      def authorize_action(rule, record: nil, raise_exception: true)
+        return true unless RubyUIAdmin.configuration.authorization_enabled?
+
+        target = record.nil? ? @record : record
+        policy = policy_instance(target)
+        normalized = normalize_rule(rule)
+
+        return handle_missing_policy(raise_exception) if policy.nil? || !policy.respond_to?(normalized)
+
+        result = !!policy.public_send(normalized)
+        if !result && raise_exception
+          raise NotAuthorizedError, "Not authorized to #{normalized} on #{target.inspect}"
+        end
+
+        result
+      end
+
+      def apply_policy(scope)
+        return scope unless RubyUIAdmin.configuration.authorization_enabled?
+
+        scope_class = scope_class_for(scope)
+        return scope unless scope_class
+
+        scope_class.new(user, scope).resolve
+      rescue Pundit::NotDefinedError
+        scope
+      end
+
+      def has_rule?(rule, record: nil)
+        target = record.nil? ? @record : record
+        policy = policy_instance(target)
+        return false if policy.nil?
+
+        policy.respond_to?(normalize_rule(rule))
+      end
+
+      def defines_rule?(rule)
+        return false if policy_class.nil?
+
+        policy_class.public_method_defined?(normalize_rule(rule))
+      rescue
+        false
+      end
+
+      private
+
+      # Explicit `authorization_policy` wins; otherwise Pundit infers the policy class from the
+      # target (instance or class). Returns nil when none can be resolved.
+      def policy_instance(target)
+        klass = policy_class || Pundit::PolicyFinder.new(target).policy
+        return nil unless klass
+
+        klass.new(user, target)
+      rescue Pundit::NotDefinedError
+        nil
+      end
+
+      def scope_class_for(scope)
+        if policy_class&.const_defined?(:Scope)
+          policy_class::Scope
+        else
+          Pundit::PolicyFinder.new(scope).scope
+        end
+      end
+    end
+  end
+end

data/lib/ruby_ui_admin/authorization.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  # Resolves the authorization adapter from `config.authorization_client`. The value may be a
+  # symbol (looked up in REGISTRY), a Class (a custom adapter), or nil (disabled — still resolves
+  # to the default adapter, which short-circuits to permissive via `authorization_enabled?`).
+  module Authorization
+    # Symbol → adapter class, wrapped in a lambda so optional backends (Pundit, CanCanCan) are only
+    # referenced when actually selected.
+    REGISTRY = {
+      action_policy: -> { ActionPolicyAdapter },
+      pundit: lambda {
+        require "ruby_ui_admin/authorization/pundit_adapter"
+        PunditAdapter
+      },
+      cancancan: lambda {
+        require "ruby_ui_admin/authorization/can_can_can_adapter"
+        CanCanCanAdapter
+      }
+    }.freeze
+
+    def self.adapter_class(client = RubyUIAdmin.configuration.authorization_client)
+      return client if client.is_a?(Class)
+
+      key = (client || :action_policy).to_sym
+      resolver = REGISTRY[key]
+      unless resolver
+        known = REGISTRY.keys.join(", ")
+        raise ArgumentError,
+          "Unknown authorization_client #{client.inspect}. Use one of: #{known}, an adapter class, or nil."
+      end
+
+      resolver.call
+    end
+
+    def self.build(...)
+      adapter_class.new(...)
+    end
+  end
+end