plutonium 0.43.2 → 0.44.1

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require_relative "../lib/plutonium_generators"
+
+module Pu
+  module Saas
+    class PortalGenerator < ::Rails::Generators::Base
+      include PlutoniumGenerators::Generator
+
+      desc "Generate a SaaS portal with entity scoping, entity management, and navigation helpers"
+
+      class_option :entity_model, type: :string, required: true,
+        desc: "The entity model name (e.g., Organization)"
+
+      class_option :user_model, type: :string, default: "User",
+        desc: "The user model name"
+
+      class_option :portal_name, type: :string, default: "Dashboard",
+        desc: "Portal name (e.g., Dashboard generates DashboardPortal)"
+
+      class_option :rodauth, type: :string, default: "user",
+        desc: "Rodauth configuration name"
+
+      def start
+        create_portal
+        connect_entity_to_portal
+        customize_entity_policy
+        add_entity_url_helper
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+
+      private
+
+      def create_portal
+        generate "pu:pkg:portal", "#{options[:portal_name]} --auth=#{rodauth_config} --scope=#{entity_model}"
+      end
+
+      def connect_entity_to_portal
+        # Shell out so the subprocess can load the newly created entity model
+        generate "pu:res:conn", "#{entity_model} --dest=#{portal_package} --singular --policy"
+      end
+
+      def customize_entity_policy
+        content = <<-RUBY
+
+  def update?
+    current_membership&.owner?
+  end
+
+  def destroy?
+    false
+  end
+
+  def permitted_attributes_for_read
+    [:name]
+  end
+
+  def permitted_attributes_for_update
+    [:name]
+  end
+
+  def permitted_associations
+    []
+  end
+        RUBY
+        inject_into_file entity_policy_path, content, after: /include #{portal_engine}::ResourcePolicy\n/
+      end
+
+      def add_entity_url_helper
+        content = <<-RUBY
+
+      included do
+        helper_method :entity_url, :user_entities
+      end
+
+      private
+
+      # Returns the URL to the current entity's show page.
+      def entity_url
+        resource_url_for(current_scoped_entity)
+      end
+
+      # Returns all entities the current user belongs to (for the entity switcher).
+      def user_entities
+        @user_entities ||= current_user.#{entity_table.pluralize}
+      end
+        RUBY
+        inject_into_file concerns_controller_path, content, after: /# add concerns above\.\n/
+      end
+
+      def entity_model
+        options[:entity_model].camelize
+      end
+
+      def entity_table
+        options[:entity_model].underscore
+      end
+
+      def rodauth_config
+        options[:rodauth]
+      end
+
+      def portal_engine
+        "#{options[:portal_name].camelize}Portal"
+      end
+
+      def portal_package
+        portal_engine.underscore
+      end
+
+      def concerns_controller_path
+        "packages/#{portal_package}/app/controllers/#{portal_package}/concerns/controller.rb"
+      end
+
+      def entity_policy_path
+        "packages/#{portal_package}/app/policies/#{portal_package}/#{entity_table}_policy.rb"
+      end
+    end
+  end
+end

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

@@ -1,27 +1,22 @@
 Description:
-    Generate a complete SaaS setup with user account, entity, and membership.
-    This is the recommended way to set up multi-tenant authentication.
+    Generate a complete SaaS setup with user account, entity, membership,
+    portal, welcome flow, invites, and profile.
+
+    This is the recommended way to bootstrap a multi-tenant SaaS app.
 
 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
+    rails g pu:saas:setup --user=User --entity=Organization
 
-    This creates:
-        1. User account (Customer) with Rodauth authentication
-        2. Entity model (Organization) with unique name
-        3. Membership model (OrganizationCustomer) with role enum
+    Full setup with all defaults:
+      - User model with Rodauth authentication
+      - Entity model with unique name and dynamic path parameter
+      - Membership model with owner/admin/member roles
+      - DashboardPortal with entity scoping
+      - Welcome/onboarding flow
+      - User invites package
+      - User profile resource
 
-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)
+    Customize:
+    rails g pu:saas:setup --user=User --entity=Organization --portal-name=Customer
+    rails g pu:saas:setup --user=User --entity=Organization --no-invites --no-profile
+    rails g pu:saas:setup --user=User --entity=Organization --no-portal

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

@@ -8,10 +8,10 @@ module Pu
     class SetupGenerator < ::Rails::Generators::Base
       include PlutoniumGenerators::Generator
 
