super_admin 0.2.0

data/lib/super_admin/dashboard_creator.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "active_support/inflector"
+
+module SuperAdmin
+  # Utility object responsible for creating dashboard skeleton files.
+  class DashboardCreator
+    def self.call(model_name: nil, stdout: $stdout)
+      new(model_name:, stdout:).call
+    end
+
+    def initialize(model_name:, stdout:)
+      @model_name = model_name
+      @stdout = stdout
+    end
+
+    def call
+      models = determine_models
+
+      if models.empty?
+        stdout.puts "No models found to generate dashboards for."
+        return { generated: [], skipped: [] }
+      end
+
+      generated = []
+      skipped = []
+
+      models.each do |model|
+        unless constantizable_model?(model)
+          stdout.puts "Skipping #{model.inspect}: model is not constantizable."
+          next
+        end
+
+        result = generate_dashboard(model)
+        next unless result
+
+        case result[:status]
+        when :generated
+          generated << result[:path]
+        when :skipped
+          skipped << result[:path]
+        end
+      end
+
+      print_summary(generated, skipped)
+
+      { generated:, skipped: }
+    end
+
+    private
+
+    attr_reader :model_name, :stdout
+
+    def determine_models
+      models = if model_name && !model_name.to_s.strip.empty?
+        [ resolve_model(model_name) ]
+      else
+        SuperAdmin::ModelInspector.discoverable_models
+      end
+
+      Array(models).compact.each_with_object([]) do |model, list|
+        if engine_owned_model?(model)
+          stdout.puts "Skipping #{model.name}: managed internally by SuperAdmin."
+          next
+        end
+
+        list << model
+      end
+    end
+
+    def constantizable_model?(model)
+      return false unless model.respond_to?(:name)
+      name = model.name
+      return false if name.nil? || name.empty?
+
+      constant = name.safe_constantize
+      constant == model
+    end
+
+    def resolve_model(name)
+      return name if name.is_a?(Class) && name < ActiveRecord::Base
+
+      constant_name = normalize_model_name(name)
+      klass = constant_name.constantize
+      if engine_owned_model?(klass)
+        raise ArgumentError, "#{constant_name} is managed internally by SuperAdmin and should not receive a dashboard."
+      end
+      return klass if klass < ActiveRecord::Base
+
+      raise ArgumentError, "#{constant_name} is not an ActiveRecord model"
+    rescue NameError
+      raise ArgumentError, "Unable to find model for '#{name}'"
+    end
+
+    def normalize_model_name(name)
+      raw = name.to_s.tr("/", "::").split("::").reject(&:empty?)
+      segments = raw.map { |segment| segment.underscore.singularize.camelize }
+      segments.join("::")
+    end
+
+    def generate_dashboard(model_class)
+      if dashboard_exists?(model_class)
+        stdout.puts "Skipping #{model_class.name}: dashboard already exists."
+        return { status: :skipped, path: relative_dashboard_path(model_class).to_s }
+      end
+
+      path = absolute_dashboard_path(model_class)
+      FileUtils.mkdir_p(path.dirname)
+      File.write(path, dashboard_template(model_class))
+      stdout.puts "Created #{relative_dashboard_path(model_class)}"
+
+      { status: :generated, path: relative_dashboard_path(model_class).to_s }
+    end
+
+    def dashboard_exists?(model_class)
+      registry = SuperAdmin::DashboardRegistry.instance
+      return true if registry.dashboard_for(model_class)
+
+      absolute_dashboard_path(model_class).exist?
+    end
+
+    def absolute_dashboard_path(model_class)
+      Rails.root.join(relative_dashboard_path(model_class))
+    end
+
+    def relative_dashboard_path(model_class)
+      Pathname.new(File.join("app", "dashboards", "super_admin", *namespace_segments(model_class), "#{model_basename(model_class)}_dashboard.rb"))
+    end
+
+    def namespace_segments(model_class)
+      relative_namespace_constants(model_class).map { |segment| segment.underscore }
+    end
+
+    def namespace_constants(model_class)
+      namespace = model_class.name.deconstantize
+      return [] if namespace.empty?
+
+      namespace.split("::")
+    end
+
+    def relative_namespace_constants(model_class)
+      segments = namespace_constants(model_class)
+      segments.shift if segments.first == root_namespace
+      segments
+    end
+
+    def model_basename(model_class)
+      model_class.name.demodulize.underscore
+    end
+
+    def dashboard_template(model_class)
+      collection_attrs = default_collection_attributes(model_class)
+      show_attrs = default_show_attributes(model_class)
+      form_attrs = default_form_attributes(model_class)
+
+      lines = []
+      lines << "# frozen_string_literal: true"
+      lines << ""
+
+      indent = 0
+      append(lines, indent, "module SuperAdmin")
+      indent += 1
+
+      relative_namespace_constants(model_class).each do |namespace|
+        append(lines, indent, "module #{namespace}")
+        indent += 1
+      end
+
+      append(lines, indent, "class #{model_class.name.demodulize}Dashboard < SuperAdmin::BaseDashboard")
+      indent += 1
+      append(lines, indent, "resource #{model_class.name}")
+      append_attribute_declaration(lines, indent, "collection_attributes", collection_attrs)
+      append_attribute_declaration(lines, indent, "show_attributes", show_attrs)
+      append_attribute_declaration(lines, indent, "form_attributes", form_attrs)
+      indent -= 1
+      append(lines, indent, "end")
+
+      relative_namespace_constants(model_class).reverse_each do |_namespace|
+        indent -= 1
+        append(lines, indent, "end")
+      end
+
+      indent -= 1
+      append(lines, indent, "end")
+
+      lines.join("\n") + "\n"
+    end
+
+    def append(lines, indent, text)
+      lines << ("  " * indent + text)
+    end
+
+    def append_attribute_declaration(lines, indent, macro, attributes)
+      return if attributes.empty?
+
+      append(lines, indent, "#{macro} #{format_attribute_list(attributes, indent)}")
+    end
+
+    def default_collection_attributes(model_class)
+      SuperAdmin::ResourceConfiguration
+        .displayable_attributes(model_class)
+        .map { |attr| normalize_attribute_name(attr) }
+    end
+
+    def default_show_attributes(model_class)
+      SuperAdmin::ResourceConfiguration
+        .displayable_attributes(model_class)
+        .map { |attr| normalize_attribute_name(attr) }
+    end
+
+    def default_form_attributes(model_class)
+      SuperAdmin::ResourceConfiguration
+        .editable_attributes(model_class)
+        .map { |attr| normalize_attribute_name(attr) }
+    end
+
+    def normalize_attribute_name(attribute)
+      attribute.is_a?(Symbol) ? attribute : attribute.to_s.to_sym
+    end
+
+    def format_attribute_list(attributes, indent)
+      tokens = attributes.map { |attr| ":#{attr}" }
+      single_line = tokens.join(", ")
+      return single_line if single_line.length <= 80
+
+      continuation_indent = "\n" + ("  " * indent) + "  "
+      tokens.join(",#{continuation_indent}")
+    end
+
+    def root_namespace
+      "SuperAdmin"
+    end
+
+    def engine_owned_model?(model)
+      model.name.start_with?("#{root_namespace}::")
+    end
+
+    def print_summary(generated, skipped)
+      stdout.puts
+      stdout.puts "Dashboards generated: #{generated.count}"
+      stdout.puts "  - #{generated.join("\n  - ")}" if generated.any?
+      stdout.puts "Dashboards skipped: #{skipped.count}"
+      stdout.puts "  - #{skipped.join("\n  - ")}" if skipped.any?
+
+      if generated.empty?
+        if skipped.any?
+          stdout.puts "No dashboards created; all models already have dashboards."
+        else
+          stdout.puts "No dashboards created."
+        end
+      end
+    end
+  end
+end

