plutonium 0.39.1 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1628c890b14f2fb0d7dd1c269d1acd8d96da310c28f990834b0fed1c33d56cc
-  data.tar.gz: 9e181312f1785e4ee5ce1900f4a90fc990f520cecdbc67cb166ff9f8ef7b93fb
+  metadata.gz: ba93910895cf945960fdec47e9ba7026df83718d63e947a68ed4eb78ccd2ff4a
+  data.tar.gz: fbff28e4bfefc0fb86a85ef6e8c5d8272b2669a0048e7e9465c882bcfa1bb07c
 SHA512:
-  metadata.gz: d7de09b2961f9e00b9bf6a5deeac78bfb31ed5f9a249b7ee4c98499da9713fbd6a14422193fee1c26fb20de7fadabbb7233ca7468af997680403bbe6a9ef02b5
-  data.tar.gz: 3859c4fa95f90cfa13f2dfc2cd728ed7013eb5891deaaf65ff3fd90e54fd3d3d9c1336776b223972711111ebb75e7f47d62865a08c98953550ce39254ae2b807
+  metadata.gz: 3c6bf1a8172e6898415f7643e9170e9ca8541980b49346e05a74264b8d19deb94ff3f8b42f5cd1c7a256aa3bb35f112ee542d687b20dfc361a770da5e77b6414
+  data.tar.gz: a70bdce9041d0e729a65f225c4211a97be8c4c97e378b9138079edcd3282a8a33cae73e2f230b9054f2041ba8dffe6035f32aab4e3ae87fb27ba7b8646cb781e

data/.claude/skills/plutonium-connect-resource/SKILL.md

@@ -10,11 +10,18 @@ Use the `pu:res:conn` generator to connect resources to portals. This is require
 ## Command Syntax
 
 ```bash
-rails g pu:res:conn RESOURCE [RESOURCE...] --dest=PORTAL_NAME
+rails g pu:res:conn RESOURCE [RESOURCE...] --dest=PORTAL_NAME [--singular]
 ```
 
 **Always specify resources directly** - this avoids interactive prompts. The `--src` option is only needed for interactive mode and can be ignored.
 
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--dest=NAME` | Target portal package (required) |
+| `--singular` | Register as a singular resource (e.g., profile, dashboard) |
+
 ## Usage Patterns
 
 ### Main App Resources (not in a package)
@@ -39,6 +46,16 @@ rails g pu:res:conn Blogging::Post Blogging::Comment --dest=admin_portal
 rails g pu:res:conn Property PropertyAmenity Unit Tenant --dest=admin_portal
 ```
 
+### Singular Resources
+
+For resources that represent a single record per user (e.g., profile, dashboard, settings):
+
+```bash
+rails g pu:res:conn Profile --dest=customer_portal --singular
+```
+
+This registers the resource with `singular: true`, generating routes like `/profile` instead of `/profiles/:id`.
+
 ## What Gets Generated
 
 For a resource `Post` connected to `admin_portal`:
@@ -89,6 +106,7 @@ end
 ```ruby
 # In packages/admin_portal/config/routes.rb
 register_resource ::Post
+register_resource ::Profile, singular: true  # With --singular
 ```
 
 ## Typical Workflow

data/.claude/skills/plutonium-controller/SKILL.md

@@ -305,23 +305,19 @@ end
 
 ## Portal-Specific Controllers
 
-Each portal can have its own controller override. Portal controllers inherit from the feature package's controller:
+Portal controllers inherit from the feature package's controller if one exists (and include the portal's `Concerns::Controller`). If no feature package controller exists, they inherit from the portal's `ResourceController`.
 
 ```ruby
-# packages/admin_portal/app/controllers/admin_portal/posts_controller.rb
+# With feature package controller:
 class AdminPortal::PostsController < ::PostsController
   include AdminPortal::Concerns::Controller
+end
 
-  private
-
-  def preferred_action_after_submit
-    "index"  # Admin prefers list view
-  end
+# Without feature package controller:
+class AdminPortal::PostsController < AdminPortal::ResourceController
 end
 ```
 
