plutonium 0.39.2 → 0.40.0

data/docs/reference/generators/index.md

@@ -87,6 +87,13 @@ rails generate pu:res:conn Post --dest=admin_portal
 
 Creates portal-specific controller, definition, and policy (if needed) and registers the resource in the portal routes.
 
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--dest NAME` | Destination portal (prompted if not provided) |
+| `--singular` | Register as a singular resource (e.g., profile, dashboard) |
+
 #### Examples
 
 ```bash
@@ -96,6 +103,9 @@ rails generate pu:res:conn Post --dest=admin_portal
 # Connect multiple resources
 rails generate pu:res:conn Post Comment --dest=admin_portal
 
+# Connect a singular resource
+rails generate pu:res:conn Profile --dest=customer_portal --singular
+
 # Interactive mode (prompts for resource and portal)
 rails generate pu:res:conn
 ```
@@ -152,6 +162,7 @@ rails generate pu:pkg:portal admin
 | `--auth NAME` | Rodauth account to authenticate with (e.g., `--auth=user`) |
 | `--public` | Grant public access (no authentication) |
 | `--byo` | Bring your own authentication |
+| `--scope CLASS` | Entity class to scope to for multi-tenancy (e.g., `--scope=Organization`) |
 
 #### Examples
 
@@ -167,6 +178,9 @@ rails generate pu:pkg:portal api --public
 
 # Bring your own authentication
 rails generate pu:pkg:portal custom --byo
+
+# With entity scoping (multi-tenancy)
+rails generate pu:pkg:portal admin --auth=admin --scope=Organization
 ```
 
 Without flags, the generator prompts for authentication configuration:
@@ -182,6 +196,7 @@ packages/admin_portal/
 │   ├── controllers/admin_portal/
 │   │   ├── concerns/controller.rb
 │   │   ├── plutonium_controller.rb
+│   │   ├── resource_controller.rb
 │   │   └── dashboard_controller.rb
 │   ├── definitions/admin_portal/
 │   ├── policies/admin_portal/
@@ -309,20 +324,65 @@ Creates a rake task for account creation:
 rails rodauth_admin:create[admin@example.com,password123]
 ```
 
-### pu:rodauth:customer
+## SaaS Generators
 
-Generate a customer account with entity (organization) association.
+### pu:saas:setup
+
+Generate a complete multi-tenant SaaS setup with user, entity, and membership.
 
 ```bash
-rails generate pu:rodauth:customer customer
-rails generate pu:rodauth:customer customer --entity=Organization
+rails generate pu:saas:setup --user Customer --entity Organization
+rails generate pu:saas:setup --user Customer --entity Organization --roles=member,admin,owner
+rails generate pu:saas:setup --user Customer --entity Organization --no-allow-signup
 ```
 
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--user NAME` | User account model name (required) |
+| `--entity NAME` | 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 |
+
 Creates:
-- Customer account model
-- Entity model (default: "Entity")
-- Membership join model
-- Has-many-through associations
+- User account model with Rodauth authentication
+- Entity model with unique name
+- Membership join model with role enum
+- Has-many-through associations with `dependent: :destroy`
+
+### pu:saas:user
+
+Generate just a SaaS user account.
+
+```bash
+rails generate pu:saas:user Customer
+rails generate pu:saas:user Customer --no-allow-signup
+rails generate pu:saas:user Customer --extra-attributes=name:string
+```
+
+### pu:saas:entity
+
+Generate just an entity model.
+
+```bash
+rails generate pu:saas:entity Organization
+rails generate pu:saas:entity Organization --extra-attributes=slug:string
+```
+
+### pu:saas:membership
+
+Generate just a membership model (requires user and entity to exist).
+
+```bash
+rails generate pu:saas:membership --user Customer --entity Organization
+rails generate pu:saas:membership --user Customer --entity Organization --roles=member,admin,owner
+```
 
 ## Core Generators
 
