plutonium 0.33.1 → 0.34.0

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

@@ -0,0 +1,400 @@
+---
+name: portal
+description: Plutonium portals - web interfaces with authentication, entity scoping, and routes
+---
+
+# Plutonium Portals
+
+Portals are Rails engines that provide web interfaces for specific user types.
+
+## Creating a Portal
+
+```bash
+rails g pu:pkg:portal dashboard
+```
+
+### Generator Options
+
+| Option | Description |
+|--------|-------------|
+| `--auth=NAME` | Rodauth account to authenticate with (e.g., `--auth=user`) |
+| `--public` | Grant public access (no authentication) |
+| `--byo` | Bring your own authentication |
+
+```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
+```
+
+Without flags, the generator prompts interactively:
+- **Rodauth account** - Use existing Rodauth authentication
+- **Public access** - No authentication required
+- **Bring your own** - Implement custom `current_user`
+
+## Portal Engine
+
+```ruby
+# packages/dashboard_portal/lib/engine.rb
+module DashboardPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      # Optional: multi-tenancy
+      scope_to_entity Organization, strategy: :path
+    end
+  end
+end
+```
+
+## Authentication
+
+### Rodauth Integration
+
+```ruby
+# packages/dashboard_portal/app/controllers/dashboard_portal/concerns/controller.rb
+module DashboardPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+      include Plutonium::Auth::Rodauth(:user)  # Use :user account
+    end
+  end
+end
+```
+
+### Public Access
+
+```ruby
+module DashboardPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+      include Plutonium::Auth::Public
+    end
+  end
+end
+```
+
+### Custom Authentication
+
+```ruby
+module DashboardPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+      include Plutonium::Auth::Public
+
+      def current_user
+        @current_user ||= User.find_by(api_key: request.headers["X-API-Key"])
+      end
+    end
+  end
+end
+```
+
+## Entity Scoping (Multi-tenancy)
+
+Automatically scope all data to a parent entity.
+
+### Path Strategy
+
+Entity ID in URL path:
+
+```ruby
+module AdminPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      scope_to_entity Organization, strategy: :path
+    end
+  end
+end
+```
+
+Routes become: `/organizations/:organization_id/posts`
+
+### Custom Strategy
+
+Implement your own lookup method:
+
+```ruby
+module AdminPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      scope_to_entity Organization, strategy: :current_organization
+    end
+  end
+end
+
+# In controller concern
+module AdminPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+
+      private
+
+      # Method name must match strategy
+      def current_organization
+        @current_organization ||= Organization.find_by!(subdomain: request.subdomain)
+      end
+    end
+  end
+end
+```
+
+### Accessing the Scoped Entity
+
+```ruby
+current_scoped_entity  # The current Organization/Account/etc.
+scoped_to_entity?      # true if scoping is active
+```
+
+### Model Requirements
+
+Models must have an association path to the scoped entity:
+
+```ruby
+# Direct association (preferred)
+class Post < ResourceRecord
+  belongs_to :organization
+end
+
+# Through association
+class Comment < ResourceRecord
+  belongs_to :post
+  has_one :organization, through: :post
+end
+
+# Complex (define custom scope)
+class AuditLog < ResourceRecord
+  scope :associated_with_organization, ->(org) {
+    joins(:user).where(users: { organization_id: org.id })
+  }
+end
+```
+
+## Routes
+
+### Portal Routes
+
+```ruby
+# packages/dashboard_portal/config/routes.rb
+DashboardPortal::Engine.routes.draw do
+  root to: "dashboard#index"
+
+  # Register resources
+  register_resource ::Post
+  register_resource Blogging::Comment
+
+  # Custom routes
+  get "settings", to: "settings#index"
+end
+```
+
+### Custom Routes on Resources
+
+Add member or collection routes with a block:
+
+```ruby
+register_resource ::Post do
+  member do
+    get :preview
+    get :analytics
+    post :publish
+  end
+  collection do
+    get :archived
+    post :bulk_publish
+  end
+end
+```
+
+This generates:
+- `GET /posts/:id/preview`
+- `GET /posts/:id/analytics`
+- `POST /posts/:id/publish`
+- `GET /posts/archived`
+- `POST /posts/bulk_publish`
+
+### Mounting in Main App
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # With authentication constraint
+  constraints Rodauth::Rails.authenticate(:user) do
+    mount DashboardPortal::Engine, at: "/dashboard"
+  end
+
+  # Or without
+  mount PublicPortal::Engine, at: "/public"
+end
+```
+
+## Controller Hierarchy
+
+```
+::PlutoniumController (app-wide base)
+    ↓
+::ResourceController (resource handling)
+    ↓
+DashboardPortal::ResourceController (portal base)
+    ↓
+DashboardPortal::PostsController (resource-specific)
+```
+
+### Portal Controllers
+
+```ruby
+# packages/dashboard_portal/app/controllers/dashboard_portal/resource_controller.rb
+module DashboardPortal
+  class ResourceController < ::ResourceController
+    include DashboardPortal::Concerns::Controller
+  end
+end
+```
+
+### Dynamic Controllers
+
+Controllers are auto-created if not defined. When accessing `DashboardPortal::PostsController`:
+
+1. If file exists, use it
+2. Otherwise, dynamically create inheriting from `::PostsController`
+3. Include `DashboardPortal::Concerns::Controller`
+
+## Portal-Specific Overrides
+
+### Override Definition
+
+```ruby
+# packages/dashboard_portal/app/definitions/dashboard_portal/post_definition.rb
+class DashboardPortal::PostDefinition < ::PostDefinition
+  # Hide certain actions from this portal
+  # Add portal-specific scopes
+  scope :my_posts, -> { where(user: current_user) }
+end
+```
+
+### Override Policy
+
+```ruby
+# packages/dashboard_portal/app/policies/dashboard_portal/post_policy.rb
+class DashboardPortal::PostPolicy < ::PostPolicy
+  include DashboardPortal::ResourcePolicy
+
+  def destroy?
+    false  # No deletion in user portal
+  end
+
+  def permitted_attributes_for_create
+    %i[title content]  # Fewer fields than admin
+  end
+end
+```
+
+### Override Controller
+
+```ruby
+# packages/dashboard_portal/app/controllers/dashboard_portal/posts_controller.rb
+module DashboardPortal
+  class PostsController < ResourceController
+    private
+
+    def preferred_action_after_submit
+      "index"
+    end
+  end
+end
+```
+
+## Layout and Views
+
+### Portal Layout
+
+```erb
+<!-- packages/dashboard_portal/app/views/layouts/dashboard_portal.html.erb -->
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Dashboard</title>
+  <%= csrf_meta_tags %>
+  <%= stylesheet_link_tag "application" %>
+</head>
+<body>
+  <nav><!-- Portal navigation --></nav>
+  <main><%= yield %></main>
+</body>
+</html>
+```
+
+### Dashboard Controller
+
+```ruby
+# packages/dashboard_portal/app/controllers/dashboard_portal/dashboard_controller.rb
+module DashboardPortal
+  class DashboardController < PlutoniumController
+    def index
+      # Dashboard home page
+    end
+  end
+end
+```
+
+## Multiple Portals Example
+
+```ruby
+# Admin portal - full access
+module AdminPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      scope_to_entity Organization, strategy: :path
+    end
+  end
+end
+
+# User dashboard - limited access
+module DashboardPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      scope_to_entity Organization, strategy: :path
+    end
+  end
+end
+
+# Public portal - read-only, no auth
+module PublicPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+  end
+end
+```
+
+Each portal can:
+- Have different authentication
+- Show different fields
+- Allow different actions
+- Use different layouts
+
+## Related Skills
+
+- `package` - Package overview (features vs portals)
+- `rodauth` - Authentication setup and configuration
+- `connect-resource` - Connecting resources to portals
+- `policy` - Portal-specific policies
+- `definition` - Portal-specific definitions
+- `controller` - Portal-specific controllers

data/.claude/skills/resource/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: resource
+description: Overview of Plutonium resources - what they are and how the pieces fit together
+---
+
+# Plutonium Resources
+
+A **resource** in Plutonium is the combination of four layers that work together to provide full CRUD functionality with minimal code.
+
+## The Four Layers
+
+| Layer | File | Purpose |
+|-------|------|---------|
+| **Model** | `app/models/post.rb` | Data, validations, associations, business rules |
+| **Definition** | `app/definitions/post_definition.rb` | UI configuration - how fields render, actions, filters |
+| **Policy** | `app/policies/post_policy.rb` | Authorization - who can do what |
+| **Controller** | `app/controllers/posts_controller.rb` | Request handling - usually empty, inherits CRUD |
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                           Resource                               │
+├─────────────────────────────────────────────────────────────────┤
+│  Model          │  Definition      │  Policy        │ Controller │
+│  (WHAT it is)   │  (HOW it looks)  │  (WHO can act) │ (HOW it    │
+│                 │                  │                │  responds)  │
+├─────────────────────────────────────────────────────────────────┤
+│  - attributes   │  - field types   │  - permissions │ - CRUD     │
+│  - associations │  - inputs/forms  │  - scoping     │ - redirects│
+│  - validations  │  - displays      │  - attributes  │ - params   │
+│  - scopes       │  - actions       │                │            │
+│  - callbacks    │  - filters       │                │            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Creating Resources
+
+### New Resources (from scratch)
+
+Use the scaffold generator to create all four layers at once:
+
+```bash
+rails g pu:res:scaffold Post title:string content:text:required published:boolean
+```
+
+This generates:
+- `app/models/post.rb` - Model with validations
+- `app/definitions/post_definition.rb` - Definition (empty, uses auto-detection)
+- `app/policies/post_policy.rb` - Policy with sensible defaults
+- `app/controllers/posts_controller.rb` - Controller (empty, inherits CRUD)
+- Migration file
+
+See `create-resource` skill for full generator options.
+
+### From Existing Models
+
+For existing Rails projects, you can convert models to Plutonium resources:
+
+1. **Include the module** in your model:
+
+```ruby
+class Post < ApplicationRecord
+  include Plutonium::Resource::Record
+  # Your existing code...
+end
+```
+
+Or inherit from a base class that includes it:
+
+```ruby
+class Post < ResourceRecord
+  # Your existing code...
+end
+```
+
+2. **Generate the supporting files** (definition, policy, controller):
+
+```bash
+rails g pu:res:scaffold Post --no-migration
+```
+
+This creates definition, policy, and controller without touching your existing model.
+
+3. **Connect to a portal**:
+
+```bash
+rails g pu:res:conn Post --dest=admin_portal
+```
+
+## Connecting to Portals
+
+Resources must be connected to a portal to be accessible:
+
+```bash
+rails g pu:res:conn Post --portal AdminPortal
+```
+
+This:
+- Registers the resource in the portal
+- Creates a route
+- Optionally creates portal-specific definition override
+
+See `connect-resource` skill for details.
+
+## Layer Responsibilities
+
+### Model (Data Layer)
+
+```ruby
+class Post < ResourceRecord
+  belongs_to :author, class_name: "User"
+  has_many :comments
+
+  validates :title, presence: true
+
+  scope :published, -> { where(published: true) }
+end
+```
+
+The model handles:
+- Database schema and associations
+- Data validation
+- Business logic scopes
+- Callbacks
+
+**Skills:** `model`, `model-features`
+
+### Definition (UI Layer)
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Override auto-detected field types
+  input :content, as: :rich_text
+
+  # Add filters and scopes
+  filter :published, with: Plutonium::Query::Filters::Boolean
+  scope :published
+
+  # Add actions
+  action :publish, interaction: PublishPostInteraction
+end
+```
+
+The definition handles:
+- Field type overrides (auto-detection handles most cases)
+- Form input customization
+- Display formatting
+- Search, filters, scopes, sorting
+- Actions (interactive operations)
+
+**Skills:** `definition`, `definition-fields`, `definition-actions`, `definition-query`
+
+### Policy (Authorization Layer)
+
+```ruby
+class PostPolicy < ResourcePolicy
+  # Who can perform actions
+  def create?
+    user.present?
+  end
+
+  def read?
+    true
+  end
+
+  def publish?
+    user.admin? || record.author == user
+  end
+
+  # What records are visible
+  relation_scope do |relation|
+    return relation if user.admin?
+    relation.where(author: user)
+  end
+
+  # What attributes are readable/writable
+  def permitted_attributes_for_read
+    %i[title content published author created_at]
+  end
+
+  def permitted_attributes_for_create
+    %i[title content]
+  end
+end
+```
+
+The policy handles:
+- Action authorization (create?, update?, destroy?, custom actions)
+- Resource scoping (what records user can see)
+- Attribute permissions (read/write access per field)
+
+**Skill:** `policy`
+
+### Controller (Request Layer)
+
+```ruby
+class PostsController < ::ResourceController
+  # Empty - all CRUD actions inherited automatically
+end
+```
+
+Controllers are usually empty because they inherit full CRUD functionality. Customize only when needed:
+
+```ruby
+class PostsController < ::ResourceController
+  private
+
+  def preferred_action_after_submit
+    "index"  # Redirect to list instead of show
+  end
+end
+```
+
+The controller handles:
+- Request/response cycle
+- Redirect logic
+- Custom parameter processing
+- Non-standard authorization flows
+
+**Skill:** `controller`
+
+## Auto-Detection
+
+Plutonium automatically detects from your model:
+- All database columns with appropriate field types
+- Associations (belongs_to, has_one, has_many)
+- Attachments (Active Storage)
+- Enums
+
+**You only need to declare when overriding defaults.**
+
+## Portal-Specific Customization
+
+Each portal can have its own definition that overrides the base:
+
+```ruby
+# Base definition
+class PostDefinition < ResourceDefinition
+  scope :published
+end
+
+# Admin portal sees more
+class AdminPortal::PostDefinition < ::PostDefinition
+  scope :draft
+  scope :pending_review
+  action :feature, interaction: FeaturePostInteraction
+end
+
+# Public portal is restricted
+class PublicPortal::PostDefinition < ::PostDefinition
+  # Only published scope, no actions
+end
+```
+
+## Workflow Summary
+
+1. **Generate** - `rails g pu:res:scaffold Model attributes...`
+2. **Connect** - `rails g pu:res:conn Model --portal PortalName`
+3. **Customize** - Edit definition/policy as needed (model rarely needs changes)
+4. **Override per portal** - Create portal-specific definitions when needed
+
+## Related Skills
+
+- `model` - Model structure and organization
+- `model-features` - has_cents, associations, scopes, routes
+- `definition` - Definition overview and structure
+- `definition-fields` - Fields, inputs, displays, columns
+- `definition-actions` - Actions and interactions
+- `interaction` - Writing interaction classes
+- `definition-query` - Search, filters, scopes, sorting
+- `policy` - Authorization and permissions
+- `controller` - Controller customization
+- `views` - Custom pages, displays, tables using Phlex
+- `forms` - Custom form templates and field builders
+- `assets` - TailwindCSS and component theming
+- `package` - Feature and portal packages
+- `portal` - Portal configuration and entity scoping
+- `nested-resources` - Parent/child routes and scoping
+- `installation` - Setting up Plutonium
+- `rodauth` - Authentication setup
+- `create-resource` - Scaffold generator details
+- `connect-resource` - Portal connection details