plutonium 0.39.2 → 0.40.0

data/lib/generators/pu/saas/USAGE

@@ -0,0 +1,22 @@
+Description:
+    SaaS generators for multi-tenant applications with user accounts, entities, and memberships.
+
+Generators:
+    pu:saas:setup       Complete SaaS setup (user + entity + membership)
+    pu:saas:user        SaaS user account with Rodauth
+    pu:saas:entity      Entity/organization model
+    pu:saas:membership  Membership join table linking users to entities
+
+Example:
+    rails g pu:saas:setup --user Customer --entity Organization
+
+    This creates:
+        - Customer user account with Rodauth authentication
+        - Organization entity model with unique name
+        - OrganizationCustomer membership model with role enum
+
+See individual generator help for more options:
+    rails g pu:saas:setup --help
+    rails g pu:saas:user --help
+    rails g pu:saas:entity --help
+    rails g pu:saas:membership --help

data/lib/generators/pu/saas/entity/USAGE

@@ -0,0 +1,19 @@
+Description:
+    Generate a SaaS entity model (organization/tenant).
+    Creates an entity with a unique name field for multi-tenant applications.
+
+Example:
+    rails g pu:saas:entity Organization
+    rails g pu:saas:entity Organization --dest=main_app
+    rails g pu:saas:entity Company --extra-attributes=slug:string,domain:string
+
+    This creates:
+        app/models/organization.rb
+        app/controllers/organizations_controller.rb
+        app/policies/organization_policy.rb
+        app/definitions/organization_definition.rb
+        db/migrate/XXX_create_organizations.rb (with unique index on name)
+
+Options:
+    --extra-attributes      Additional model attributes (name:string is always included)
+    --dest                  Destination package (default: main_app)

data/lib/generators/pu/saas/entity_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+require_relative "../lib/plutonium_generators"
+
+module Pu
+  module Saas
+    class EntityGenerator < ::Rails::Generators::NamedBase
+      include PlutoniumGenerators::Generator
+
+      desc "Generate a SaaS entity model (organization/tenant)"
+
+      class_option :extra_attributes, type: :array, default: [],
+        desc: "Additional attributes for the entity model"
+
+      def start
+        generate_entity_resource
+        add_unique_index_to_migration
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+
+      private
+
+      def generate_entity_resource
+        invoke "pu:res:scaffold", [normalized_name, *entity_attributes],
+          dest: selected_destination_feature,
+          model: true,
+          force: options[:force],
+          skip: options[:skip]
+      end
+
+      def add_unique_index_to_migration
+        migration_dir = File.join("db", "migrate")
+        migration_file = Dir[File.join(migration_dir, "*_create_#{normalized_name.pluralize}.rb")].first
+
+        return unless migration_file && File.exist?(migration_file)
+
+        insert_into_file migration_file,
+          indent("add_index :#{normalized_name.pluralize}, :name, unique: true\n", 4),
+          before: /^  end\s*$/
+      end
+
+      def entity_attributes
+        ["name:string", *Array(options[:extra_attributes])]
+      end
+
+      def normalized_name = name.underscore
+
+      def selected_destination_feature
+        feature_option :dest, prompt: "Select destination feature"
+      end
+    end
+  end
+end

data/lib/generators/pu/saas/membership/USAGE

@@ -0,0 +1,25 @@
+Description:
+    Generate a SaaS membership model linking users to entities.
+    Creates a join table with role enum and bidirectional associations.
+
+    Requires both user and entity models to exist first.
+
+Example:
+    rails g pu:saas:membership --user Customer --entity Organization
+    rails g pu:saas:membership --user Customer --entity Organization --roles=member,admin,owner
+    rails g pu:saas:membership --user Customer --entity Organization --extra-attributes=joined_at:datetime
+
+    This creates:
+        app/models/organization_customer.rb (with role enum and uniqueness validation)
+        db/migrate/XXX_create_organization_customers.rb (with unique index)
+
+    And adds to existing models:
+        Customer: has_many :organization_customers, has_many :organizations
+        Organization: has_many :organization_customers, has_many :customers
+
+Options:
+    --user                  User model name (required)
+    --entity                Entity model name (required)
+    --roles                 Comma-separated roles (default: member,owner)
+    --extra-attributes      Additional model attributes
+    --dest                  Destination package (default: main_app)

