argus-trail 0.1.0

data/lib/argus/trail/pagination.rb

@@ -0,0 +1,41 @@
+module Argus
+  module Trail
+    module Pagination
+      # Minimal stand-in for a Kaminari page, used only when the host app
+      # hasn't bundled Kaminari. Implements just enough of Kaminari's relation
+      # interface for the engine's views (current_page, total_pages, total_count, each).
+      class SimplePage
+        include Enumerable
+
+        attr_reader :current_page, :per_page, :total_count
+
+        def initialize(relation, page:, per:)
+          @current_page = [ page.to_i, 1 ].max
+          @per_page     = per
+          @total_count  = relation.count
+          @records      = relation.offset((@current_page - 1) * per).limit(per).to_a
+        end
+
+        def each(&block) = @records.each(&block)
+        def any? = @records.any?
+        def empty? = @records.empty?
+        def size = @records.size
+
+        def total_pages
+          return 0 if per_page.zero?
+          (total_count.to_f / per_page).ceil
+        end
+      end
+
+      module_function
+
+      def paginate(relation, page:, per:)
+        if defined?(Kaminari)
+          relation.page(page).per(per)
+        else
+          SimplePage.new(relation, page: page, per: per)
+        end
+      end
+    end
+  end
+end

data/lib/argus/trail/version.rb

@@ -0,0 +1,5 @@
+module Argus
+  module Trail
+    VERSION = "0.1.0"
+  end
+end

data/lib/argus/trail.rb

@@ -0,0 +1,30 @@
+require "argus/trail/version"
+require "argus/trail/configuration"
+require "argus/trail/current"
+require "argus/trail/actor"
+require "argus/trail/pagination"
+require "argus/trail/engine"
+
+module Argus
+  module Trail
+    EVENT_TYPES = %w[role_assigned role_revoked permission_granted permission_revoked].freeze
+
+    class << self
+      def configure
+        yield config
+      end
+
+      def config
+        @config ||= Configuration.new
+      end
+
+      def current_actor=(actor)
+        Current.actor = actor
+      end
+
+      def current_actor
+        Current.actor
+      end
+    end
+  end
+end

data/lib/generators/argus/trail/config/config_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require_relative "../install/install_generator"
+
+module Argus
+  module Trail
+    module Generators
+      # Re-templates just the initializer — for hosts who already ran
+      # `install` (migrations + route already in place) and want the
+      # config/initializers/argus_trail.rb file regenerated.
+      class ConfigGenerator < Rails::Generators::Base
+        source_root Argus::Trail::Generators::InstallGenerator.source_root
+
+        desc "Writes (or rewrites) config/initializers/argus_trail.rb"
+
+        def create_initializer
+          template "initializer.rb", "config/initializers/argus_trail.rb"
+        end
+      end
+    end
+  end
+end

data/lib/generators/argus/trail/install/install_generator.rb

@@ -0,0 +1,46 @@
+require "rails/generators"
+require "rails/generators/migration"
+require "active_record"
+
+module Argus
+  module Trail
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        include Rails::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        def self.next_migration_number(dirname)
+          ActiveRecord::Migration.next_migration_number(current_migration_number(dirname) + 1)
+        end
+
+        def create_initializer
+          template "initializer.rb", "config/initializers/argus_trail.rb"
+        end
+
+        def create_core_migration
+          migration_template "create_argus_trail_tables.rb.erb",
+                              "db/migrate/create_argus_trail_tables.rb"
+        end
+
+        def mount_engine
+          routes_file = File.expand_path("config/routes.rb", destination_root)
+          return unless File.exist?(routes_file)
+          return if File.read(routes_file).include?("Argus::Trail::Engine")
+
+          route 'mount Argus::Trail::Engine => "/admin/access"'
+        end
+
+        def show_readme
+          readme "POST_INSTALL" if behavior == :invoke
+        end
+
+        private
+
+        def migration_version
+          "[#{ActiveRecord::Migration.current_version}]"
+        end
+      end
+    end
+  end
+end

data/lib/generators/argus/trail/install/templates/POST_INSTALL

