plutonium 0.44.0 → 0.45.0

data/.claude/skills/plutonium-model-features/SKILL.md

@@ -1,286 +0,0 @@
----
-name: plutonium-model-features
-description: Plutonium model features - has_cents, associations, scopes, and routing
----
-
-# Plutonium Model Features
-
-Advanced features available in Plutonium resource models.
-
-## Monetary Handling (has_cents)
-
-Store monetary values as integers (cents) while exposing decimal interfaces.
-
-### Basic Usage
-
-```ruby
-class Product < ResourceRecord
-  has_cents :price_cents                    # Creates price getter/setter
-  has_cents :cost_cents, name: :wholesale   # Custom accessor name
-  has_cents :tax_cents, rate: 1000          # 3 decimal places
-  has_cents :quantity_cents, rate: 1        # Whole numbers only
-end
-
-product = Product.new
-product.price = 19.99
-product.price_cents  # => 1999
-product.price        # => 19.99
-
-# Truncates (doesn't round)
-product.price = 10.999
-product.price_cents  # => 1099
-```
-
-### Options
-
-```ruby
-has_cents :field_cents,
-  name: :custom_name,    # Accessor name (default: field without _cents)
-  rate: 100,             # Conversion rate (default: 100)
-  suffix: "amount"       # Suffix for generated name (default: "amount")
-```
-
-### Validation
-
-```ruby
-class Product < ResourceRecord
-  has_cents :price_cents
-
-  # Validate the cents field
-  validates :price_cents, numericality: {greater_than: 0}
-end
-
-product = Product.new(price: -10)
-product.valid?  # => false
-product.errors[:price_cents]  # => ["must be greater than 0"]
-product.errors[:price]        # => ["is invalid"] (propagated)
-```
-
-### Introspection
-
-```ruby
-Product.has_cents_attributes
-# => {price_cents: {name: :price, rate: 100}, ...}
-
-Product.has_cents_attribute?(:price_cents)  # => true
-```
-
-## Association SGID Support
-
-All associations get Signed Global ID (SGID) methods for secure serialization.
-
-### Singular Associations (belongs_to, has_one)
-
-```ruby
-class Post < ResourceRecord
-  belongs_to :user
-  has_one :featured_image
-end
-
-post = Post.first
-
-# Get SGID
-post.user_sgid           # => "BAh7CEkiCG..."
-post.featured_image_sgid # => "BAh7CEkiCG..."
-
-# Set by SGID (finds and assigns)
-post.user_sgid = "BAh7CEkiCG..."
-post.featured_image_sgid = "BAh7CEkiCG..."
-```
-
-### Collection Associations (has_many, has_and_belongs_to_many)
-
-```ruby
-class User < ResourceRecord
-  has_many :posts
-  has_and_belongs_to_many :roles
-end
-
-user = User.first
-
-# Get SGIDs
-user.post_sgids  # => ["BAh7CEkiCG...", "BAh7CEkiCG..."]
-user.role_sgids  # => ["BAh7CEkiCG...", "BAh7CEkiCG..."]
-
-# Bulk assignment
-user.post_sgids = ["BAh7CEkiCG...", ...]
-
-# Individual manipulation
-user.add_post_sgid("BAh7CEkiCG...")     # Add to collection
-user.remove_post_sgid("BAh7CEkiCG...")  # Remove from collection
-```
-
-### Use Cases
-
-- Secure form submissions without exposing internal IDs
-- API responses with portable references
-- Caching and serialization
-
-## Entity Scoping (associated_with)
-
-Query records associated with another record. Essential for multi-tenant apps.
-
-### Basic Usage
-
-```ruby
-class Comment < ResourceRecord
-  belongs_to :post
-end
-
-# Find comments for a post
-Comment.associated_with(post)
-# => Comment.where(post: post)
-```
-
-### Association Detection
-
-Works with:
-- `belongs_to` - Uses WHERE clause (most efficient)
-- `has_one` - Uses JOIN + WHERE
-- `has_many` - Uses JOIN + WHERE
-
-```ruby
-# Direct association (preferred)
-Comment.associated_with(post)  # WHERE post_id = ?
-
-# Reverse association (less efficient, logs warning)
-Post.associated_with(comment)  # JOIN comments WHERE comments.id = ?
-```
-
-### Custom Scopes
-
-For optimal performance, define custom scopes:
-
-```ruby
-class Comment < ResourceRecord
-  # Custom scope naming: associated_with_{model_name}
-  scope :associated_with_user, ->(user) do
-    joins(:post).where(posts: {user_id: user.id})
-  end
-end
-
-# Automatically uses custom scope
-Comment.associated_with(user)
-```
-
-### Error Handling
-
-```ruby
-# When no association exists
-UnrelatedModel.associated_with(user)
-# Raises: Could not resolve the association between 'UnrelatedModel' and 'User'
-#
-# Define:
-#  1. the associations between the models
-#  2. a named scope on UnrelatedModel e.g.
-#
-# scope :associated_with_user, ->(user) { do_something_here }
-```
-
-## URL Routing
-
-### Default Behavior
-
-```ruby
-user = User.find(1)
-user.to_param  # => "1"
-```
-
-### Custom Path Parameters
-
-Use a stable, unique field instead of ID:
-
-```ruby
-class User < ResourceRecord
-  private
-
-  def path_parameter(param_name)
-    :username  # Must be unique
-  end
-end
-
-user = User.create(username: "john_doe")
-user.to_param  # => "john_doe"
-# URLs: /users/john_doe
-```
-
-### Dynamic Path Parameters (SEO-friendly)
-
-Include ID prefix for uniqueness with human-readable suffix:
-
-```ruby
-class Article < ResourceRecord
-  private
-
-  def dynamic_path_parameter(param_name)
-    :title
-  end
-end
-
-article = Article.create(id: 1, title: "My Great Article")
-article.to_param  # => "1-my-great-article"
-# URLs: /articles/1-my-great-article
-```
-
-### Path Parameter Lookup
-
-```ruby
-# Scope for finding by path parameter
-User.from_path_param("john_doe")
-Article.from_path_param("1-my-great-article")  # Extracts ID
-```
-
-## Association Route Discovery
-
-```ruby
-class User < ResourceRecord
-  has_many :posts
-  has_many :comments
-  accepts_nested_attributes_for :posts
-end
-
-# Get has_many association names
-User.has_many_association_routes
-# => ["posts", "comments"]
-
-# Get nested attributes config
-User.all_nested_attributes_options
-# => {posts: {allow_destroy: false, update_only: false, macro: :has_many, class: Post}}
-```
-
-## Performance Tips
-
-### Field Introspection
-
-```ruby
-# Cached in production, fresh in development
-User.resource_field_names  # First call queries, subsequent cached
-```
-
-### Association Queries
-
-```ruby
-# Efficient: Direct belongs_to
-Comment.associated_with(post)  # Simple WHERE
-
-# Less efficient: Reverse has_many (logs warning)
-Post.associated_with(comment)  # JOIN required
-
-# Optimal: Custom scope when direct isn't possible
-scope :associated_with_user, ->(user) { where(user_id: user.id) }
-```
-
-### SGID Operations
-
-```ruby
-# Efficient: Batch assignment
-user.post_sgids = sgid_array  # Single operation
-
-# Inefficient: Individual adds
-sgid_array.each { |sgid| user.add_post_sgid(sgid) }
-```
-
-## Related Skills
-
-- `plutonium-model` - Model overview and structure
-- `plutonium-create-resource` - Scaffold generator

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