@@ -423,8 +483,8 @@ rails db:migrate
 ### Adding a New Portal
 
 ```bash
-# Create customer account type
-rails generate pu:rodauth:customer customer
+# Create SaaS setup (user + entity + membership)
+rails generate pu:saas:setup --user Customer --entity Organization
 
 # Create portal
 rails generate pu:pkg:portal customer

data/docs/reference/portal/index.md

@@ -23,12 +23,16 @@ rails generate pu:pkg:portal admin
 | `--auth NAME` | Rodauth account to authenticate with (e.g., `--auth=user`) |
 | `--public` | Grant public access (no authentication) |
 | `--byo` | Bring your own authentication |
+| `--scope CLASS` | Entity class to scope to for multi-tenancy (e.g., `--scope=Organization`) |
 
 ```bash
 # Non-interactive examples
 rails generate pu:pkg:portal admin --auth=admin
 rails generate pu:pkg:portal api --public
 rails generate pu:pkg:portal custom --byo
+
+# With entity scoping (multi-tenancy)
+rails generate pu:pkg:portal admin --auth=admin --scope=Organization
 ```
 
 Without flags, the generator prompts interactively for authentication choice.
@@ -174,27 +178,34 @@ end
 
 ## Controllers
 
-### Resource Controllers
+### Base Controller
 
-Portal-specific controllers inherit from the feature package's controller and include the portal's controller concern:
+```ruby
+# packages/admin_portal/app/controllers/admin_portal/resource_controller.rb
+module AdminPortal
+  class ResourceController < ::ResourceController
+    include AdminPortal::Concerns::Controller
+  end
+end
+```
+
+### Resource Controllers
 
 ```ruby
 # packages/admin_portal/app/controllers/admin_portal/posts_controller.rb
-class AdminPortal::PostsController < ::PostsController
-  include AdminPortal::Concerns::Controller
-
-  private
+module AdminPortal
+  class PostsController < ResourceController
+    private
 