data/lib/super_admin/engine.rb

@@ -0,0 +1,53 @@
+module SuperAdmin
+  # :nocov:
+  class Engine < ::Rails::Engine
+    isolate_namespace SuperAdmin
+
+    initializer "super_admin.assets" do |app|
+      # Add engine's JavaScript to asset paths so they can be served
+      app.config.assets.paths << root.join("app/javascript") if app.config.respond_to?(:assets)
+      # Add engine's stylesheets to asset paths for propshaft/sprockets
+      app.config.assets.paths << root.join("app/assets/stylesheets") if app.config.respond_to?(:assets)
+    end
+
+    initializer "super_admin.importmap", before: "importmap" do |app|
+      # Register SuperAdmin importmap if importmap-rails is available
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << root.join("app/javascript")
+      end
+    end
+
+    initializer "super_admin.route_helpers" do
+      require_relative "../../app/helpers/super_admin/route_helper"
+
+      ActiveSupport.on_load(:action_view) do
+        include ::SuperAdmin::RouteHelper
+      end
+
+      ActiveSupport.on_load(:action_controller) do
+        helper ::SuperAdmin::RouteHelper
+      end
+
+      config.to_prepare do
+        if defined?(ViewComponent::Base) && !ViewComponent::Base.included_modules.include?(::SuperAdmin::RouteHelper)
+          ViewComponent::Base.include(::SuperAdmin::RouteHelper)
+        end
+
+        if defined?(ActionView::Component::Base) && !ActionView::Component::Base.included_modules.include?(::SuperAdmin::RouteHelper)
+          ActionView::Component::Base.include(::SuperAdmin::RouteHelper)
+        end
+      end
+    end
+
+    initializer "super_admin.rack_attack", after: :load_config_initializers do
+      # Load Rack::Attack configuration for SuperAdmin endpoints
+      if defined?(Rack::Attack)
+        require "rack-attack"
+        config_file = root.join("config/initializers/rack_attack.rb")
+        load(config_file) if config_file.exist?
+      end
+    end
+  end
+  # :nocov:
+end