@@ -0,0 +1,43 @@
+========================================================================
+Argus::Trail installed
+========================================================================
+
+Next steps:
+
+1. Run the migrations:
+     bin/rails db:migrate
+
+2. Add one line to the user/account model you configured as actor_class_name.
+   No migration needed on that model — roles live in the engine's own
+   polymorphic join table, so an actor can hold any number of roles:
+
+     class User < ApplicationRecord
+       include Argus::Trail::Actor
+     end
+
+3. Tell the engine who's making each change, once, in your ApplicationController:
+
+     class ApplicationController < ActionController::Base
+       before_action { Argus::Trail.current_actor = current_user }
+     end
+
+4. If you have Pundit in your Gemfile, define policies for the engine's
+   records so its admin screens know who's allowed in, e.g.:
+
+     class Argus::Trail::RolePolicy < ApplicationPolicy
+       def index? = user.admin?
+       def show?  = user.admin?
+       # ...
+     end
+
+   Do the same for Argus::Trail::PermissionPolicy and
+   Argus::Trail::AuditEntryPolicy. No Pundit? Set config.authorize_with
+   in config/initializers/argus_trail.rb instead.
+
+5. Visit the mounted engine (default /admin/access, see config/routes.rb)
+   to manage roles, permissions, and view the audit log.
+
+Want to customize the HTML? Run:
+     bin/rails generate argus:trail:views
+to copy the views into app/views/argus/trail for editing.
+========================================================================

data/lib/generators/argus/trail/install/templates/create_argus_trail_tables.rb.erb

@@ -0,0 +1,47 @@
+class CreateArgusTrailTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :argus_trail_roles do |t|
+      t.string :name, null: false
+      t.string :description
+      t.timestamps
+    end
+    add_index :argus_trail_roles, :name, unique: true
+
+    create_table :argus_trail_permissions do |t|
+      t.string :name, null: false
+      t.string :description
+      t.timestamps
+    end
+    add_index :argus_trail_permissions, :name, unique: true
+
+    create_table :argus_trail_role_permissions do |t|
+      t.references :role, null: false, foreign_key: { to_table: :argus_trail_roles }
+      t.references :permission, null: false, foreign_key: { to_table: :argus_trail_permissions }
+      t.timestamps
+    end
+    add_index :argus_trail_role_permissions, [ :role_id, :permission_id ], unique: true,
+              name: "index_argus_trail_role_permissions_on_role_id_and_permission_id"
+
+    # Polymorphic join between any actor class (include Argus::Trail::Actor)
+    # and a role — engine-owned, so no migration is needed on your own
+    # actor/user table. An actor may hold any number of roles.
+    create_table :argus_trail_role_assignments do |t|
+      t.references :actor, polymorphic: true, null: false
+      t.references :role, null: false, foreign_key: { to_table: :argus_trail_roles }
+      t.timestamps
+    end
+    add_index :argus_trail_role_assignments, [ :actor_type, :actor_id, :role_id ], unique: true,
+              name: "index_argus_trail_role_assignments_on_actor_and_role"
+
+    create_table :argus_trail_audit_entries do |t|
+      t.string :event_type, null: false
+      t.references :subject, polymorphic: true, null: false
+      t.references :changed_by, polymorphic: true, null: true
+      t.references :role, foreign_key: { to_table: :argus_trail_roles }
+      t.references :permission, foreign_key: { to_table: :argus_trail_permissions }
+      t.text :metadata
+      t.datetime :created_at, null: false
+    end
+    add_index :argus_trail_audit_entries, :event_type
+  end
+end

data/lib/generators/argus/trail/install/templates/initializer.rb