data/lib/generators/pu/saas/membership_generator.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require_relative "../lib/plutonium_generators"
+
+module Pu
+  module Saas
+    class MembershipGenerator < ::Rails::Generators::Base
+      include PlutoniumGenerators::Generator
+
+      desc "Generate a SaaS membership model linking users to entities"
+
+      class_option :user, type: :string, required: true,
+        desc: "The user model name (e.g., Customer)"
+
+      class_option :entity, type: :string, required: true,
+        desc: "The entity model name (e.g., Organization)"
+
+      class_option :roles, type: :array, default: %w[member owner],
+        desc: "Available roles for memberships"
+
+      class_option :extra_attributes, type: :array, default: [],
+        desc: "Additional attributes for the membership model"
+
+      def start
+        validate_models_exist!
+        generate_membership_model
+        add_unique_index_to_migration
+        add_default_to_role_column
+        add_role_enum_to_model
+        add_unique_validation_to_model
+        add_associations_to_models
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+
+      private
+
+      def validate_models_exist!
+        user_model_path = File.join("app", "models", "#{normalized_user_name}.rb")
+        entity_model_path = File.join("app", "models", "#{normalized_entity_name}.rb")
+
+        unless File.exist?(user_model_path)
+          raise "User model '#{normalized_user_name}' does not exist at #{user_model_path}. Please create it first with: rails g pu:saas:user #{options[:user]}"
+        end
+
+        unless File.exist?(entity_model_path)
+          raise "Entity model '#{normalized_entity_name}' does not exist at #{entity_model_path}. Please create it first with: rails g pu:saas:entity #{options[:entity]}"
+        end
+      end
+
+      def generate_membership_model
+        invoke "pu:res:model", [membership_model_name, *membership_attributes],
+          dest: selected_destination_feature,
+          force: options[:force],
+          skip: options[:skip]
+      end
+
+      def add_unique_index_to_migration
+        migration_file = find_migration_file
+
+        return unless migration_file
+
+        insert_into_file migration_file,
+          indent("add_index :#{membership_table_name}, [:#{normalized_entity_name}_id, :#{normalized_user_name}_id], unique: true\n", 4),
+          before: /^  end\s*$/
+      end
+
+      def add_default_to_role_column
+        migration_file = find_migration_file
+
+        return unless migration_file
+
+        gsub_file migration_file,
+          /t\.integer :role, null: false/,
+          "t.integer :role, null: false, default: 0"
+      end
+
+      def add_role_enum_to_model
+        model_file = File.join("app", "models", "#{membership_model_name}.rb")
+
+        return unless File.exist?(model_file)
+
+        enum_definition = "enum :role, #{roles_enum}\n"
+        insert_into_file model_file, indent(enum_definition, 2), before: /^\s*# add enums above\./
+      end
+
+      def add_unique_validation_to_model
+        model_file = File.join("app", "models", "#{membership_model_name}.rb")
+
+        return unless File.exist?(model_file)
+
+        validation = "validates :#{normalized_user_name}, uniqueness: {scope: :#{normalized_entity_name}_id, message: \"is already a member of this #{normalized_entity_name.humanize.downcase}\"}\n"
+        insert_into_file model_file, indent(validation, 2), before: /^\s*# add validations above\./
+      end
+
+      def add_associations_to_models
+        add_association_to_entity_model
+        add_association_to_user_model
+      end
+
+      def add_association_to_entity_model
+        entity_model_path = File.join("app", "models", "#{normalized_entity_name}.rb")
+
+        return unless File.exist?(entity_model_path)
+
+        associations = <<~RUBY
+          has_many :#{membership_table_name}, dependent: :destroy
+          has_many :#{normalized_user_name.pluralize}, through: :#{membership_table_name}
+        RUBY
+        insert_into_file entity_model_path, indent(associations, 2), before: /# add has_many associations above\.\n/
+      end
+
+      def add_association_to_user_model
+        user_model_path = File.join("app", "models", "#{normalized_user_name}.rb")
+
+        return unless File.exist?(user_model_path)
+
+        associations = <<~RUBY
+          has_many :#{membership_table_name}, dependent: :destroy
+          has_many :#{normalized_entity_name.pluralize}, through: :#{membership_table_name}
+        RUBY
+        insert_into_file user_model_path, indent(associations, 2), before: /# add has_many associations above\.\n/
+      end
+
+      def find_migration_file
+        migration_dir = File.join("db", "migrate")
+        Dir[File.join(migration_dir, "*_create_#{membership_table_name}.rb")].first
+      end
+
+      def membership_model_name
+        "#{normalized_entity_name}_#{normalized_user_name}"
+      end
+
+      def membership_table_name
+        membership_model_name.pluralize
+      end
+
+      def membership_attributes
+        [
+          "#{normalized_entity_name}:references",
+          "#{normalized_user_name}:references",
+          "role:integer",
+          *Array(options[:extra_attributes])
+        ]
+      end
+
+      def normalized_user_name = options[:user].underscore
+
+      def normalized_entity_name = options[:entity].underscore
+
+      def roles
+        Array(options[:roles]).flat_map { |r| r.split(",") }.map(&:strip)
+      end
+
+      def roles_enum
+        roles.each_with_index.map { |r, i| "#{r}: #{i}" }.join(", ")
+      end
+
+      def selected_destination_feature
+        feature_option :dest, prompt: "Select destination feature"
+      end
+    end
+  end
+end