data/lib/super_admin/install_task.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module SuperAdmin
+  # Handles bootstrapping host applications with required SuperAdmin assets.
+  class InstallTask
+    INITIALIZER_PATH = "config/initializers/super_admin.rb"
+
+    def self.call(stdout: $stdout)
+      new(stdout:).call
+    end
+
+    def initialize(stdout: $stdout)
+      @stdout = stdout
+      @engine_root = Pathname.new(SuperAdmin::Engine.root)
+      @app_root = Pathname.new(Rails.root)
+    end
+
+    def call
+      copy_initializer
+      copy_migrations
+      stdout.puts "SuperAdmin installation complete."
+    end
+
+    # Public method for copying migrations (used by rake task)
+    def copy_migrations
+      migration_files.each do |source_path|
+        copy_migration(source_path)
+      end
+    end
+
+    private
+
+    attr_reader :stdout, :engine_root, :app_root
+
+    def copy_initializer
+      target = app_root.join(INITIALIZER_PATH)
+      if target.exist?
+        stdout.puts "Initializer already exists at #{relative_to_app(target)} (skipping)."
+        return
+      end
+
+      source = engine_root.join(INITIALIZER_PATH)
+      FileUtils.mkdir_p(target.dirname)
+      FileUtils.cp(source, target)
+      stdout.puts "Initializer copied to #{relative_to_app(target)}."
+    end
+
+    def migration_files
+      # Dir[] does not guarantee order, so we must sort to preserve migration sequence.
+      # We filter to only include files starting with a timestamp (e.g., 20240101000001_)
+      # to avoid copying non-migration files like super_admin.rb
+      Dir[engine_root.join("lib", "generators", "super_admin", "templates", "*.rb")]
+        .select { |f| File.basename(f) =~ /^\d+_/ }
+        .sort
+    end
+
+    def copy_migration(source_path)
+      basename = File.basename(source_path).sub(/^\d+_/, "")
+
+      if migration_exists?(basename)
+        stdout.puts "Migration #{basename} already present (skipping)."
+        return
+      end
+
+      timestamp = next_migration_timestamp
+      target = app_root.join("db", "migrate", "#{timestamp}_#{basename}")
+      FileUtils.mkdir_p(target.dirname)
+      FileUtils.cp(source_path, target)
+      stdout.puts "Migration created at #{relative_to_app(target)}."
+    end
+
+    def migration_exists?(basename)
+      Dir[app_root.join("db", "migrate", "*_#{basename}").to_s].any?
+    end
+
+    def next_migration_timestamp
+      now = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+      @migration_counter ||= begin
+        existing = Dir[app_root.join("db", "migrate", "*.rb").to_s]
+        existing.map { |path| File.basename(path).split("_", 2).first.to_i }.max || 0
+      end
+
+      @migration_counter = [ @migration_counter + 1, now ].max
+      format("%014d", @migration_counter)
+    end
+
+    def relative_to_app(path)
+      path.relative_path_from(app_root)
+    rescue ArgumentError
+      path
+    end
+  end
+end

