role_fu 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baa4ff8c1fb945a9a511b86be18ecf899e03b72713faebaa2f903068a556fd26
-  data.tar.gz: cc7f9603db34f8363232db64520bfbc2f80cdd67b7488a508555dffaeba47fcf
+  metadata.gz: 8895d1ec974d84a207c9a1ef584910237b328442cb76f78d84a382b640527e43
+  data.tar.gz: da9cf4d703ecc9eef0e92bf2c883dc6cdacd49cd96e8c898289980465f96b445
 SHA512:
-  metadata.gz: 6fc1e0fccbd72b33b2d6df3d4ccee047d513347dae12f6ab05a8b8626c7d2e115e0206044a02b72b1443cde6628686de1898ccce982859762b724c444eca6dcf
-  data.tar.gz: c4ab6403ff5658dfa5f9a7335da11fabeaea677e5b33c4b42353e8ec1e310deb64f3157da7420ce3ae310ca9aee34b60ed77372804dbe6d526816fe78fa2d812
+  metadata.gz: 84626ecc3ac908297ad8dd95649126b851d990975ea74fb86fc73b8fe0f38af1c72630232393ce418720b722a3e695a64b55b9c05874c8d0e4b1010235d8770c
+  data.tar.gz: 4cd9382ad8db4b60fda9ebdc256cfe44f15662e07392c0b27170acb744c3947705acb58b985bf8811f816b9e5f111f470f17988680bf297219da78cb1a530126

data/.ruby-version

@@ -0,0 +1 @@
+4.0.6

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.6.0] - 2026-09-22
+
+### Added
+
+- **Field-level Abilities**: `role_fu_can?(action, field:)` and `role_fu_permitted_fields(action)` allow scoping a `Permission` to a single attribute (e.g. `reports.update` + `field: "status"`). A permission granted without a `field` remains a wildcard for that action, so existing action-only permissions are unaffected. The `permissions` table gains an optional `field` column (nullable — existing installs keep working without it).
+- **CanCanCan Adapter**: field-scoped permissions now translate into CanCanCan's own native attribute restriction (`can :update, Report, :status`) instead of role_fu re-implementing attribute-level authorization.
+- **Role Name Normalization**: role names are now canonicalized (`"Admin"`, `"admin"`, `"Admin User"`, `"admin-user"` all resolve to the same role) to prevent case/formatting duplicates. Does not singularize.
+- **`RoleFu::Authorizable`**: a minimal, framework-agnostic guard concern (`role_fu_authorize!`, `role_fu_can!`, raising `RoleFu::AccessDenied`) for apps that want a guard clause without adding a full authorization gem. Deliberately not an `allow`/`deny` DSL — see README for the Pundit/CanCanCan adapters when you need real rule resolution.
+- **`role_fu:upgrade` generator**: run after bumping the gem to catch up on optional schema/data changes. Inspects your actual schema/data instead of tracking "which version you were on" (nothing persists that reliably), so it's safe to run regardless of how many releases you skipped and safe to re-run. Currently detects the missing `permissions.field` column (generates the migration) and denormalized role names (reports only — never auto-merges, since two differently-cased roles may already coexist with their own assignments).
+- **Post-install banner**: `gem install`/`bundle install` now print a reminder to run `rails generate role_fu:upgrade` after upgrading.
+
+### BREAKING CHANGES
+
+- **Role name normalization** changes the stored `name` for newly created/looked-up roles (e.g. `"Admin"` -> `"admin"`). Existing rows with mixed-case names are **not** migrated automatically — run `rails generate role_fu:upgrade` after upgrading; it will detect and report them so you can decide how to merge duplicates before backfilling.
+
 ## [0.5.0] - 2026-07-15
 
 ### BREAKING CHANGES

data/README.md