data/lib/generators/pu/saas/setup/USAGE

@@ -0,0 +1,27 @@
+Description:
+    Generate a complete SaaS setup with user account, entity, and membership.
+    This is the recommended way to set up multi-tenant authentication.
+
+Example:
+    rails g pu:saas:setup --user Customer --entity Organization
+    rails g pu:saas:setup --user Customer --entity Organization --roles=member,admin,owner
+    rails g pu:saas:setup --user Customer --entity Organization --no-allow-signup
+    rails g pu:saas:setup --user Customer --entity Organization --user-attributes=name:string
+    rails g pu:saas:setup --user Customer --entity Organization --skip-entity
+
+    This creates:
+        1. User account (Customer) with Rodauth authentication
+        2. Entity model (Organization) with unique name
+        3. Membership model (OrganizationCustomer) with role enum
+
+Options:
+    --user                      User model name (required)
+    --entity                    Entity model name (required)
+    --allow-signup              Allow public registration (default: true)
+    --roles                     Comma-separated membership roles (default: member,owner)
+    --skip-entity               Skip entity model generation
+    --skip-membership           Skip membership model generation
+    --user-attributes           Additional user model attributes
+    --entity-attributes         Additional entity model attributes
+    --membership-attributes     Additional membership model attributes
+    --dest                      Destination package (default: main_app)

data/lib/generators/pu/saas/setup_generator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+return unless defined?(Rodauth::Rails)
+
+require "rails/generators/base"
+require_relative "../lib/plutonium_generators"
+
+module Pu
+  module Saas
+    class SetupGenerator < ::Rails::Generators::Base
+      include PlutoniumGenerators::Generator
+
+      desc "Generate a complete SaaS setup with user, entity, and membership"
+
+      class_option :user, type: :string, required: true,
+        desc: "The user model name (e.g., Customer)"
+
+      class_option :entity, type: :string, required: true,
+        desc: "The entity model name (e.g., Organization)"
+
+      class_option :allow_signup, type: :boolean, default: true,
+        desc: "Whether to allow users to sign up to the platform"
+
+      class_option :roles, type: :array, default: %w[member owner],
+        desc: "Available roles for memberships"
+
+      class_option :skip_entity, type: :boolean, default: false,
+        desc: "Skip entity model generation"
+
+      class_option :skip_membership, type: :boolean, default: false,
+        desc: "Skip membership model generation"
+
+      class_option :user_attributes, type: :array, default: [],
+        desc: "Additional attributes for the user model (e.g., name:string)"
+
+      class_option :entity_attributes, type: :array, default: [],
+        desc: "Additional attributes for the entity model"
+
+      class_option :membership_attributes, type: :array, default: [],
+        desc: "Additional attributes for the membership model"
+
+      def start
+        generate_user
+        generate_entity unless options[:skip_entity]
+        generate_membership unless options[:skip_membership]
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+
+      private
+
+      def generate_user
+        # Use class-based invocation to avoid Thor's invoke caching
+        klass = Rails::Generators.find_by_namespace("pu:saas:user")
+        klass.new(
+          [options[:user]],
+          {
+            allow_signup: options[:allow_signup],
+            extra_attributes: options[:user_attributes],
+            force: options[:force],
+            skip: options[:skip]
+          }
+        ).invoke_all
+      end
+
+      def generate_entity
+        # Use class-based invocation to avoid Thor's invoke caching
+        klass = Rails::Generators.find_by_namespace("pu:saas:entity")
+        klass.new(
+          [options[:entity]],
+          {
+            extra_attributes: options[:entity_attributes],
+            dest: options[:dest],
+            force: options[:force],
+            skip: options[:skip]
+          }
+        ).invoke_all
+      end
+
+      def generate_membership
+        # Use class-based invocation to avoid Thor's invoke caching
+        klass = Rails::Generators.find_by_namespace("pu:saas:membership")
+        klass.new(
+          [],
+          {
+            user: options[:user],
+            entity: options[:entity],
+            roles: options[:roles],
+            extra_attributes: options[:membership_attributes],
+            dest: options[:dest],
+            force: options[:force],
+            skip: options[:skip]
+          }
+        ).invoke_all
+      end
+    end
+  end
+end