data/lib/super_admin/version.rb

@@ -0,0 +1,3 @@
+module SuperAdmin
+  VERSION = "0.2.0"
+end

data/lib/super_admin.rb

@@ -0,0 +1,7 @@
+require "super_admin/version"
+require "super_admin/engine"
+require "pagy"
+
+module SuperAdmin
+  # Your code goes here...
+end

data/lib/tasks/super_admin_tasks.rake

@@ -0,0 +1,38 @@
+require "super_admin/dashboard_creator"
+require "super_admin/install_task"
+
+namespace :super_admin do
+  desc "Install SuperAdmin (use 'rails generate super_admin:install' instead)"
+  task install: :environment do
+    puts "⚠️  This rake task is deprecated. Please use the generator instead:"
+    puts "   rails generate super_admin:install"
+    puts "\nRunning generator..."
+    Rails::Generators.invoke("super_admin:install")
+  rescue StandardError => e
+    abort "SuperAdmin install failed: #{e.message}"
+  end
+
+  namespace :install do
+    desc "Copy migrations from SuperAdmin to application"
+    task :migrations do
+      SuperAdmin::InstallTask.new.send(:copy_migrations)
+    end
+  end
+
+  namespace :dashboards do
+    desc "Generate SuperAdmin dashboards (use 'rails generate super_admin:dashboard' instead)"
+      task :generate, [ :model_name ] => :environment do |_task, args|
+        model_name = args[:model_name] || ENV["MODEL"]
+        puts "⚠️  This rake task is deprecated. Please use the generator instead:"
+        if model_name
+          puts "   rails generate super_admin:dashboard #{model_name}"
+        else
+          puts "   rails generate super_admin:dashboard"
+        end
+        puts "\nRunning generator..."
+        Rails::Generators.invoke("super_admin:dashboard", [ model_name ].compact)
+    rescue ArgumentError => e
+      abort e.message
+    end
+  end
+end

metadata