@@ -99,6 +99,16 @@ user.has_role?(:manager, :any) # => true
 user.only_has_role?(:manager, org) # => true if this is their only role
 ```
 
+> **Role names are normalized** (`"Admin"`, `"admin"`, `"Admin User"` and
+> `"admin-user"` all resolve to the same role) so casing/formatting mistakes
+> don't silently create duplicate roles. Normalization does **not**
+> singularize — `"sales"` stays `"sales"` — since blindly singularizing
+> arbitrary business terms tends to mangle them. **Upgrading?** Existing rows
+> with mixed-case names aren't rewritten automatically —
+> `rails generate role_fu:upgrade` will detect and warn about them (it won't
+> backfill on its own: two differently-cased roles may already coexist and
+> need a human to decide how to merge them).
+
 #### Scopes (Finders)
 
 ```ruby
@@ -185,6 +195,36 @@ manager_role.permissions.create(action: "posts.edit")
 user.role_fu_can?("posts.edit") # => true
 ```
 
+**Field-level granularity:**
+
+Permissions can optionally be scoped to a single attribute. A permission granted
+*without* a `field` is a wildcard that satisfies any field-scoped check for that
+same action — so existing `action`-only permissions keep working unchanged.
+
+```ruby
+support_role.permissions.create(action: "reports.update", field: "status")
+
+user.role_fu_can?("reports.update")                # => true  (can do *something* here)
+user.role_fu_can?("reports.update", field: :status) # => true
+user.role_fu_can?("reports.update", field: :amount) # => false
+
+# Build a form / strong params allowlist dynamically:
+user.role_fu_permitted_fields("reports.update")
+# => ["status"]                    if scoped to specific fields
+# => :all                          if granted without a field restriction
+# => []                            if the action isn't granted at all
+```
+
+> **Upgrading an existing `permissions` table?** Run `rails generate role_fu:upgrade`
+> — it inspects your current schema/config and generates only the migrations
+> you're actually missing (here: adding `field` to `permissions`). Safe to
+> re-run any time, regardless of which version you're upgrading from. Without
+> the column, RoleFu transparently falls back to action-only checks.
+
+The **CanCanCan adapter** translates field-scoped permissions into CanCanCan's
+own native attribute restriction (`can :update, Report, :status`) instead of
+role_fu re-implementing attribute-level authorization itself.
+
 ---
 
 ### Adapters (Pundit & CanCanCan)
@@ -212,6 +252,40 @@ end
 
 _`PostPolicy#update?` will automatically check `user.role_fu_can?('posts.update')`._
 
+#### Lightweight Guard (no authorization gem)
+
+If you don't want to add Pundit or CanCanCan as a dependency just to raise on
+a missing role, `RoleFu::Authorizable` gives you two guard-clause helpers
+built on top of `has_role?` / `role_fu_can?`. **It is intentionally not an
+`allow`/`deny` DSL or a rule-resolution engine** — for anything beyond "raise
+unless this check passes" (policy objects, scopes, composable rules), use the
+Pundit or CanCanCan adapters instead.
+
+```ruby
+class ApplicationController < ActionController::Base
+  include RoleFu::Authorizable
+
+  rescue_from RoleFu::AccessDenied, with: :render_forbidden
+
+  private
+
+  def render_forbidden
+    head :forbidden
+  end
+end
+
+class PostsController < ApplicationController
+  def destroy
+    role_fu_authorize!(:admin)          # raises RoleFu::AccessDenied unless current_user.has_role?(:admin)
+    role_fu_can!("posts.destroy")       # raises RoleFu::AccessDenied unless current_user.role_fu_can?("posts.destroy")
+    # ...
+  end
+end
+```
+
+Resolves the acting user via `current_user` by default; override
+`role_fu_current_user` for jobs/service objects that don't have one.
+
 ---
 
 ### Performance (N+1 Prevention)