data/lib/generators/pu/saas/user/USAGE

@@ -0,0 +1,21 @@
+Description:
+    Generate a SaaS user account with Rodauth authentication.
+    Creates a user model with login, signup, password reset, and other auth features.
+
+Example:
+    rails g pu:saas:user Customer
+    rails g pu:saas:user Customer --no-allow-signup
+    rails g pu:saas:user Customer --extra-attributes=name:string,phone:string
+
+    This creates:
+        app/models/customer.rb
+        app/rodauth/customer_rodauth_plugin.rb
+        app/controllers/rodauth/customer_controller.rb
+        app/controllers/customers_controller.rb
+        app/policies/customer_policy.rb
+        app/definitions/customer_definition.rb
+        db/migrate/XXX_create_rodauth_customer_*.rb
+
+Options:
+    --allow-signup          Allow public registration (default: true)
+    --extra-attributes      Additional model attributes (e.g., name:string)

data/lib/generators/pu/saas/user_generator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+return unless defined?(Rodauth::Rails)
+
+require "rails/generators/named_base"
+require_relative "../lib/plutonium_generators"
+
+module Pu
+  module Saas
+    class UserGenerator < ::Rails::Generators::NamedBase
+      include PlutoniumGenerators::Concerns::Logger
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate a SaaS user account with Rodauth integration"
+
+      class_option :allow_signup, type: :boolean, default: true,
+        desc: "Whether to allow users to sign up to the platform"
+
+      class_option :extra_attributes, type: :array, default: [],
+        desc: "Additional attributes to add to the account model (e.g., name:string)"
+
+      def start
+        generate_user_account
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+
+      private
+
+      def generate_user_account
+        invoke "pu:rodauth:account", [name],
+          defaults: false,
+          **user_features,
+          extra_attributes: Array(options[:extra_attributes]),
+          force: options[:force],
+          skip: options[:skip],
+          lint: true
+      end
+
+      def user_features
+        features = %i[
+          login
+          remember
+          logout
+          create_account
+          verify_account
+          verify_account_grace_period
+          reset_password
+          reset_password_notify
+          change_login
+          verify_login_change
+          change_password
+          change_password_notify
+          case_insensitive_login
+          internal_request
+        ]
+
+        features.delete(:create_account) unless options[:allow_signup]
+        features.map { |feature| [feature, true] }.to_h
+      end
+
+      def normalized_name = name.underscore
+    end
+  end
+end

data/lib/plutonium/definition/base.rb

@@ -13,7 +13,8 @@ module Plutonium
     #     field :name, as: :string
     #     input :email, as: :email
     #     filter :status, type: :select, collection: %w[active inactive]
-    #     scope :active, default: true
+    #     scope :active
+    #     default_scope :active
     #     sorter :created_at
     #
     #     def customize_fields
@@ -29,6 +30,7 @@ module Plutonium
       include InheritableConfigAttr
       include Actions
       include Sorting
+      include Scoping
       include Search
       include NestedInputs
 

data/lib/plutonium/definition/scoping.rb