@@ -1,281 +0,0 @@
----
-name: plutonium-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 `plutonium-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 --dest=admin_portal
-```
-
-This:
-- Registers the resource in portal routes
-- Creates portal-specific controller
-- Creates portal-specific policy with attribute permissions
-
-See `plutonium-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:** `plutonium-model`, `plutonium-model-features`
-
-### Definition (UI Layer)
-
-```ruby
-class PostDefinition < ResourceDefinition
-  # Override auto-detected field types
-  input :content, as: :markdown
-
-  # 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:** `plutonium-definition`, `plutonium-definition-fields`, `plutonium-definition-actions`, `plutonium-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:** `plutonium-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:** `plutonium-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... --dest=main_app`
-2. **Connect** - `rails g pu:res:conn Model --dest=portal_name`
-3. **Customize** - Edit definition/policy as needed (model rarely needs changes)
-4. **Override per portal** - Create portal-specific definitions when needed
-
-## Related Skills
-
-- `plutonium-model` - Model structure and organization
-- `plutonium-model-features` - has_cents, associations, scopes, routes
-- `plutonium-definition` - Definition overview and structure
-- `plutonium-definition-fields` - Fields, inputs, displays, columns
-- `plutonium-definition-actions` - Actions and interactions
-- `plutonium-interaction` - Writing interaction classes
-- `plutonium-definition-query` - Search, filters, scopes, sorting
-- `plutonium-policy` - Authorization and permissions
-- `plutonium-controller` - Controller customization
-- `plutonium-views` - Custom pages, displays, tables using Phlex
-- `plutonium-forms` - Custom form templates and field builders
-- `plutonium-assets` - TailwindCSS and component theming
-- `plutonium-package` - Feature and portal packages
-- `plutonium-portal` - Portal configuration and entity scoping
-- `plutonium-nested-resources` - Parent/child routes and scoping
-- `plutonium-installation` - Setting up Plutonium
-- `plutonium-rodauth` - Authentication setup
-- `plutonium-create-resource` - Scaffold generator details
-- `plutonium-connect-resource` - Portal connection details