@@ -0,0 +1,40 @@
+Argus::Trail.configure do |config|
+  # The class name of your app's user/account model — the one that gets
+  # `include Argus::Trail::Actor`. No column is added to this model's own
+  # table; roles are tracked in the engine's own polymorphic join table, so
+  # an actor may hold any number of roles (0..N).
+  config.actor_class_name = "User"
+
+  # Rename the engine's Role/Permission/RolePermission model classes — useful
+  # if "Role"/"Permission" already collide with another gem or one of your
+  # own models. These still back onto the engine's own tables
+  # (argus_trail_roles / argus_trail_permissions / argus_trail_role_permissions)
+  # — this renames the class, it does not let you point at a pre-existing
+  # table with a different schema.
+  # config.role_class_name            = "Argus::Trail::Role"
+  # config.permission_class_name      = "Argus::Trail::Permission"
+  # config.role_permission_class_name = "Argus::Trail::RolePermission"
+
+  # How the engine looks up "who made this change" when writing an audit
+  # entry. Defaults to a per-request actor set via:
+  #   # in your ApplicationController
+  #   before_action { Argus::Trail.current_actor = current_user }
+  # Override entirely for jobs/console usage, e.g. `-> { SomeJob.current_actor }`.
+  # config.changed_by_resolver = -> { Argus::Trail.current_actor }
+
+  # Gate for who may use the roles/permissions/audit-log admin screens.
+  # Left unset, Argus::Trail falls back to Pundit if it's in your Gemfile
+  # (define Argus::Trail::RolePolicy / PermissionPolicy / AuditEntryPolicy)
+  # — otherwise it raises until you set one of the two.
+  # config.authorize_with = ->(controller, record_or_class) { controller.current_user&.admin? }
+
+  # The method the engine calls on its controllers to get the logged-in actor.
+  # config.current_actor_method = :current_user
+
+  # Rows per page on the roles/permissions/audit-log admin screens.
+  # config.per_page = 30
+
+  # Render engine screens inside one of your app's own layouts instead of
+  # the engine's self-contained Tailwind-CDN layout.
+  # config.layout = "application"
+end

data/lib/generators/argus/trail/views/views_generator.rb

@@ -0,0 +1,18 @@
+require "rails/generators"
+
+module Argus
+  module Trail
+    module Generators
+      class ViewsGenerator < Rails::Generators::Base
+        source_root Argus::Trail::Engine.root.join("app", "views")
+
+        desc "Copies Argus::Trail's views into your app for full override"
+
+        def copy_views
+          directory "argus/trail", "app/views/argus/trail"
+          directory "layouts/argus/trail", "app/views/layouts/argus/trail"
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: argus-trail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ram Laxman Yadav
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: Plug-and-play role/permission management with a unified audit log of
+  role reassignments and permission grants/revokes, shipped as a mountable engine
+  with paginated HTML admin screens and generators for install/views/config. Agnostic
+  to auth (works standalone, auto-integrates with Pundit) and pagination (auto-integrates
+  with Kaminari).
+email:
+- yadavramlaxman@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/argus/trail/application_controller.rb
+- app/controllers/argus/trail/audit_entries_controller.rb
+- app/controllers/argus/trail/permissions_controller.rb
+- app/controllers/argus/trail/roles_controller.rb
+- app/helpers/argus/trail/application_helper.rb
+- app/models/argus/trail/application_record.rb
+- app/models/argus/trail/audit_entry.rb
+- app/models/argus/trail/permission.rb
+- app/models/argus/trail/role.rb
+- app/models/argus/trail/role_assignment.rb
+- app/models/argus/trail/role_permission.rb
+- app/views/argus/trail/audit_entries/index.html.erb
+- app/views/argus/trail/pagination/_simple_pager.html.erb
+- app/views/argus/trail/permissions/_form.html.erb
+- app/views/argus/trail/permissions/edit.html.erb
+- app/views/argus/trail/permissions/index.html.erb
+- app/views/argus/trail/permissions/new.html.erb
+- app/views/argus/trail/permissions/show.html.erb
+- app/views/argus/trail/roles/_form.html.erb
+- app/views/argus/trail/roles/edit.html.erb
+- app/views/argus/trail/roles/index.html.erb
+- app/views/argus/trail/roles/new.html.erb
+- app/views/argus/trail/roles/show.html.erb
+- app/views/layouts/argus/trail/application.html.erb
+- config/routes.rb
+- lib/argus/trail.rb
+- lib/argus/trail/actor.rb
+- lib/argus/trail/configuration.rb
+- lib/argus/trail/current.rb
+- lib/argus/trail/engine.rb
+- lib/argus/trail/pagination.rb
+- lib/argus/trail/version.rb
+- lib/generators/argus/trail/config/config_generator.rb
+- lib/generators/argus/trail/install/install_generator.rb
+- lib/generators/argus/trail/install/templates/POST_INSTALL
+- lib/generators/argus/trail/install/templates/create_argus_trail_tables.rb.erb
+- lib/generators/argus/trail/install/templates/initializer.rb
+- lib/generators/argus/trail/views/views_generator.rb
+homepage: https://github.com/reddoorz/argus-trail
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/reddoorz/argus-trail
+  source_code_uri: https://github.com/reddoorz/argus-trail
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Mountable Rails engine for roles, permissions, and an audit trail of who
+  changed what.
+test_files: []