plutonium 0.33.1 → 0.34.0

data/docs/reference/model/index.md

@@ -0,0 +1,219 @@
+# Model Reference
+
+Complete reference for Plutonium resource models.
+
+## Base Class
+
+All resource models inherit from `ResourceRecord`:
+
+```ruby
+class Post < ResourceRecord
+  # Your model code
+end
+```
+
+In packages, models inherit from the package's ResourceRecord:
+
+```ruby
+module Blogging
+  class Post < Blogging::ResourceRecord
+    # Your model code
+  end
+end
+```
+
+`ResourceRecord` is an abstract class that inherits from `ApplicationRecord` and is created by the Plutonium installer.
+
+## Standard ActiveRecord Features
+
+All standard ActiveRecord features work:
+
+```ruby
+class Post < ResourceRecord
+  # Associations
+  belongs_to :user
+  has_many :comments, dependent: :destroy
+  has_one :featured_image
+  has_many :tags, through: :post_tags
+
+  # Validations
+  validates :title, presence: true, length: { maximum: 200 }
+  validates :slug, uniqueness: true
+  validates :status, inclusion: { in: %w[draft published] }
+
+  # Scopes
+  scope :published, -> { where(status: 'published') }
+  scope :recent, -> { order(created_at: :desc) }
+  scope :by_author, ->(user) { where(user: user) }
+
+  # Callbacks
+  before_save :generate_slug
+  after_create :notify_subscribers
+
+  # Methods
+  def publish!
+    update!(status: 'published', published_at: Time.current)
+  end
+end
+```
+
+## Nested Resources
+
+Nesting is automatic via `belongs_to` associations:
+
+```ruby
+class Comment < ResourceRecord
+  belongs_to :post
+end
+```
+
+When both `Post` and `Comment` are registered in a portal, Plutonium automatically creates nested routes (`/posts/:post_id/comments`). The `associated_with` scope is automatically available for querying.
+
+See the [Nested Resources Guide](/guides/nested-resources) for details.
+
+## Entity Scoping (Multi-tenancy)
+
+Entity scoping is configured on the **portal engine**, not the model:
+
+```ruby
+# packages/customer_portal/lib/engine.rb
+module CustomerPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      scope_to_entity Organization
+    end
+  end
+end
+```
+
+See the [Multi-tenancy Guide](/guides/multi-tenancy) for details.
+
+## Plutonium Features
+
+See [Model Features](./features) for:
+- `has_cents` - Store monetary values as integers, expose as decimals
+- `to_label` - Human-readable record labels
+- `path_parameter` / `dynamic_path_parameter` - Custom URL parameters
+- Secure association SGIDs - Auto-generated SGID accessors for associations
+- `associated_with` - Scope for nested resource queries
+- Field introspection methods
+
+## Field Introspection
+
+Plutonium introspects models to detect:
+
+### Column Types
+
+| Database Type | Detected As |
+|--------------|-------------|
+| `string` | `:string` |
+| `text` | `:text` |
+| `integer` | `:integer` |
+| `bigint` | `:integer` |
+| `float` | `:float` |
+| `decimal` | `:decimal` |
+| `boolean` | `:boolean` |
+| `date` | `:date` |
+| `datetime` | `:datetime` |
+| `time` | `:time` |
+| `json`/`jsonb` | `:json` |
+
+### Constraints
+
+```ruby
+# NULL constraint detected
+t.string :title, null: false  # Required field
+```
+
+### Associations
+
+```ruby
+belongs_to :user      # Detected as association field
+has_many :comments    # Available for association panels
+```
+
+### Validations
+
+```ruby
+validates :title, presence: true    # Required
+validates :email, format: { ... }   # Format hint
+validates :role, inclusion: { in: [...] }  # Select options
+```
+
+## Model Organization
+
+### Feature Package Models
+
+```ruby
+# packages/blogging/app/models/blogging/post.rb
+module Blogging
+  class Post < ResourceRecord
+    # Namespaced model
+  end
+end
+```
+
+### Table Naming
+
+Namespaced models use prefixed tables:
+
+```ruby
+module Blogging
+  class Post < ResourceRecord
+    # Table: blogging_posts
+  end
+end
+```
+
+Override if needed:
+
+```ruby
+self.table_name = "posts"
+```
+
+## Best Practices
+
+### Keep Models Thin
+
+Put complex logic in Interactions:
+
+```ruby
+# Model: simple validations and associations
+class Post < ResourceRecord
+  validates :title, presence: true
+end
+
+# Interaction: complex logic
+class PublishPost < ResourceInteraction
+  def execute
+    resource.update!(published: true)
+    notify_subscribers
+    update_search_index
+    succeed(resource)
+  end
+end
+```
+
+### Use Meaningful Scopes
+
+```ruby
+# Good: intention-revealing names
+scope :visible_to, ->(user) { where(user: user).or(where(published: true)) }
+
+# Avoid: generic names
+scope :filtered, -> { where(status: 'active') }
+```
+
+### Validate at the Right Level
+
+- **Model**: Data integrity (presence, format, uniqueness)
+- **Interaction**: Business rules (can only publish once)
+- **Policy**: Authorization (user must own the record)
+
+## Related
+
+- [Model Features](./features)
+- [Resources Concept](/concepts/resources)
+- [Definition Reference](/reference/definition/)