-Controllers are auto-created if not defined. When accessing a portal resource, Plutonium dynamically creates the controller by inheriting from the feature package's controller.
-
 For non-resource portal pages (dashboard, settings), inherit from `PlutoniumController`:
 
 ```ruby

data/.claude/skills/plutonium-definition-query/SKILL.md

@@ -27,6 +27,9 @@ class PostDefinition < ResourceDefinition
   scope :published
   scope :draft
 
+  # Default scope
+  default_scope :published
+
   # Sorting - sortable columns
   sort :title
   sort :created_at
@@ -246,9 +249,11 @@ Set a scope as default to apply it when no scope is explicitly selected:
 
 ```ruby
 class PostDefinition < ResourceDefinition
-  scope :published, default: true  # Applied by default
+  scope :published
   scope :draft
   scope :archived
+
+  default_scope :published  # Applied by default
 end
 ```
 
@@ -329,10 +334,13 @@ class ProductDefinition < ResourceDefinition
   filter :category, with: :association
 
   # Quick scopes
-  scope :active, default: true
+  scope :active
   scope :featured
   scope(:recent) { |scope| scope.where('created_at > ?', 1.week.ago) }
 
+  # Default scope
+  default_scope :active
+
   # Sortable columns
   sorts :name, :price, :created_at
 

data/.claude/skills/plutonium-installation/SKILL.md

@@ -124,10 +124,10 @@ rails generate pu:rodauth:install
 rails generate pu:rodauth:account user
 
 # Admin with 2FA, lockout, audit logging
-rails generate pu:rodauth:admin
+rails generate pu:rodauth:admin admin
 
-# Customer with entity association
-rails generate pu:rodauth:customer customer
+# SaaS user with entity/organization (multi-tenant)
+rails generate pu:saas:setup --user Customer --entity Organization
 ```
 
 ### Account Options
@@ -136,8 +136,7 @@ rails generate pu:rodauth:customer customer
 |--------|-------------|
 | `--defaults` | Enable common features (login, logout, remember, reset_password) |
 | `--kitchen_sink` | Enable all available features |
-| `--no-allow_signup` | Disable public signup |
-| `--entity=Organization` | Create associated entity model |
+| `--no-allow-signup` | Disable public signup |
 
 ### Connect Auth to Controllers
 
@@ -279,8 +278,11 @@ For models that already exist in your app:
 | `pu:core:install` | Initial Plutonium setup |
 | `pu:rodauth:install` | Setup Rodauth authentication |
 | `pu:rodauth:account NAME` | Create user account type |
-| `pu:rodauth:admin` | Create admin account with 2FA |
-| `pu:rodauth:customer NAME` | Create customer with entity |
+| `pu:rodauth:admin NAME` | Create admin account with 2FA |
+| `pu:saas:setup` | Create SaaS user + entity + membership |
+| `pu:saas:user NAME` | Create SaaS user account |
+| `pu:saas:entity NAME` | Create entity model |
+| `pu:saas:membership` | Create membership join table |
 | `pu:pkg:package NAME` | Create feature package |
 | `pu:pkg:portal NAME` | Create portal package |
 | `pu:res:scaffold NAME` | Create resource (model, policy, definition, controller) |