-  def build_resource
-    super.tap do |post|
-      post.user = current_user
+    def build_resource
+      super.tap do |post|
+        post.user = current_user
+      end
     end
   end
 end
 ```
 
-Controllers are auto-created if not defined. When accessing `AdminPortal::PostsController`, Plutonium will dynamically create it by inheriting from `::PostsController` and including `AdminPortal::Concerns::Controller`.
-
 ## Portal-Specific Overrides
 
 ### Definitions

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.39.0)
+    plutonium (0.39.2)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 9.0)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.39.0)
+    plutonium (0.39.2)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 9.0)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.39.0)
+    plutonium (0.39.2)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 9.0)

data/lib/generators/pu/gem/active_shrine/active_shrine_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../../lib/plutonium_generators"
+
+module Pu
+  module Gem
+    class ActiveShrineGenerator < Rails::Generators::Base
+      include PlutoniumGenerators::Generator
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Set up active_shrine for file uploads"
+
+      class_option :s3, type: :boolean, default: false,
+        desc: "Configure S3 storage (adds aws-sdk-s3 gem)"
+      class_option :store_dimensions, type: :boolean, default: false,
+        desc: "Enable image dimension storage (adds fastimage gem)"
+
+      def start
+        bundle "active_shrine"
+        bundle "aws-sdk-s3" if options[:s3]
+        bundle "fastimage" if options[:store_dimensions]
+
+        generate "active_shrine:install"
+        template "config/initializers/shrine.rb", force: true
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+    end
+  end
+end

data/lib/generators/pu/gem/active_shrine/templates/config/initializers/shrine.rb.tt

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "shrine"
+<%- if options[:s3] -%>
+require "shrine/storage/s3"
+<%- else -%>
+require "shrine/storage/file_system"
+<%- end -%>
+
+Shrine.logger = Rails.logger
+
+<%- if options[:s3] -%>
+s3_options = {
+  bucket: ENV.fetch("S3_BUCKET"),
+  region: ENV.fetch("AWS_REGION", "us-east-1"),
+  access_key_id: ENV.fetch("AWS_ACCESS_KEY_ID"),
+  secret_access_key: ENV.fetch("AWS_SECRET_ACCESS_KEY")
+}
+
+Shrine.storages = {
+  cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
+  store: Shrine::Storage::S3.new(**s3_options)
+}
+<%- else -%>
+Shrine.storages = {
+  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"), # temporary
+  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads") # permanent
+}
+<%- end -%>
+
+Shrine.plugin :activerecord
+Shrine.plugin :determine_mime_type, analyzer: lambda { |io, analyzers|
+  mime_type = analyzers[:marcel].call(io)
+  mime_type = analyzers[:file].call(io) if mime_type == "application/octet-stream" || mime_type.nil?
+  mime_type = analyzers[:mime_types].call(io) if mime_type == "text/plain"
+  mime_type
+}
+Shrine.plugin :instrumentation
+Shrine.plugin :infer_extension, force: true
+<%- if options[:store_dimensions] -%>
+Shrine.plugin :store_dimensions
+<%- end -%>
+Shrine.plugin :pretty_location
+Shrine.plugin :refresh_metadata
+Shrine.plugin :remove_invalid
+
+Shrine.plugin :backgrounding
+
+Shrine::Attacher.promote_block do
+  PromoteShrineAttachmentJob.perform_later(self.class.name, record.class.name, record.id, record.record_type, name.to_s, file_data)
+end
+
+Shrine::Attacher.destroy_block do
+  DestroyShrineAttachmentJob.perform_later(self.class.name, record.record_type, data)
+end
+
+Shrine.plugin :upload_endpoint, url: true
+Shrine.plugin :derivatives, create_on_promote: true

data/lib/generators/pu/gem/annotated/templates/lib/tasks/auto_annotate_models.rake

@@ -3,7 +3,12 @@
 # NOTE: to have a dev-mode tool do its thing in production.
 return unless Rails.env.development?
 
-require "annotated"
+begin
+  require "annotated"
+rescue LoadError
+  return
+end
+
 task :set_annotation_options do
   # You can override any of these by setting an environment variable of the
   # same name.

data/lib/generators/pu/gem/dotenv/templates/config/initializers/001_ensure_required_env.rb

@@ -1,5 +1,8 @@
 return if ENV["SECRET_KEY_BASE_DUMMY"].present?
 
+# In development/test, only check if dotenv is loaded (process may not have reloaded yet)
+return if Rails.env.local? && !defined?(Dotenv)
+
 # Add required env vars to this list
 required_env_vars = %w[
   RAILS_DEFAULT_URL

data/lib/generators/pu/invites/USAGE

@@ -0,0 +1,27 @@
+Description:
+    Install user invites package with all required files.
+
+Example:
+    rails g pu:invites:install
+
+    This will create a packages/invites/ package with:
+        packages/invites/app/models/invites/user_invite.rb
+        packages/invites/app/mailers/invites/user_invite_mailer.rb
+        packages/invites/app/controllers/invites/user_invitations_controller.rb
+        packages/invites/app/views/invites/...
+        packages/invites/app/interactions/invites/resend_invite_interaction.rb
+        packages/invites/app/definitions/invites/user_invite_definition.rb
+        packages/invites/app/policies/invites/user_invite_policy.rb
+        db/migrate/TIMESTAMP_create_user_invites.rb
+
+Options:
+    --entity-model=NAME       Entity model name for scoping (default: Entity)
+    --user-model=NAME         User model name (default: User)
+    --membership-model=NAME   Membership model name (default: <Entity>User)
+    --roles=ROLES             Comma-separated roles (default: member,admin)
+    --rodauth=NAME            Rodauth configuration for signup (default: user)
+    --enforce-domain          Require user email domain to match entity domain
+
+After installation, use pu:invites:invitable to connect invitables:
+    rails g pu:invites:invitable Tenant
+    rails g pu:invites:invitable TeamMember --role=member