data/docs/reference/policy/index.md

@@ -0,0 +1,385 @@
+# Policy Reference
+
+Complete reference for authorization policies. Built on [ActionPolicy](https://actionpolicy.evilmartians.io/).
+
+## Overview
+
+Policies control authorization at three levels:
+1. **Action Permissions** - Can user perform this action?
+2. **Attribute Permissions** - Which fields can user access?
+3. **Scope Permissions** - Which records can user see?
+
+## Base Class
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  # Policy code
+end
+```
+
+In packages, inherit from the package's ResourcePolicy:
+
+```ruby
+module AdminPortal
+  class PostPolicy < ::PostPolicy
+    # Portal-specific overrides
+  end
+end
+```
+
+## Authorization Context
+
+Inside a policy, you have access to:
+
+| Variable | Description |
+|----------|-------------|
+| `user` | Current authenticated user (required) |
+| `record` | Resource being authorized |
+| `entity_scope` | Current scoped entity (for multi-tenancy) |
+
+```ruby
+def update?
+  user          # => Current user
+  record        # => The Post instance
+  entity_scope  # => Organization for multi-tenant portals
+end
+```
+
+## Action Permissions
+
+### Core Actions (Must Override)
+
+These default to `false` - you must override them:
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  def create?
+    user.present?
+  end
+
+  def read?
+    true
+  end
+end
+```
+
+### Derived Actions
+
+These inherit from core actions by default:
+
+| Method | Inherits From | Override When |
+|--------|---------------|---------------|
+| `update?` | `create?` | Different update rules |
+| `destroy?` | `create?` | Different delete rules |
+| `index?` | `read?` | Custom listing rules |
+| `show?` | `read?` | Record-specific read rules |
+| `new?` | `create?` | Rarely needed |
+| `edit?` | `update?` | Rarely needed |
+| `search?` | `index?` | Search-specific rules |
+
+### Example with Ownership
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  def create?
+    user.present?
+  end
+
+  def read?
+    true
+  end
+
+  def update?
+    owner? || admin?
+  end
+
+  def destroy?
+    owner? || admin?
+  end
+
+  private
+
+  def owner?
+    record.user_id == user.id
+  end
+
+  def admin?
+    user.admin?
+  end
+end
+```
+
+### Custom Action Permissions
+
+For custom actions defined in definitions:
+
+```ruby
+def publish?
+  owner? && !record.published?
+end
+
+def archive?
+  owner? || admin?
+end
+
+def bulk_delete?
+  admin?
+end
+```
+
+Actions are secure by default - undefined methods return `false`.
+
+## Attribute Permissions
+
+### Core Methods (Must Override for Production)
+
+```ruby
+# What users can see (index, show)
+def permitted_attributes_for_read
+  %i[title body author created_at]
+end
+
+# What users can set (create, update)
+def permitted_attributes_for_create
+  %i[title body category_id]
+end
+```
+
+### Derived Methods
+
+| Method | Inherits From |
+|--------|---------------|
+| `permitted_attributes_for_update` | `permitted_attributes_for_create` |
+| `permitted_attributes_for_index` | `permitted_attributes_for_read` |
+| `permitted_attributes_for_show` | `permitted_attributes_for_read` |
+| `permitted_attributes_for_new` | `permitted_attributes_for_create` |
+| `permitted_attributes_for_edit` | `permitted_attributes_for_update` |
+
+### Conditional Attribute Access
+
+```ruby
+def permitted_attributes_for_create
+  attrs = %i[title body]
+  attrs << :featured if user.admin?
+  attrs << :author_id if user.admin?
+  attrs
+end
+
+def permitted_attributes_for_update
+  case record.status
+  when 'draft'
+    %i[title body category_id]
+  when 'published'
+    %i[body]  # Can only edit body once published
+  else
+    []
+  end
+end
+```
+
+### Auto-Detection (Development Only)
+
+In development, undefined attribute methods auto-detect from the model. This raises errors in production - always define explicitly:
+
+```
+🚨 Resource field auto-detection: PostPolicy#permitted_attributes_for_create
+Auto-detected resource fields result in security holes and will fail outside of development.
+```
+
+## Association Permissions
+
+Control which associations appear in panels and forms:
+
+```ruby
+def permitted_associations
+  %i[comments tags author]
+end
+```
+
+Returns an empty array by default.
+
+## Collection Scoping
+
+### relation_scope
+
+Filter which records users can see using ActionPolicy's `relation_scope`:
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  relation_scope do |relation|
+    if user.admin?
+      relation
+    else
+      relation.where(published: true).or(
+        relation.where(user_id: user.id)
+      )
+    end
+  end
+end
+```
+
+### With Entity Scoping
+
+Call `super` to preserve automatic entity scoping for multi-tenancy:
+
+```ruby
+relation_scope do |relation|
+  relation = super(relation)  # Applies associated_with(entity_scope)
+
+  if user.admin?
+    relation
+  else
+    relation.where(published: true)
+  end
+end
+```
+
+The default `relation_scope` automatically applies `relation.associated_with(entity_scope)` when an entity scope is present.
+
+## Portal-Specific Policies
+
+Override policies for specific portals:
+
+```ruby
+# packages/admin_portal/app/policies/admin_portal/post_policy.rb
+module AdminPortal
+  class PostPolicy < ::PostPolicy
+    def destroy?
+      true  # Admins can delete any post
+    end
+
+    def permitted_attributes_for_create
+      %i[title body featured internal_notes]  # More fields
+    end
+
+    relation_scope do |relation|
+      relation  # No restrictions for admins
+    end
+  end
+end
+```
+
+## Custom Authorization Context
+
+Add custom context using ActionPolicy's `authorize` directive:
+
+```ruby
+# In policy
+class PostPolicy < Plutonium::Resource::Policy
+  authorize :department, allow_nil: true
+
+  def create?
+    department&.allows_posting?
+  end
+end
+
+# In controller
+class PostsController < ResourceController
+  authorize :department, through: :current_department
+
+  private
+
+  def current_department
+    current_user.department
+  end
+end
+```
+
+## Authorization Errors
+
+When authorization fails:
+
+```ruby
+# Raises ActionPolicy::Unauthorized
+```
+
+### Handling Errors
+
+```ruby
+# app/controllers/application_controller.rb
+rescue_from ActionPolicy::Unauthorized do |exception|
+  redirect_to root_path, alert: "Not authorized"
+end
+```
+
+## Common Patterns
+
+### Role-Based
+
+```ruby
+def update?
+  case user.role
+  when 'admin' then true
+  when 'editor' then true
+  when 'author' then owner?
+  else false
+  end
+end
+```
+
+### Status-Based
+
+```ruby
+def update?
+  return false if record.archived?
+  owner? || admin?
+end
+```
+
+### Time-Based
+
+```ruby
+def update?
+  return false if record.created_at < 24.hours.ago
+  owner?
+end
+```
+
+### Hierarchical
+
+```ruby
+def read?
+  return true if admin?
+  return true if manager_of_department?
+  return true if owner?
+  record.public?
+end
+```
+
+## Debugging
+
+### Logging
+
+```ruby
+def update?
+  result = owner? || admin?
+  Rails.logger.debug { "PostPolicy#update? user=#{user.id} post=#{record.id}: #{result}" }
+  result
+end
+```
+
+### Console Testing
+
+```ruby
+user = User.find(1)
+post = Post.find(1)
+
+# Use ActionPolicy's testing helpers
+policy = PostPolicy.new(post, user: user)
+policy.update?
+policy.permitted_attributes_for_update
+```
+
+## Best Practices
+
+1. **Always override `create?` and `read?`** - They default to `false`
+2. **Define attributes explicitly** - Auto-detection only works in development
+3. **Call `super` in `relation_scope`** - Preserves entity scoping
+4. **Use derived methods** - Let `update?` inherit from `create?` when appropriate
+5. **Keep policies focused** - Authorization logic only, no business logic
+6. **Test edge cases** - Archived records, nil associations, role combinations
+
+## Related
+
+- [Multi-tenancy Guide](/guides/multi-tenancy)
+- [ActionPolicy Documentation](https://actionpolicy.evilmartians.io/)