data/.claude/skills/plutonium-invites/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: plutonium-invites
+description: Plutonium user invites - invitation system for multi-tenant apps with entity memberships
+---
+
+# Plutonium User Invites
+
+Plutonium provides a complete user invitation system for multi-tenant applications. The system handles:
+- Sending email invitations to new users
+- Token-based invite acceptance flow
+- Integration with Rodauth authentication
+- Entity membership creation on acceptance
+- Support for invitable models that get notified when invites are accepted
+
+## Installation
+
+### Prerequisites
+
+Before installing invites, ensure you have:
+1. A user model with Rodauth authentication
+2. An entity model (Organization, Company, Team, etc.)
+3. A membership model linking users to entities
+
+Use `pu:saas:setup` to generate all three:
+
+```bash
+rails g pu:saas:setup --user Customer --entity Organization
+```
+
+### Install the Invites Package
+
+```bash
+rails generate pu:invites:install
+```
+
+**Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--entity-model=NAME` | Entity | Entity model name for scoping |
+| `--user-model=NAME` | User | User model name |
+| `--membership-model=NAME` | EntityUser | Membership join model |
+| `--roles=ROLES` | member,admin | Comma-separated roles |
+| `--rodauth=NAME` | user | Rodauth configuration for signup |
+| `--enforce-domain` | false | Require email domain to match entity |
+
+**Example with custom models:**
+
+```bash
+rails g pu:invites:install \
+  --entity-model=Organization \
+  --user-model=Customer \
+  --membership-model=OrganizationMember \
+  --roles=member,manager,admin
+```
+
+### What Gets Created
+
+```
+packages/invites/
+├── app/
+│   ├── controllers/invites/
+│   │   ├── user_invitations_controller.rb
+│   │   └── welcome_controller.rb
+│   ├── definitions/invites/
+│   │   └── user_invite_definition.rb
+│   ├── interactions/invites/
+│   │   ├── cancel_invite_interaction.rb
+│   │   └── resend_invite_interaction.rb
+│   ├── mailers/invites/
+│   │   └── user_invite_mailer.rb
+│   ├── models/invites/
+│   │   └── user_invite.rb
+│   ├── policies/invites/
+│   │   └── user_invite_policy.rb
+│   └── views/invites/
+│       ├── user_invitations/
+│       │   ├── error.html.erb
+│       │   ├── landing.html.erb
+│       │   ├── show.html.erb
+│       │   └── signup.html.erb
+│       ├── user_invite_mailer/
+│       │   ├── invitation.html.erb
+│       │   └── invitation.text.erb
+│       └── welcome/
+│           └── pending_invitation.html.erb
+
+app/interactions/
+├── entity/
+│   └── invite_user_interaction.rb
+└── user/
+    └── invite_user_interaction.rb
+
+db/migrate/
+└── TIMESTAMP_create_user_invites.rb
+```
+
+### Routes Added
+
+```ruby
+# Public invitation routes (unauthenticated)
+get "welcome", to: "invites/welcome#index"
+get "invitations/:token", to: "invites/user_invitations#show"
+post "invitations/:token/accept", to: "invites/user_invitations#accept"
+get "invitations/:token/signup", to: "invites/user_invitations#signup"
+post "invitations/:token/signup", to: "invites/user_invitations#signup"
+```
+
+## Connecting Invitables
+
+Invitables are models that trigger invitations and get notified when they're accepted. Common examples:
+- `Tenant` - A tenant record that needs a user assigned
+- `TeamMember` - A membership record created by admin, waiting for user signup
+- `ProjectCollaborator` - A project role waiting for user acceptance
+
+### Generate an Invitable
+
+```bash
+rails generate pu:invites:invitable Tenant
+rails generate pu:invites:invitable TeamMember --role=member
+rails generate pu:invites:invitable Tenant --dest=my_package
+```
+
+**Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--role=ROLE` | member | Role to assign to invited users |
+| `--user-model=NAME` | User | User model name |
+| `--membership-model=NAME` | EntityUser | Membership model |
+| `--dest=PACKAGE` | main_app | Destination package |
+| `--[no-]email-templates` | true | Generate custom email templates |
+
+### Implement the Callback
+
+After generation, implement `on_invite_accepted` in your invitable model:
+
+```ruby
+# app/models/tenant.rb
+class Tenant < ApplicationRecord
+  include Plutonium::Invites::Concerns::Invitable
+
+  belongs_to :entity
+  belongs_to :user, optional: true
+
+  def on_invite_accepted(user)
+    update!(user: user, status: :active)
+  end
+end
+```
+
+## How the Flow Works
+
+### 1. Admin Sends Invite
+
+An admin uses the "Invite User" action on an entity or invitable:
+
+```ruby
+# From entity context
+entity.invite_user(email: "user@example.com", role: :member)
+
+# From invitable context (e.g., Tenant)
+tenant.invite_user(email: "user@example.com")
+```
+
+### 2. Email Sent
+
+The system sends an email with a secure invitation link:
+
+```
+Subject: You've been invited to join Acme Corp
+
+Click here to accept: https://app.example.com/invitations/abc123...
+```
+
+### 3. User Accepts Invite
+
+**Existing User Flow:**
+1. User clicks invite link
+2. User logs in (or is already logged in)
+3. System validates email matches
+4. Membership created, invitable notified
+
+**New User Flow:**
+1. User clicks invite link
+2. User clicks "Create Account"
+3. User signs up with the invited email
+4. System validates email matches
+5. Membership created, invitable notified
+
+### 4. Pending Invite Check
+
+After login, users are redirected to `/welcome` where pending invites are shown:
+
+```ruby
+# In your controller
+include Plutonium::Invites::PendingInviteCheck
+
+# Automatically shows pending invites after login
+```
+
+## UserInvite Model
+
+The generated `Invites::UserInvite` model includes:
+
+```ruby
+class Invites::UserInvite < Invites::ResourceRecord
+  include Plutonium::Invites::Concerns::InviteToken
+
+  # Associations
+  belongs_to :entity
+  belongs_to :invited_by, polymorphic: true
+  belongs_to :user, optional: true
+  belongs_to :invitable, polymorphic: true, optional: true
+
+  # States: pending, accepted, expired, cancelled
+  enum :state, pending: 0, accepted: 1, expired: 2, cancelled: 3
+
+  # Roles
+  enum :role, member: 0, admin: 1
+end
+```
+
+### Key Methods
+
+```ruby
+# Find valid invite for acceptance
+invite = Invites::UserInvite.find_for_acceptance(token)
+
+# Accept for a user
+invite.accept_for_user!(current_user)
+
+# Resend invitation email
+invite.resend!
+
+# Cancel invitation
+invite.cancel!
+```
+
+## Customization
+
+### Custom Email Templates
+
+Override templates in your package:
+
+```erb
+<%# packages/invites/app/views/invites/user_invite_mailer/invitation.html.erb %>
+<h1>Welcome to <%= @invite.entity.name %>!</h1>
+<p><%= @invite.invited_by.email %> has invited you to join.</p>
+<p><%= link_to "Accept Invitation", @invitation_url %></p>
+```
+
+### Custom Validation
+
+Extend the invite model:
+
+```ruby
+# packages/invites/app/models/invites/user_invite.rb
+class Invites::UserInvite < Invites::ResourceRecord
+  validate :email_not_already_member
+
+  private
+
+  def email_not_already_member
+    existing = membership_model.joins(:user)
+      .where(entity: entity, users: { email: email })
+      .exists?
+
+    errors.add(:email, "is already a member") if existing
+  end
+end
+```
+
+### Domain Enforcement
+
+Enable domain matching in the install:
+
+```bash
+rails g pu:invites:install --enforce-domain
+```
+
+This requires the invited email domain to match the entity's domain.
+
+### Custom Roles
+
+Specify roles during install:
+
+```bash
+rails g pu:invites:install --roles=viewer,editor,admin,owner
+```
+
+## Integration with Portals
+
+### Connect Invites to Your Portal
+
+```ruby
+# packages/customer_portal/lib/engine.rb
+module CustomerPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    # Register the invites package for this portal
+    register_package Invites::Engine
+  end
+end
+```
+
+### Entity-Scoped Invite Management
+
+The `Invites::UserInvite` definition automatically scopes to the current entity:
+
+```ruby
+# In your portal, invites are automatically filtered by entity_scope
+# Admins only see invites for their organization
+```
+
+## Troubleshooting
+
+### Invite Not Found
+
+- Check the token hasn't expired (default: 1 week)
+- Verify the invite hasn't been cancelled
+- Ensure the invite is still in `pending` state
+
+### Email Mismatch Error
+
+The system requires the accepting user's email to match the invited email:
+
+```
+"This invitation is for user@example.com. You must use an account with that email address."
+```
+
+To allow any email (not recommended for security):
+
+```ruby
+# In your UserInvite model
+def enforce_email?
+  false
+end
+```
+
+### Rodauth Integration Issues
+
+Ensure the Rodauth plugin is configured:
+
+```ruby
+# app/rodauth/user_rodauth_plugin.rb
+configure do
+  login_return_to_requested_location? true
+  login_redirect "/welcome"
+
+  after_login do
+    session[:after_welcome_redirect] = session.delete(:login_redirect)
+  end
+end
+```
+
+## Related Skills
+
+- `plutonium-rodauth` - Authentication setup
+- `plutonium-interaction` - Custom business logic
+- `plutonium-portal` - Portal configuration
+- `plutonium-policy` - Authorization for invite actions