@@ -0,0 +1,20 @@
+module Plutonium
+  module Definition
+    module Scoping
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_default_scope, instance_writer: false, instance_predicate: false
+
+        def self.default_scope(name = nil)
+          self._default_scope = name.to_sym if name
+          _default_scope
+        end
+      end
+
+      def default_scope
+        self.class._default_scope
+      end
+    end
+  end
+end

data/lib/plutonium/invites/concerns/cancel_invite.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Invites
+    module Concerns
+      # CancelInvite provides the cancel invitation interaction logic.
+      #
+      # Include this concern in your cancel interaction and override methods
+      # as needed for customization.
+      #
+      # @example Basic usage
+      #   class CancelInviteInteraction < Plutonium::Resource::Interaction
+      #     include Plutonium::Invites::Concerns::CancelInvite
+      #   end
+      #
+      module CancelInvite
+        extend ActiveSupport::Concern
+
+        included do
+          presents label: "Cancel Invitation", icon: "outline/x-circle"
+        end
+
+        def execute
+          unless resource.pending?
+            return failed(not_pending_message)
+          end
+
+          resource.cancelled!
+          succeed(resource).with_message(success_message)
+        end
+
+        private
+
+        def success_message
+          "Invitation cancelled"
+        end
+
+        def not_pending_message
+          "Can only cancel pending invitations"
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/invites/concerns/invitable.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Invites
+    module Concerns
+      # Invitable allows any model to trigger invites and be notified on acceptance.
+      #
+      # This pattern is useful when you have a profile or record that needs to
+      # invite a user and then connect itself to that user after acceptance.
+      #
+      # @example TenantProfile that invites users
+      #   class TenantProfile < ApplicationRecord
+      #     include Plutonium::Resource::Record
+      #     include Plutonium::Invites::Concerns::Invitable
+      #
+      #     belongs_to :entity
+      #     belongs_to :user, optional: true
+      #
+      #     def on_invite_accepted(user)
+      #       update!(user: user)
+      #     end
+      #   end
+      #
+      # @example Creating an invite from an invitable
+      #   tenant_profile.create_invite!(
+      #     email: tenant_profile.email,
+      #     entity: tenant_profile.entity,
+      #     invited_by: current_user,
+      #     role: :member,
+      #     email_template: "tenant"
+      #   )
+      #
+      module Invitable
+        extend ActiveSupport::Concern
+
+        included do
+          # Association to the pending user invite for this record.
+          # Scoped to pending only - cancelled/expired/accepted invites are kept for audit.
+          has_one :user_invite, -> { pending }, class_name: "Invites::UserInvite", as: :invitable
+        end
+
+        # Create an invite for this invitable.
+        #
+        # If there's already a pending invite for this invitable, it will be
+        # destroyed and replaced with a new one.
+        #
+        # @param email [String] the email address to invite
+        # @param entity [Object] the entity to join
+        # @param invited_by [Object] the user creating the invite
+        # @param role [Symbol, String] the role to assign (default: nil, uses model default)
+        # @param email_template [String, nil] optional template type for email customization
+        # @return [Object] the created invite record
+        def create_invite!(email:, entity:, invited_by:, role: nil, email_template: nil)
+          # Cancel any existing pending invite first (association is already scoped to pending)
+          user_invite&.cancelled!
+
+          attrs = {
+            email: email,
+            entity: entity,
+            invited_by: invited_by,
+            email_template: email_template
+          }
+          attrs[:role] = role if role.present?
+
+          create_user_invite!(attrs)
+        end
+
+        # Check if there's an active pending invite.
+        #
+        # @return [Boolean] true if there's a pending invite
+        def has_pending_invite?
+          user_invite.present?
+        end
+
+        # Check if this invitable can receive an invitation.
+        #
+        # Override this method to customize the logic. The default implementation
+        # returns true if no user is attached and no pending invite exists.
+        #
+        # @return [Boolean] true if invitation can be sent
+        def can_invite_user?
+          !user.present? && !has_pending_invite?
+        end
+
+        # Called when the invited user accepts and joins the entity.
+        #
+        # Override this method in your model to handle the acceptance,
+        # typically to connect the invitable to the user.
+        #
+        # @param user [Object] the user who accepted the invite
+        # @raise [NotImplementedError] if not overridden
+        def on_invite_accepted(user)
+          raise NotImplementedError, "#{self.class.name} must implement #on_invite_accepted(user)"
+        end
+      end
+    end
+  end
+end