plutonium 0.26.1 → 0.26.2

data/docs/modules/generator.md

@@ -25,9 +25,11 @@ The Generator module is located in `lib/generators/pu/`.
 Sets up the base requirements for a Plutonium application.
 
 ::: code-group
+
 ```bash [Command]
 rails generate pu:core:install
 ```
+
 ```text [Generated Structure]
 config/
 ├── packages.rb          # Package loading configuration
@@ -49,6 +51,7 @@ app/views/
 └── layouts/
     └── resource.html.erb            # Ejected layout for customization
 ```
+
 :::
 
 ### Package Generators
@@ -58,6 +61,7 @@ app/views/
 Creates a complete portal package, which acts as a user-facing entry point to your application, often with its own authentication.
 
 ::: code-group
+
 ```bash [Command]
 # Creates an "admin" portal with authentication
 rails generate pu:pkg:portal admin
@@ -65,6 +69,7 @@ rails generate pu:pkg:portal admin
 # Creates a "customer" portal with public access
 rails generate pu:pkg:portal customer --public
 ```
+
 ```text [Generated Structure]
 packages/admin_portal/
 ├── lib/
@@ -83,6 +88,7 @@ packages/admin_portal/
     └── definitions/
         └── admin_portal/
 ```
+
 ```ruby [Authentication Integration]
 # Automatic Rodauth integration is added to the controller concern
 # packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb
@@ -98,6 +104,7 @@ module AdminPortal
   end
 end
 ```
+
 :::
 
 #### Package Generator (`pu:pkg:package`)
@@ -105,9 +112,11 @@ end
 Creates a standard feature package for encapsulating domain logic.
 
 ::: code-group
+
 ```bash [Command]
 rails generate pu:pkg:package blogging
 ```
+
 ```text [Generated Structure]
 packages/blogging/
 ├── lib/
@@ -124,6 +133,7 @@ packages/blogging/
     └── interactions/
         └── blogging/
 ```
+
 :::
 
 ### Resource Generators
@@ -133,10 +143,12 @@ packages/blogging/
 Creates a complete resource with a model, controller, policy, and definition, including full CRUD operations.
 
 ::: code-group
+
 ```bash [Command]
 # Generate a new resource with attributes, placing it in the 'blogging' package
 rails generate pu:res:scaffold Post title:string content:text author:references published:boolean --dest=blogging
 ```
+
 ```ruby [Generated Model]
 # packages/blogging/app/models/blogging/post.rb
 class Blogging::Post < Blogging::ResourceRecord
@@ -146,6 +158,7 @@ class Blogging::Post < Blogging::ResourceRecord
   validates :content, presence: true
 end
 ```
+
 ```ruby [Generated Policy]
 # packages/blogging/app/policies/blogging/post_policy.rb
 class Blogging::PostPolicy < Blogging B::ResourcePolicy
@@ -158,6 +171,7 @@ class Blogging::PostPolicy < Blogging B::ResourcePolicy
   end
 end
 ```
+
 ```ruby [Generated Definition]
 # packages/blogging/app/definitions/blogging/post_definition.rb
 class Blogging::PostDefinition < Blogging::ResourceDefinition
@@ -172,19 +186,80 @@ class Blogging::PostDefinition < Blogging::ResourceDefinition
   filter :author, with: :select
 end
 ```
+
 :::
 
 ### Authentication Generators
 
+#### Rodauth Customer Generator (`pu:rodauth:customer`)
+
+Easily add multitenancy and SaaS-ready authentication to your Plutonium app. This generator creates a customer-oriented Rodauth account, an entity model, and a membership join model, wiring up all necessary relationships for multi-tenant architectures.
+
+> **Note:** If you omit the `--entity` parameter, the entity name will default to `Entity` and the join relation will be `EntityCustomer`. **It is strongly recommended to always provide a meaningful entity name using `--entity=YourEntityName` to ensure clarity and proper model relationships in your application.**
+
+> **Option:** `--allow-signup` determines whether the customer user is allowed to sign up on the platform. If not allowed, new customer accounts will typically be created by platform admins and users notified. Use `--no-allow-signup` to restrict self-signup.
+
+::: code-group
+
+```bash [Command]
+rails generate pu:rodauth:customer Customer --entity=Organization
+```
+
+```text [Generated Structure]
+app/
+├── models/
+│   ├── customer.rb
+│   ├── organization.rb
+│   └── organization_customer.rb
+└── rodauth/
+    ├── customer_rodauth.rb
+    └── customer_rodauth_plugin.rb
+db/
+└── migrate/
+    ├── ..._create_customers.rb
+    ├── ..._create_organizations.rb
+    └── ..._create_organization_customers.rb
+```
+
+```ruby [Generated Models]
+# app/models/organization.rb
+class Organization < ::ResourceRecord
+  has_many :organization_customers
+  has_many :customers, through: :organization_customers
+end
+
+# app/models/customer.rb
+class Customer < ResourceRecord
+  include Rodauth::Rails.model(:customer)
+
+  has_many :organization_customers
+  has_many :organizations, through: :organization_customers
+end
+
+# app/models/organization_customer.rb
+class OrganizationCustomer < ::ResourceRecord
+
+  belongs_to :organization
+  belongs_to :customer
+  enum role: { member: 0, admin: 1 }
+end
+```
+
+:::
+
+> **Note:** If you already have a customer user model and want to add an entity (for example, as your project evolves into a SaaS), use the Entity Resource Generator below to generate just the entity and membership join model.
+
 #### Rodauth Account Generator (`pu:rodauth:account`)
 
 Generates the necessary files for a Rodauth authentication setup for a given account type.
 
 ::: code-group