@@ -0,0 +1,239 @@
+--- !ruby/object:Gem::Specification
+name: super_admin
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Thibaut Baissac
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: pagy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: stimulus-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rack-attack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: SuperAdmin is a mountable Rails engine that provides a full-featured
+  administration interface inspired by Administrate and ActiveAdmin, built for modern
+  Rails 7+ applications.
+email:
+- tbaissac@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- app/assets/stylesheets/super_admin/application.css
+- app/assets/stylesheets/super_admin/tailwind.css
+- app/assets/stylesheets/super_admin/tailwind.source.css
+- app/controllers/super_admin/application_controller.rb
+- app/controllers/super_admin/associations_controller.rb
+- app/controllers/super_admin/audit_logs_controller.rb
+- app/controllers/super_admin/base_controller.rb
+- app/controllers/super_admin/dashboard_controller.rb
+- app/controllers/super_admin/exports_controller.rb
+- app/controllers/super_admin/resources_controller.rb
+- app/dashboards/super_admin/base_dashboard.rb
+- app/errors/super_admin/configuration_error.rb
+- app/helpers/super_admin/application_helper.rb
+- app/helpers/super_admin/exports_helper.rb
+- app/helpers/super_admin/resources_helper.rb
+- app/helpers/super_admin/route_helper.rb
+- app/javascript/super_admin/application.js
+- app/jobs/super_admin/application_job.rb
+- app/jobs/super_admin/generate_super_admin_csv_export_job.rb
+- app/mailers/super_admin/application_mailer.rb
+- app/models/super_admin/application_record.rb
+- app/models/super_admin/audit_log.rb
+- app/models/super_admin/csv_export.rb
+- app/services/super_admin/auditing.rb
+- app/services/super_admin/authorization.rb
+- app/services/super_admin/authorization_adapters/base_adapter.rb
+- app/services/super_admin/authorization_adapters/default_adapter.rb
+- app/services/super_admin/authorization_adapters/proc_adapter.rb
+- app/services/super_admin/authorization_adapters/pundit_adapter.rb
+- app/services/super_admin/csv_export_creator.rb
+- app/services/super_admin/dashboard_registry.rb
+- app/services/super_admin/dashboard_resolver.rb
+- app/services/super_admin/filter_builder.rb
+- app/services/super_admin/form_builder.rb
+- app/services/super_admin/form_fields/array_field.rb
+- app/services/super_admin/form_fields/association_field.rb
+- app/services/super_admin/form_fields/base_field.rb
+- app/services/super_admin/form_fields/boolean_field.rb
+- app/services/super_admin/form_fields/date_field.rb
+- app/services/super_admin/form_fields/date_time_field.rb
+- app/services/super_admin/form_fields/enum_field.rb
+- app/services/super_admin/form_fields/factory.rb
+- app/services/super_admin/form_fields/nested_field.rb
+- app/services/super_admin/form_fields/number_field.rb
+- app/services/super_admin/form_fields/text_area_field.rb
+- app/services/super_admin/model_inspector.rb
+- app/services/super_admin/queries/base_query.rb
+- app/services/super_admin/queries/filter_query.rb
+- app/services/super_admin/queries/resource_scope_query.rb
+- app/services/super_admin/queries/search_query.rb
+- app/services/super_admin/queries/sort_query.rb
+- app/services/super_admin/resource_configuration.rb
+- app/services/super_admin/resource_exporter.rb
+- app/services/super_admin/resource_query.rb
+- app/services/super_admin/resources/association_inspector.rb
+- app/services/super_admin/resources/collection_presenter.rb
+- app/services/super_admin/resources/context.rb
+- app/services/super_admin/resources/filter_params.rb
+- app/services/super_admin/resources/permitted_attributes.rb
+- app/services/super_admin/resources/value_normalizer.rb
+- app/services/super_admin/sensitive_attributes.rb
+- app/views/layouts/super_admin.html.erb
+- app/views/super_admin/audit_logs/index.html.erb
+- app/views/super_admin/dashboard/index.html.erb
+- app/views/super_admin/exports/index.html.erb
+- app/views/super_admin/exports/show.html.erb
+- app/views/super_admin/resources/_form.html.erb
+- app/views/super_admin/resources/destroy.turbo_stream.erb
+- app/views/super_admin/resources/edit.html.erb
+- app/views/super_admin/resources/index.html.erb
+- app/views/super_admin/resources/new.html.erb
+- app/views/super_admin/resources/show.html.erb
+- app/views/super_admin/shared/_breadcrumbs.html.erb
+- app/views/super_admin/shared/_custom_styles.html.erb
+- app/views/super_admin/shared/_flash.html.erb
+- app/views/super_admin/shared/_form_field.html.erb
+- app/views/super_admin/shared/_navigation.html.erb
+- app/views/super_admin/shared/_nested_fields.html.erb
+- app/views/super_admin/shared/_nested_record_fields.html.erb
+- config/importmap.rb
+- config/initializers/rack_attack.rb
+- config/initializers/super_admin.rb
+- config/locales/super_admin.en.yml
+- config/locales/super_admin.fr.yml
+- config/routes.rb
+- lib/generators/super_admin/dashboard_generator.rb
+- lib/generators/super_admin/install_generator.rb
+- lib/generators/super_admin/templates/20240101000001_create_super_admin_audit_logs.rb
+- lib/generators/super_admin/templates/20240101000002_create_super_admin_csv_exports.rb
+- lib/generators/super_admin/templates/super_admin.rb
+- lib/super_admin.rb
+- lib/super_admin/dashboard_creator.rb
+- lib/super_admin/engine.rb
+- lib/super_admin/install_task.rb
+- lib/super_admin/version.rb
+- lib/tasks/super_admin_tasks.rake
+homepage: https://github.com/ThibautBaissac/super_admin
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ThibautBaissac/super_admin
+  source_code_uri: https://github.com/ThibautBaissac/super_admin
+  changelog_uri: https://github.com/ThibautBaissac/super_admin/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ThibautBaissac/super_admin/issues
+  documentation_uri: https://github.com/ThibautBaissac/super_admin#readme
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A modern, flexible administration engine for Rails applications
+test_files: []