-      desc "Generate a complete SaaS setup with user, entity, and membership"
+      desc "Generate a complete SaaS setup with user, entity, membership, portal, and welcome flow"
 
       class_option :user, type: :string, required: true,
-        desc: "The user model name (e.g., Customer)"
+        desc: "The user model name (e.g., User)"
 
       class_option :entity, type: :string, required: true,
         desc: "The entity model name (e.g., Organization)"
@@ -19,8 +19,8 @@ module Pu
       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 :roles, type: :array, default: %w[admin member],
+        desc: "Additional roles for memberships (owner is always included as the first role)"
 
       class_option :skip_entity, type: :boolean, default: false,
         desc: "Skip entity model generation"
@@ -37,6 +37,21 @@ module Pu
       class_option :membership_attributes, type: :array, default: [],
         desc: "Additional attributes for the membership model"
 
+      class_option :portal, type: :boolean, default: true,
+        desc: "Generate a portal with entity scoping"
+
+      class_option :portal_name, type: :string, default: "Dashboard",
+        desc: "Portal name (e.g., Dashboard generates DashboardPortal)"
+
+      class_option :welcome, type: :boolean, default: true,
+        desc: "Generate the welcome/onboarding flow"
+
+      class_option :invites, type: :boolean, default: true,
+        desc: "Generate the user invites package"
+
+      class_option :profile, type: :boolean, default: true,
+        desc: "Generate user profile resource"
+
       class_option :api_client, type: :string, default: nil,
         desc: "Generate an API client model (e.g., ApiClient)"
 
@@ -48,6 +63,10 @@ module Pu
         generate_user
         generate_entity unless options[:skip_entity]
         generate_membership unless options[:skip_membership]
+        generate_portal if options[:portal] && !options[:skip_entity]
+        generate_profile if options[:profile]
+        generate_welcome if options[:welcome] && !options[:skip_entity] && options[:portal]
+        generate_invites if options[:invites] && !options[:skip_entity] && !options[:skip_membership]
         generate_api_client if options[:api_client].present?
       rescue => e
         exception "#{self.class} failed:", e
@@ -62,7 +81,6 @@ module Pu
       end
 
       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]],
@@ -76,7 +94,6 @@ module Pu
       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]],
@@ -90,7 +107,6 @@ module Pu
       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(
           [],
@@ -106,8 +122,34 @@ module Pu
         ).invoke_all
       end
 
+      def generate_portal
+        generate "pu:saas:portal",
+          "--entity-model=#{options[:entity]} --user-model=#{options[:user]}" \
+          " --portal-name=#{options[:portal_name]}" \
+          " --rodauth=#{rodauth_config}"
+      end
+
+      def generate_profile
+        generate "pu:profile:setup",
+          "--user-model=#{options[:user]} --dest=main_app" \
+          "#{" --portal=#{portal_package}" if options[:portal]}"
+      end
+
+      def generate_welcome
+        generate "pu:saas:welcome",
+          "--user-model=#{options[:user]} --entity-model=#{options[:entity]}" \
+          " --portal=#{portal_engine}" \
+          " --rodauth=#{rodauth_config}" \
+          "#{" --profile" if options[:profile]}"
+      end
+
+      def generate_invites
+        generate "pu:invites:install",
+          "--entity-model=#{options[:entity]} --user-model=#{options[:user]} --dest=main_app" \
+          " --rodauth=#{rodauth_config}"
+      end
+
       def generate_api_client
-        # Use class-based invocation to avoid Thor's invoke caching
         klass = Rails::Generators.find_by_namespace("pu:saas:api_client")
         api_client_options = {
           roles: options[:api_client_roles],
@@ -116,11 +158,22 @@ module Pu
           skip: options[:skip]
         }
 
-        # Scope to entity if entity is being generated
         api_client_options[:entity] = options[:entity] unless options[:skip_entity]
 
         klass.new([options[:api_client]], api_client_options).invoke_all
       end
+
+      def rodauth_config
+        options[:user].underscore
+      end
+
+      def portal_package
+        "#{options[:portal_name].underscore}_portal"
+      end
+
+      def portal_engine
+        "#{options[:portal_name].camelize}Portal"
+      end
     end
   end
 end

data/lib/generators/pu/saas/welcome/USAGE