+
 ```bash [Command]
 # Generate a 'user' account with common features
 rails generate pu:rodauth:account user --features login logout create-account verify-account reset-password remember
 ```
+
 ```text [Generated Structure]
 app/
 ├── controllers/
@@ -201,6 +276,7 @@ db/
 └── migrate/
     └── ..._create_users.rb
 ```
+
 :::
 
 #### Rodauth Admin Generator (`pu:rodauth:admin`)
@@ -208,9 +284,11 @@ db/
 A specialized generator for creating a secure admin account with enhanced features like MFA and audit logging.
 
 ::: code-group
+
 ```bash [Command]
 rails generate pu:rodauth:admin admin
 ```
+
 ```ruby [Generated Plugin]
 # app/rodauth/admin_rodauth_plugin.rb
 class AdminRodauthPlugin < RodauthPlugin
@@ -224,6 +302,40 @@ class AdminRodauthPlugin < RodauthPlugin
   end
 end
 ```
+
+:::
+
+### Entity Resource Generator (`pu:res:entity`)
+
+Creates an entity model and a membership join model for associating customers with entities. Use this if you already have a customer model and want to add multitenancy or evolve your project into a SaaS platform.
+
+::: code-group
+
+```bash [Command]
+rails generate pu:res:entity Organization --auth-account=Customer
+```
+
+```text [Generated Structure]
+app/
+├── models/
+│   ├── organization.rb
+│   └── organization_customer.rb
+db/
+└── migrate/
+    ├── ..._create_organizations.rb
+    └── ..._create_organization_customers.rb
+```
+
+```ruby [Generated Membership Model]
+# app/models/organization_customer.rb
+class OrganizationCustomer < ResourceRecord
+  belongs_to :organization
+  belongs_to :customer
+
+  enum role: { member: 0, admin: 1 } # not added by default
+end
+```
+
 :::
 
 ### Ejection Generators

data/lib/generators/pu/res/entity/entity_generator.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+require_relative "../../lib/plutonium_generators"
+
+module Pu
+  module Res
+    class EntityGenerator < ::Rails::Generators::NamedBase
+      include PlutoniumGenerators::Generator
+
+      desc "Generate an entity model for customer accounts"
+
+      class_option :model, type: :boolean, default: true
+      class_option :allow_signup, type: :boolean, default: true,
+        desc: "Whether to allow customer to sign up to the platform"
+      class_option :auth_account, type: :string,
+        desc: "Specify the authentication account name", required: true
+
+      def start
+        ensure_customer_model_exists! if behavior == :invoke
+        generate_entity_resource
+        generate_membership_resource
+      end
+
+      private
+
+      def ensure_customer_model_exists!
+        customer_model_path = File.join("app", "models", "#{normalized_auth_account_name}.rb")
+        unless File.exist?(customer_model_path)
+          raise "Customer model '#{normalized_auth_account_name}' does not exist. Please create it first."
+        end
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+
+      def generate_entity_resource
+        Rails::Generators.invoke(
+          "pu:res:scaffold",
+          [
+            normalized_name,
+            "name:string",
+            "--model",
+            ("--force" if options[:force]),
+            ("--skip" if options[:skip]),
+            "--dest=#{selected_destination_feature}"
+          ].compact,
+          behavior: behavior,
+          destination_root: destination_root
+        )
+
+        add_unique_index_to_migration(normalized_name, [:name])
+      end
+
+      def generate_membership_resource
+        Rails::Generators.invoke(
+          "pu:res:scaffold",
+          [
+            normalized_entity_membership_name,
+            *membership_attributes,
+            "--model",
+            ("--force" if options[:force]),
+            ("--skip" if options[:skip]),
+            "--dest=#{selected_destination_feature}"
+          ].compact,
+          behavior: behavior,
+          destination_root: destination_root
+        )
+
+        add_unique_index_to_migration(
+          normalized_entity_membership_name,
+          ["#{normalized_name}_id", "#{normalized_auth_account_name}_id"]
+        )
+      end
+
+      private
+
+      def selected_destination_feature = "main_app"
+
+      def normalized_name = name.underscore
+
+      def normalized_entity_membership_name
+        "#{normalized_name}_#{normalized_auth_account_name}"
+      end
+
+      def normalized_auth_account_name = options[:auth_account].underscore
+
+      def add_unique_index_to_migration(model_name, index_columns)
+        migration_dir = File.join("db", "migrate")
+        migration_file = Dir[File.join(migration_dir, "*_create_#{model_name.pluralize}.rb")].first
+
+        if migration_file && File.exist?(migration_file)
+          index_definition = build_index_definition(model_name, index_columns)
+          insert_into_file migration_file, indent(index_definition, 4), before: /^  end\s*$/
+          success "Added unique index to #{model_name.pluralize}"
+        end
+      end
+
+      def build_index_definition(model_name, index_columns)
+        table_name = model_name.pluralize
+
+        case index_columns
+        when Array
+          if index_columns.size == 1
+            "add_index :#{table_name}, :#{index_columns.first}, unique: true\n"
+          else
+            column_list = index_columns.map { |col| ":#{col}" }.join(", ")
+            "add_index :#{table_name}, [#{column_list}], unique: true\n"
+          end
+        else
+          "add_index :#{table_name}, :#{index_columns}, unique: true\n"
+        end
+      end
+
+      def membership_attributes
+        [
+          "#{normalized_name}:references",
+          "#{normalized_auth_account_name}:references",
+          "role:integer"
+        ]
+      end
+    end
+  end
+end