data/.claude/skills/plutonium-package/SKILL.md

@@ -74,7 +74,8 @@ packages/admin_portal/
 │   ├── controllers/admin_portal/
 │   │   ├── concerns/controller.rb
 │   │   ├── dashboard_controller.rb
-│   │   └── plutonium_controller.rb
+│   │   ├── plutonium_controller.rb
+│   │   └── resource_controller.rb
 │   ├── definitions/admin_portal/     # Portal-specific overrides
 │   ├── policies/admin_portal/        # Portal-specific overrides
 │   └── views/

data/.claude/skills/plutonium-portal/SKILL.md

@@ -20,12 +20,16 @@ rails g pu:pkg:portal dashboard
 | `--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 g pu:pkg:portal admin --auth=admin
 rails g pu:pkg:portal api --public
 rails g pu:pkg:portal custom --byo
+
+# With entity scoping (multi-tenancy)
+rails g pu:pkg:portal admin --auth=admin --scope=Organization
 ```
 
 Without flags, the generator prompts interactively:
@@ -244,21 +248,31 @@ end
 
 ## Controller Hierarchy
 
-### Resource Controllers
+Portal controllers inherit from the feature package's controller if one exists (and include the portal's `Concerns::Controller`). If no feature package controller exists, they inherit from the portal's `ResourceController`.
 