@@ -0,0 +1,27 @@
+Description:
+  Generates a post-login welcome flow with onboarding and entity selection.
+
+  This creates the controllers, views, and routes needed to bridge
+  authentication and the main portal:
+
+  - AuthenticatedController: base controller requiring login
+  - WelcomeController: routing hub (invite check -> onboarding -> entity selection -> portal)
+  - Onboarding view: create first entity (and optional profile)
+  - Entity selection view: choose from multiple entities
+
+Example:
+  rails g pu:saas:welcome --user-model=User --entity-model=Organization --portal=CustomerPortal
+
+  This generates:
+    app/controllers/authenticated_controller.rb
+    app/controllers/welcome_controller.rb
+    app/views/welcome/onboarding.html.erb
+    app/views/welcome/select_entity.html.erb
+
+  And adds routes:
+    GET  /welcome         -> welcome#index
+    GET  /welcome/onboard -> welcome#new_entity
+    POST /welcome/onboard -> welcome#onboard
+
+Options:
+  --profile  Include profile setup in onboarding form

data/lib/generators/pu/saas/welcome/templates/app/controllers/authenticated_controller.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class AuthenticatedController < ApplicationController
+<% if rodauth? -%>
+  include Plutonium::Auth::Rodauth(:<%= rodauth_config %>)
+
+  before_action { rodauth.require_authentication }
+<% else -%>
+  before_action :require_authenticated
+
+  private
+
+  def require_authenticated
+    # TODO: Implement based on your authentication system
+    redirect_to "/login" unless current_user
+  end
+<% end -%>
+end

data/lib/generators/pu/saas/welcome/templates/app/controllers/welcome_controller.rb.tt

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+class WelcomeController < AuthenticatedController
+  layout "welcome"
+
+  def index
+    entities = current_user.<%= entity_table.pluralize %>.to_a
+    if entities.none?
+      @<%= entity_table %> = <%= entity_model %>.new
+<% if profile? -%>
+      @profile = current_user.profile || current_user.build_profile
+<% end -%>
+      render :onboarding
+    elsif entities.one?
+      redirect_to portal_root_path(entities.first)
+    else
+      @entities = entities
+      render :select_entity
+    end
+  end
+
+  def new_entity
+    @<%= entity_table %> = <%= entity_model %>.new
+<% if profile? -%>
+    @profile = current_user.profile || current_user.build_profile
+<% end -%>
+    render :onboarding
+  end
+
+  def onboard
+    @<%= entity_table %> = <%= entity_model %>.new(<%= entity_table %>_params)
+<% if profile? -%>
+    @profile = current_user.profile || current_user.build_profile
+    @profile.assign_attributes(profile_params)
+
+    if @<%= entity_table %>.valid? && @profile.valid?
+<% else -%>
+    if @<%= entity_table %>.valid?
+<% end -%>
+      ActiveRecord::Base.transaction do
+        @<%= entity_table %>.save!
+        <%= membership_model %>.create!(<%= entity_table %>: @<%= entity_table %>, <%= user_table %>: current_user, role: :owner)
+<% if profile? -%>
+        @profile.save!
+<% end -%>
+      end
+      redirect_to portal_root_path(@<%= entity_table %>), notice: "Welcome! Your workspace is ready."
+    else
+      render :onboarding, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def <%= entity_table %>_params
+    params.require(:<%= entity_table %>).permit(:name)
+  end
+<% if profile? -%>
+
+  def profile_params
+    params.require(:profile).permit(:name)
+  end
+<% end -%>
+
+  def portal_root_path(<%= entity_table %>)
+    <%= portal_engine %>::Engine.routes.url_helpers.<%= entity_table %>_root_path(<%= entity_table %>: <%= entity_table %>)
+  end
+  helper_method :portal_root_path
+end

data/lib/generators/pu/saas/welcome/templates/app/views/layouts/welcome.html.erb.tt

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Welcome</title>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <meta name="csrf-param" content="authenticity_token" />
+  <meta name="csrf-token" content="<%%= form_authenticity_token %>" />
+  <%%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
+  <%%= javascript_importmap_tags %>
+</head>
+<body class="antialiased min-h-screen bg-[var(--pu-body)]">
+  <main class="p-4 min-h-screen flex flex-col items-center justify-center gap-2 px-6 py-8 mx-auto lg:py-0">
+    <%% if flash.any? %>
+      <%% flash.each do |type, message| %>
+        <div class="fixed z-50 top-16 inset-x-0 mx-auto flex items-center w-full max-w-md p-4 rounded-[var(--pu-radius-lg)]"
+             style="box-shadow: var(--pu-shadow-md); background: <%%= type == 'alert' ? 'var(--color-danger-50)' : 'var(--color-success-50)' %>; color: <%%= type == 'alert' ? 'var(--color-danger-600)' : 'var(--color-success-600)' %>"
+             role="alert">
+          <div class="ms-3 text-sm font-normal"><%%= message %></div>
+        </div>
+      <%% end %>
+    <%% end %>
+
+    <!-- Main content card -->
+    <div class="w-full sm:max-w-md bg-[var(--pu-card-bg)] border border-[var(--pu-card-border)] rounded-[var(--pu-radius-lg)]"
+         style="box-shadow: var(--pu-shadow-lg)">
+      <div class="p-6 space-y-4 md:space-y-6 sm:p-8">
+        <%%= yield %>
+      </div>
+    </div>
+  </main>
+</body>
+</html>

