plutonium 0.33.1 → 0.34.0

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

@@ -0,0 +1,286 @@
+---
+name: 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
+
+- `model` - Model overview and structure
+- `create-resource` - Scaffold generator

data/.claude/skills/nested-resources/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: nested-resources
+description: Plutonium nested resources - parent/child routes, scoping, and URL generation
+---
+
+# Nested Resources
+
+Plutonium automatically creates nested routes for `has_many` associations, scopes queries to the parent, and handles URL generation.
+
+## How It Works
+
+When you register resources with parent-child relationships:
+
+```ruby
+# In portal routes
+register_resource ::Company
+register_resource ::Property  # has belongs_to :company
+```
+
+Plutonium automatically creates nested routes:
+- `/companies/:company_id/properties` - Properties scoped to company
+- `/companies/:company_id/properties/new` - New property for company
+- `/companies/:company_id/properties/:id` - Property in company context
+
+## Automatic Behavior
+
+When accessing nested routes, Plutonium automatically:
+
+1. **Resolves the parent** via `current_parent`
+2. **Scopes queries** to only show records belonging to parent
+3. **Assigns parent** to new records on create
+4. **Hides parent field** in forms (already determined by URL)
+5. **Authorizes parent access** before proceeding
+
+## Controller Methods
+
+### current_parent
+
+Returns the parent record from the URL:
+
+```ruby
+# URL: /companies/123/properties
+current_parent  # => Company.find(123)
+```
+
+### parent_route_param
+
+The URL parameter containing the parent ID:
+
+```ruby
+parent_route_param  # => :company_id
+```
+
+### parent_input_param
+
+The association name on the child model:
+
+```ruby
+parent_input_param  # => :company
+```
+
+## Presentation Hooks
+
+Control whether parent field appears in views/forms:
+
+```ruby
+class PropertiesController < ResourceController
+  private
+
+  # Show parent field in displays (default: false)
+  def present_parent?
+    true
+  end
+
+  # Allow changing parent in forms (default: same as present_parent?)
+  def submit_parent?
+    false  # Parent is set from URL, don't allow changing
+  end
+end
+```
+
+## Query Scoping
+
+Collections are automatically scoped to the parent via policies:
+
+```ruby
+class PropertyPolicy < ResourcePolicy
+  relation_scope do |relation|
+    relation = super(relation)  # Applies associated_with(entity_scope)
+    # entity_scope is the current_parent
+    relation
+  end
+end
+```
+
+The `associated_with` scope finds records belonging to the parent:
+
+```ruby
+# Automatic detection via belongs_to
+Property.associated_with(company)
+# => Property.where(company: company)
+```
+
+### Custom Association Scope
+
+For complex relationships, define a custom scope:
+
+```ruby
+class Property < ResourceRecord
+  scope :associated_with_organization, ->(org) {
+    joins(:company).where(companies: { organization_id: org.id })
+  }
+end
+```
+
+## URL Generation
+
+Use `resource_url_for` with the `parent:` option:
+
+```ruby
+# Child collection
+resource_url_for(Property, parent: company)
+# => /companies/123/properties
+
+# Child record
+resource_url_for(property, parent: company)
+# => /companies/123/properties/456
+
+# New child form
+resource_url_for(Property, action: :new, parent: company)
+# => /companies/123/properties/new
+
+# Edit child
+resource_url_for(property, action: :edit, parent: company)
+# => /companies/123/properties/456/edit
+```
+
+## Association Panels
+
+On the parent's show page, child resources are displayed via association panels:
+
+```ruby
+class CompanyPolicy < ResourcePolicy
+  def permitted_associations
+    %i[properties contacts]  # Shows panels for these
+  end
+end
+```
+
+The panel loads children via the nested route automatically.
+
+## Authorization
+
+### Parent Authorization
+
+The parent is authorized for `:read?` before `current_parent` returns:
+
+```ruby
+def current_parent
+  # ... resolution logic ...
+  authorize! parent, to: :read?
+  parent
+end
+```
+
+### Policy Context
+
+The parent is passed to child policies as `entity_scope`:
+
+```ruby
+class PropertyPolicy < ResourcePolicy
+  def create?
+    # entity_scope is the parent company
+    entity_scope.present? && user.member_of?(entity_scope)
+  end
+
+  def read?
+    entity_scope.present? && record.company == entity_scope
+  end
+end
+```
+
+## Parameter Handling
+
+Parent is automatically injected into resource params:
+
+```ruby
+# When creating a property under /companies/123/properties
+resource_params
+# => { name: "...", company: <Company:123>, company_id: 123 }
+```
+
+You don't need to include hidden fields for the parent in forms.
+
+## Nesting Limitations
+
+Plutonium supports **one level of nesting**:
+
+- ✅ `/companies/:company_id/properties` (parent → child)
+- ❌ `/companies/:company_id/properties/:property_id/units` (grandparent → parent → child)
+
+## Common Patterns
+
+### Scoped Uniqueness
+
+Validate uniqueness within parent:
+
+```ruby
+class Property < ResourceRecord
+  belongs_to :company
+  validates :code, uniqueness: { scope: :company_id }
+end
+```
+
+### Conditional Parent Display
+
+Show parent only in certain contexts:
+
+```ruby
+class PropertiesController < ResourceController
+  private
+
+  def present_parent?
+    # Show parent when accessed standalone, hide when nested
+    current_parent.nil?
+  end
+end
+```
+
+### Custom Parent Resolution
+
+Override parent lookup:
+
+```ruby
+class PropertiesController < ResourceController
+  private
+
+  def current_parent
+    @current_parent ||= Company.friendly.find(params[:company_id])
+  end
+end
+```
+
+### Breadcrumbs
+
+Breadcrumbs automatically include the parent:
+
+```
+Companies > Acme Corp > Properties > Property #123
+```
+
+## Route Registration with Custom Routes
+
+Add custom member/collection routes to nested resources:
+
+```ruby
+register_resource ::Property do
+  member do
+    get :analytics
+    post :archive
+  end
+end
+```
+
+Generates nested routes:
+- `/companies/:company_id/properties/:id/analytics`
+- `/companies/:company_id/properties/:id/archive`
+
+## Related Skills
+
+- `portal` - Route registration
+- `policy` - Authorization and scoping
+- `controller` - Presentation hooks
+- `model-features` - associated_with scope