data/lib/generators/pu/rodauth/customer_generator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+return unless defined?(Rodauth::Rails)
+
+require "rails/generators/named_base"
+require_relative "../lib/plutonium_generators"
+
+module Pu
+  module Rodauth
+    class CustomerGenerator < ::Rails::Generators::NamedBase
+      include PlutoniumGenerators::Concerns::Logger
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generate a rodauth-rails account optimized for customer-based tasks"
+
+      class_option :allow_signup, type: :boolean, default: true,
+        desc: "Whether to allow customer to sign up to the platform"
+
+      class_option :entity, default: "Entity",
+        desc: "Generate an entity model for customer accounts. Defaults to 'Entity'",
+        aliases: ["--entity", "-e"]
+
+      def start
+        create_customer_account
+        create_entity_model_and_membership
+        configure_model_relationships
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+
+      private
+
+      def create_customer_account
+        invoke "pu:rodauth:account", [name],
+          defaults: false,
+          **customer_features,
+          force: options[:force],
+          skip: options[:skip],
+          lint: true
+      end
+
+      def create_entity_model_and_membership
+        invoke "pu:res:entity", [normalized_entity_name],
+          auth_account: normalized_name,
+          force: options[:force],
+          skip: options[:skip]
+      end
+
+      def configure_model_relationships
+        entity_model_path = File.join("app", "models", "#{normalized_entity_name}.rb")
+        if File.exist?(entity_model_path)
+          insert_into_file entity_model_path, <<~RUBY + "  ", before: /# add has_many associations above\.\n/
+            has_many :#{normalized_entity_membership_name.pluralize}
+              has_many :#{normalized_name.pluralize}, through: :#{normalized_entity_membership_name.pluralize}
+          RUBY
+          success "Added relationship to #{normalized_entity_name} model"
+        end
+
+        customer_model_path = File.join("app", "models", "#{normalized_name}.rb")
+        if File.exist?(customer_model_path)
+          insert_into_file customer_model_path, <<~RUBY + "  ", before: /# add has_many associations above\.\n/
+            has_many :#{normalized_entity_membership_name.pluralize}
+              has_many :#{normalized_entity_name.pluralize}, through: :#{normalized_entity_membership_name.pluralize}
+          RUBY
+          success "Added relationship to #{normalized_name} model"
+        end
+      end
+
+      private
+
+      def customer_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
+
+      def normalized_entity_name = options[:entity].underscore
+
+      def normalized_entity_membership_name
+        "#{normalized_entity_name.underscore}_#{normalized_name}"
+      end
+    end
+  end
+end

data/lib/plutonium/interaction/response/redirect.rb

@@ -12,16 +12,25 @@ module Plutonium
         # @param controller [ActionController::Base] The controller instance.
         # @return [void]
         def execute(controller)
+          # Capture the instance variables before entering instance_eval
+          redirect_args = @args
+          redirect_options = @options
+
           controller.instance_eval do
-            url = url_for(*@args)
+            url = url_for(*redirect_args)
 
-            format.any { redirect_to(url, **@options) }
-            if helpers.current_turbo_frame == "remote_modal"
+            respond_to do |format|
               format.turbo_stream do
-                render turbo_stream: [
-                  helpers.turbo_stream_redirect(url)
-                ]
+                if helpers.current_turbo_frame == "remote_modal"
+                  render turbo_stream: [
+                    helpers.turbo_stream_redirect(url)
+                  ]
+                else
+                  redirect_to(url, **redirect_options)
+                end
               end
+
+              format.any { redirect_to(url, **redirect_options) }
             end
           end
         end

data/lib/plutonium/version.rb

@@ -1,5 +1,5 @@
 module Plutonium
-  VERSION = "0.26.1"
+  VERSION = "0.26.2"
   NEXT_MAJOR_VERSION = VERSION.split(".").tap { |v|
     v[1] = v[1].to_i + 1
     v[2] = 0