data/lib/generators/pu/saas/welcome/templates/app/views/welcome/onboarding.html.erb.tt

@@ -0,0 +1,51 @@
+<h1 class="text-lg font-bold leading-tight tracking-tight text-[var(--pu-text)] md:text-xl text-center">
+  Welcome! Let's get you set up.
+</h1>
+
+<%%= form_with(url: welcome_onboard_path, method: :post, class: "space-y-4 md:space-y-6") do |f| %>
+<% if profile? -%>
+  <%% if @<%= entity_table %>.errors.any? || @profile.errors.any? %>
+<% else -%>
+  <%% if @<%= entity_table %>.errors.any? %>
+<% end -%>
+    <div class="p-4 rounded-[var(--pu-radius-lg)] bg-[color:var(--color-danger-50)] text-[color:var(--color-danger-600)]">
+      <ul class="list-disc list-inside text-sm">
+        <%% @<%= entity_table %>.errors.full_messages.each do |message| %>
+          <li><%%= message %></li>
+        <%% end %>
+<% if profile? -%>
+        <%% @profile.errors.full_messages.each do |message| %>
+          <li><%%= message %></li>
+        <%% end %>
+<% end -%>
+      </ul>
+    </div>
+  <%% end %>
+<% if profile? -%>
+
+  <%%= f.fields_for :profile, @profile do |pf| %>
+    <div>
+      <%%= pf.label :name, "Your Name", class: "block mb-2 text-sm font-medium text-[var(--pu-text)]" %>
+      <%%= pf.text_field :name,
+          class: "pu-input w-full",
+          placeholder: "e.g. Jane Smith",
+          autofocus: true %>
+    </div>
+  <%% end %>
+<% end -%>
+
+  <%%= f.fields_for :<%= entity_table %>, @<%= entity_table %> do |ef| %>
+    <div>
+      <%%= ef.label :name, "Workspace Name", class: "block mb-2 text-sm font-medium text-[var(--pu-text)]" %>
+      <%%= ef.text_field :name,
+          class: "pu-input w-full",
+          placeholder: "e.g. Acme Corp",
+<% unless profile? -%>
+          autofocus: true,
+<% end -%>
+          required: true %>
+    </div>
+  <%% end %>
+
+  <%%= f.submit "Get Started", class: "w-full pu-btn pu-btn-md pu-btn-primary" %>
+<%% end %>

data/lib/generators/pu/saas/welcome/templates/app/views/welcome/select_entity.html.erb.tt

@@ -0,0 +1,22 @@
+<h1 class="text-lg font-bold leading-tight tracking-tight text-[var(--pu-text)] md:text-xl text-center">
+  Select a Workspace
+</h1>
+
+<div class="space-y-2">
+  <%% @entities.each do |<%= entity_table %>| %>
+    <a href="<%%= portal_root_path(<%= entity_table %>) %>"
+       class="flex items-center gap-3 w-full p-4 text-left bg-[var(--pu-surface-alt)] border border-[var(--pu-border)] rounded-[var(--pu-radius-lg)] hover:border-[var(--color-primary-500)] hover:bg-[var(--pu-surface)] transition-colors">
+      <div class="flex-1">
+        <p class="font-medium text-[var(--pu-text)]"><%%= <%= entity_table %>.name %></p>
+      </div>
+      <%%= render Phlex::TablerIcons::ChevronRight.new(class: "w-5 h-5 text-[var(--pu-text-muted)]") %>
+    </a>
+  <%% end %>
+</div>
+
+<div class="pt-2">
+  <a href="<%%= welcome_onboard_path %>"
+     class="w-full block pu-btn pu-btn-md pu-btn-outline text-center">
+    Create New Workspace
+  </a>
+</div>