-Portal resource controllers inherit from the feature package's controller:
+```ruby
+# With feature package controller:
+class DashboardPortal::PostsController < ::PostsController
+  include DashboardPortal::Concerns::Controller
+end
 
-```
-::PostsController (feature package controller)
-    ↓
-DashboardPortal::PostsController (portal-specific)
+# Without feature package controller:
+class DashboardPortal::PostsController < DashboardPortal::ResourceController
+end
 ```
 
-Controllers are auto-created if not defined. When accessing `DashboardPortal::PostsController`:
+### Portal ResourceController
 
-1. If file exists, use it
-2. Otherwise, dynamically create inheriting from `::PostsController`
-3. Include `DashboardPortal::Concerns::Controller`
+The portal's `ResourceController` serves as the base class for resource controllers when no feature package controller exists. It includes the portal's `Concerns::Controller` so individual resource controllers don't need to.
+
+```ruby
+# packages/dashboard_portal/app/controllers/dashboard_portal/resource_controller.rb
+module DashboardPortal
+  class ResourceController < ::ResourceController
+    include DashboardPortal::Concerns::Controller
+  end
+end
+```
 
 ### Non-Resource Controllers
 
@@ -309,13 +323,13 @@ end
 
 ```ruby
 # packages/dashboard_portal/app/controllers/dashboard_portal/posts_controller.rb
-class DashboardPortal::PostsController < ::PostsController
-  include DashboardPortal::Concerns::Controller
-
-  private
+module DashboardPortal
+  class PostsController < ResourceController
+    private
 
-  def preferred_action_after_submit
-    "index"
+    def preferred_action_after_submit
+      "index"
+    end
   end
 end
 ```