@@ -315,6 +389,24 @@ User.in_group(:admin)      # Alias for with_group/with_role
 User.not_in_group(:admin)  # Alias for without_group/without_role
 ```
 
+## Upgrading RoleFu
+
+After bumping the gem version, run:
+
+```bash
+rails generate role_fu:upgrade
+rails db:migrate
+```
+
+It inspects your actual schema/config (not "which version you were on" —
+nothing persists that reliably) and generates only what's missing, so it's
+safe to run regardless of how many releases you skipped, and safe to re-run.
+Currently checks for: the `field` column on `permissions` (see
+[Field-level granularity](#4-role-abilities-permissions)), and role names
+that don't match RoleFu's [normalized format](#roleable-user-model) (reported
+only — never auto-merged, since two differently-cased roles may already
+coexist).
+
 ## Migrating from Rolify
 
 1. **Code Changes**: Replace `rolify` with `include RoleFu::Roleable` and `resourcify` with `include RoleFu::Resourceable`.

data/gemfiles/rails_7.2.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    role_fu (0.5.0)
+    role_fu (0.6.0)
       activerecord (>= 7.2)
 
 GEM
@@ -386,7 +386,7 @@ CHECKSUMS
   rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
   regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
-  role_fu (0.5.0)
+  role_fu (0.6.0)
   rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
   rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
   rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    role_fu (0.5.0)
+    role_fu (0.6.0)
       activerecord (>= 7.2)
 
 GEM
@@ -382,7 +382,7 @@ CHECKSUMS
   rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
   regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
-  role_fu (0.5.0)
+  role_fu (0.6.0)
   rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
   rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
   rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    role_fu (0.5.0)
+    role_fu (0.6.0)
       activerecord (>= 7.2)
 
 GEM
@@ -384,7 +384,7 @@ CHECKSUMS
   rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
   regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
-  role_fu (0.5.0)
+  role_fu (0.6.0)
   rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
   rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
   rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836

data/lib/generators/role_fu/templates/abilities_migration.rb.erb

@@ -5,11 +5,12 @@ class RoleFuCreatePermissions < ActiveRecord::Migration<%= migration_version %>
     create_table :permissions<%= ", id: :uuid" if uuid_enabled? %> do |t|
       t.references :role, null: false, index: true<%= ", type: :uuid" if uuid_enabled? %>
       t.string :action, null: false
+      t.string :field
       t.jsonb :conditions, default: {}
 
       t.timestamps
     end
-    
-    add_index :permissions, [:role_id, :action]
+
+    add_index :permissions, [:role_id, :action, :field]
   end
 end

data/lib/generators/role_fu/templates/upgrade_permissions_field_migration.rb.erb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class RoleFuAddFieldToPermissions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :permissions, :field, :string
+    add_index :permissions, [:role_id, :action, :field]
+  end
+end

data/lib/generators/role_fu/upgrade_generator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+module RoleFu
+  module Generators
+    # Run after bumping the role_fu gem version. Does not track "which
+    # version you upgraded from" - there's nowhere reliable to read that from
+    # (Gemfile.lock only ever has the current version). Instead it inspects
+    # the actual schema/config already installed and generates whatever is
+    # missing, so it's safe to run regardless of how many versions you skipped,
+    # and safe to run again if nothing changed.
+    class UpgradeGenerator < ActiveRecord::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :name, type: :string, default: "upgrade"
+
+      def self.banner
+        "bin/rails generate role_fu:upgrade\n\n" \
+        "Detects which optional role_fu columns/config are missing for your\n" \
+        "installed models and generates the migrations needed to catch up."
+      end
+
+      desc ""
+
+      def run_upgrade_checks
+        applied = upgrade_checks.count { |check| send(check) }
+
+        say "role_fu is already up to date - nothing to generate.", :green if applied.zero?
+      end
+
+      private
+
+      # Each check returns true when it generated something or has a warning
+      # to report. Add new entries here as future optional columns/config land.
+      def upgrade_checks
+        [:check_permissions_field, :check_denormalized_role_names]
+      end
+
+      def check_permissions_field
+        return false unless table_exists?(:permissions)
+        return false if column_exists?(:permissions, :field)
+
+        say "Adding missing 'field' column to permissions (see README: Field-level granularity)", :yellow
+        migration_template "upgrade_permissions_field_migration.rb.erb", "db/migrate/role_fu_add_field_to_permissions.rb"
+        true
+      end
+
+      # Not auto-fixed: blindly renaming could collide two existing roles
+      # (e.g. "Admin" and "admin" both already present with their own
+      # role_assignments) into one, which needs a human to decide how to
+      # merge rather than a migration silently doing it.
+      def check_denormalized_role_names
+        role_class = RoleFu.configuration.role_class_name.safe_constantize
+        return false unless role_class&.table_exists?
+
+        denormalized = role_class.pluck(:name).any? { |name| name != RoleFu.normalize_role_name(name) }
+        return false unless denormalized
+
+        say "Found role names that don't match RoleFu's normalized format (e.g. \"Admin\" vs \"admin\").", :yellow
+        say "Not fixed automatically - two differently-cased roles may already coexist and need a human merge decision.", :yellow
+        say "Review, then backfill e.g.: UPDATE #{role_class.table_name} SET name = LOWER(name) WHERE name != LOWER(name)", :yellow
+        true
+      end
+
+      def table_exists?(name)
+        ActiveRecord::Base.connection.table_exists?(name.to_s)
+      rescue
+        false
+      end
+
+      def column_exists?(table, column)
+        ActiveRecord::Base.connection.column_exists?(table.to_s, column)
+      rescue
+        false
+      end
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]" if Rails::VERSION::MAJOR >= 5
+      end
+    end
+  end
+end

data/lib/role_fu/ability.rb

@@ -4,20 +4,55 @@ module RoleFu
   module Ability
     extend ActiveSupport::Concern
 
-    def role_fu_can?(action, _resource = nil)
-      role_fu_permissions.include?(action.to_s)
+    # @param action [String, Symbol] e.g. "posts.update"
+    # @param field [String, Symbol, nil] restrict the check to a single attribute
+    #   (e.g. :description). A permission granted with field: nil is a wildcard
+    #   that satisfies any field-scoped check for the same action.
+    def role_fu_can?(action, _resource = nil, field: nil)
+      fields = role_fu_permission_fields(action)
+      return false if fields.nil?
+
+      field.nil? || fields.include?(nil) || fields.include?(field.to_s)
+    end
+
+    # Fields explicitly granted for `action`.
+    # Returns :all when the action was granted without a field restriction,
+    # [] when the action isn't granted at all, or the explicit field list otherwise.
+    def role_fu_permitted_fields(action)
+      fields = role_fu_permission_fields(action)
+      return [] if fields.nil?
+      return :all if fields.include?(nil)
+
+      fields.to_a
     end
 
     def role_fu_permissions
+      role_fu_permissions_index.keys.to_set
+    end
+
+    private
+
+    def role_fu_permission_fields(action)
+      role_fu_permissions_index[action.to_s]
+    end
+
+    def role_fu_permissions_index
       return @_role_fu_permissions if defined?(@_role_fu_permissions) && @_role_fu_permissions
 
       permission_class = "Permission".safe_constantize
-      return Set.new unless permission_class
+      return (@_role_fu_permissions = {}) unless permission_class
 
       scope = roles
       scope = filter_expired(scope) if respond_to?(:filter_expired, true)
 
-      @_role_fu_permissions = scope.joins(:permissions).pluck("permissions.action").map(&:to_s).to_set
+      has_field_column = permission_class.column_names.include?("field")
+      columns = has_field_column ? %w[permissions.action permissions.field] : %w[permissions.action]
+      rows = scope.joins(:permissions).pluck(*columns)
+
+      @_role_fu_permissions = rows.each_with_object({}) do |row, index|
+        action, field = has_field_column ? row : [row, nil]
+        (index[action.to_s] ||= Set.new) << field
+      end
     end
   end
 end

data/lib/role_fu/adapters/cancancan.rb

@@ -13,11 +13,20 @@ module RoleFu
 
           if parts.size == 2
             subject_name, rule = parts
-            begin
-              subject_class = subject_name.classify.constantize
-              can rule.to_sym, subject_class
+            subject_class = begin
+              subject_name.classify.constantize
             rescue NameError
-              can rule.to_sym, subject_name.to_sym
+              subject_name.to_sym
+            end
+
+            # Field-scoped permissions map onto CanCanCan's own attribute
+            # restriction (`can :update, Post, :title`) instead of role_fu
+            # re-implementing attribute authorization itself.
+            fields = user.role_fu_permitted_fields(action)
+            if fields == :all
+              can rule.to_sym, subject_class
+            else
+              can rule.to_sym, subject_class, *fields.map(&:to_sym)
             end
           else
             can action.to_sym, :all

data/lib/role_fu/authorizable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RoleFu
+  # Raised by RoleFu::Authorizable guard methods. Rescue it yourself
+  # (e.g. `rescue_from RoleFu::AccessDenied` in ApplicationController) —
+  # role_fu does not register a rescue handler on your behalf.
+  class AccessDenied < RoleFu::Error
+    def initialize(message = "You are not authorized to perform this action.")
+      super
+    end
+  end
+
+  # Minimal, framework-agnostic authorization guard for apps that don't want
+  # to pull in a full authorization gem just to raise on a missing role.
+  #
+  # This is deliberately NOT an `allow`/`deny` DSL or a rule-resolution
+  # engine — for anything beyond "raise unless this check passes", reach for
+  # the Pundit or CanCanCan adapters instead. Mixing this concern into a
+  # controller (or any object that responds to `current_user`, or overrides
+  # `role_fu_current_user`) just gives you two guard-clause helpers built on
+  # top of the `has_role?` / `role_fu_can?` methods you already have.
+  module Authorizable
+    extend ActiveSupport::Concern
+
+    # Override this if the current user isn't exposed via `current_user`
+    # (e.g. in a job or service object).
+    def role_fu_current_user
+      current_user if respond_to?(:current_user)
+    end
+
+    def role_fu_authorize!(role_name, resource = nil)
+      user = role_fu_current_user
+      raise RoleFu::AccessDenied unless user&.respond_to?(:has_role?) && user.has_role?(role_name, resource)
+
+      true
+    end
+
+    def role_fu_can!(action, resource = nil, field: nil)
+      user = role_fu_current_user
+      raise RoleFu::AccessDenied unless user&.respond_to?(:role_fu_can?) && user.role_fu_can?(action, resource, field: field)
+
+      true
+    end
+  end
+end

data/lib/role_fu/role.rb

@@ -15,7 +15,15 @@ module RoleFu
 
       belongs_to :resource, polymorphic: true, optional: true
 
+      before_validation :normalize_role_fu_name
+
       validates :name, presence: true, uniqueness: {scope: [:resource_type, :resource_id]}
     end
+
+    private
+
+    def normalize_role_fu_name
+      self.name = RoleFu.normalize_role_name(name) if name.present?
+    end
   end
 end

data/lib/role_fu/roleable.rb

@@ -24,7 +24,7 @@ module RoleFu
         role_table = RoleFu.role_class.table_name
         assignment_table = RoleFu.role_assignment_class.table_name
 
-        query = joins(:roles).where(role_table => {name: role_name.to_s})
+        query = joins(:roles).where(role_table => {name: RoleFu.normalize_role_name(role_name)})
 
         if RoleFu.role_assignment_class.column_names.include?("expires_at")
           query = query.where("#{assignment_table}.expires_at IS NULL OR #{assignment_table}.expires_at > ?", Time.current)
@@ -136,7 +136,7 @@ module RoleFu
       return false if role_name.nil?
 
       if resource == :any
-        filter_expired(roles.where(name: role_name.to_s)).exists?
+        filter_expired(roles.where(name: RoleFu.normalize_role_name(role_name))).exists?
       else
         return true if filter_expired(find_roles(role_name, resource)).any?
 
@@ -157,7 +157,7 @@ module RoleFu
     end
 
     def has_cached_role?(role_name, resource = nil)
-      role_name = role_name.to_s
+      role_name = RoleFu.normalize_role_name(role_name)
       roles.to_a.any? do |role|
         next false unless role.name == role_name
 
@@ -241,14 +241,14 @@ module RoleFu
 
     def find_or_create_role(role_name, resource)
       RoleFu.role_class.find_or_create_by(
-        name: role_name.to_s,
+        name: RoleFu.normalize_role_name(role_name),
         resource_type: resource_type_for(resource),
         resource_id: resource_id_for(resource)
       )
     end
 
     def find_roles(role_name, resource)
-      query = roles.where(name: role_name.to_s)
+      query = roles.where(name: RoleFu.normalize_role_name(role_name))
 
       if resource.is_a?(Class)
         query.where(resource_type: resource.to_s, resource_id: nil)

data/lib/role_fu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RoleFu
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/role_fu.rb

@@ -3,6 +3,10 @@
 require "active_support/concern"
 require "active_support/core_ext/string/inflections"
 
+module RoleFu
+  class Error < StandardError; end
+end
+
 require_relative "role_fu/version"
 require_relative "role_fu/configuration"
 require_relative "role_fu/role"
@@ -11,14 +15,13 @@ require_relative "role_fu/roleable"
 require_relative "role_fu/resourceable"
 require_relative "role_fu/permission"
 require_relative "role_fu/ability"
+require_relative "role_fu/authorizable"
 require_relative "role_fu/cleanup"
 require_relative "role_fu/adapters/cancancan"
 require_relative "role_fu/adapters/pundit"
 require_relative "role_fu/railtie" if defined?(Rails)
 
 module RoleFu
-  class Error < StandardError; end
-
   class << self
     def with_actor(actor)
       Thread.current[:role_fu_actor] = actor
@@ -30,5 +33,15 @@ module RoleFu
     def current_actor
       Thread.current[:role_fu_actor]
     end
+
+    # Canonicalizes a role name so that "Admin", "admin", "Admin User" and
+    # "admin-user" all resolve to the same underlying Role row.
+    # Note: does NOT singularize (unlike acl9) — that silently mangles
+    # ordinary business terms (e.g. "sales" -> "sale").
+    def normalize_role_name(name)
+      return nil if name.nil?
+
+      name.to_s.strip.gsub(/[\s-]+/, "_").underscore
+    end
   end
 end

data/mise.toml

@@ -0,0 +1,14 @@
+[tools]
+ruby = "4.0.6"
+
+[tasks.test]
+description = "Run the RSpec suite"
+run = "bundle exec rake spec"
+
+[tasks.lint]
+description = "Run RuboCop"
+run = "bundle exec rubocop"
+
+[tasks.release]
+description = "Build and publish the gem (rake release)"
+run = "bundle exec rake release"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: role_fu
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Alexey Poimtsev
@@ -116,6 +116,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ruby-version"
 - Appraisals
 - CHANGELOG.md
 - LICENSE.txt
@@ -142,10 +143,13 @@ files:
 - lib/generators/role_fu/templates/role.rb.erb
 - lib/generators/role_fu/templates/role_assignment.rb.erb
 - lib/generators/role_fu/templates/role_fu.rb
+- lib/generators/role_fu/templates/upgrade_permissions_field_migration.rb.erb
+- lib/generators/role_fu/upgrade_generator.rb
 - lib/role_fu.rb
 - lib/role_fu/ability.rb
 - lib/role_fu/adapters/cancancan.rb
 - lib/role_fu/adapters/pundit.rb
+- lib/role_fu/authorizable.rb
 - lib/role_fu/cleanup.rb
 - lib/role_fu/configuration.rb
 - lib/role_fu/permission.rb
@@ -156,6 +160,7 @@ files:
 - lib/role_fu/roleable.rb
 - lib/role_fu/version.rb
 - lib/tasks/role_fu.rake
+- mise.toml
 - sig/role_fu.rbs
 homepage: https://github.com/alec-c4/role_fu
 licenses:
@@ -164,6 +169,17 @@ metadata:
   homepage_uri: https://github.com/alec-c4/role_fu
   source_code_uri: https://github.com/alec-c4/role_fu
   changelog_uri: https://github.com/alec-c4/role_fu/blob/main/CHANGELOG.md
+post_install_message: |
+  Thanks for installing role_fu 0.6.0!
+
+  Upgrading from an older role_fu? Run this to pick up any missing
+  schema/data changes (it inspects your app, so it's a no-op if there's
+  nothing to do):
+
+    rails generate role_fu:upgrade
+    rails db:migrate
+
+  Full changelog: https://github.com/alec-c4/role_fu/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -178,7 +194,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A modern role management gem for Rails, replacing rolify.
 test_files: []