plutonium 0.33.0 → 0.34.0

data/docs/guide/claude-code-guide.md

@@ -1,74 +0,0 @@
----
-title: Claude Code Guide for Plutonium Development
----
-
-<script setup>
-import { withBase } from 'vitepress'
-</script>
-
-# Claude Code Guide for Plutonium Development
-
-This page provides comprehensive development guidance for building Plutonium applications effectively. This guide is designed to help AI assistants and developers understand the framework's patterns and best practices.
-
-## Quick Start
-
-**Download the CLAUDE.md File**: <a :href="withBase('/CLAUDE.md')" target="_blank">📄 CLAUDE.md</a>
-
-**Or download directly from your terminal**:
-
-::: code-group
-
-```bash [Unix/Linux/macOS/WSL]
-curl -o CLAUDE.md https://radioactive-labs.github.io/plutonium-core/CLAUDE.md
-```
-
-```cmd [Windows]
-curl -o CLAUDE.md https://radioactive-labs.github.io/plutonium-core/CLAUDE.md
-```
-
-:::
-
-## Using This Guide
-
-Claude Code uses CLAUDE.md files for project-specific context:
-
-1. **Download the guide**: Right-click the link above and "Save As" to download the `CLAUDE.md` file
-2. **Place in your project root** as `CLAUDE.md`
-3. **Claude Code automatically loads** this file for project context
-4. **Enhance with your own instructions** by adding project-specific details
-
-The guide provides comprehensive patterns and examples for building Plutonium applications with AI assistance.
-
-## What's Included
-
-The CLAUDE.md guide contains comprehensive guidelines for:
-
-### 🏗️ **Framework Architecture**
-- Resource-oriented development patterns
-- Package architecture (Feature & Portal packages)
-- Component-based UI with Phlex
-- Business logic through Interactions
-
-### 📝 **Resource Development**
-- **Auto-detection philosophy** - Field types are automatically detected from models
-- **Definition patterns** - Only override when needed
-- **Policy-based authorization** - Fine-grained permissions
-- **Interaction-driven business logic** - Encapsulated operations
-
-### 🔧 **Development Patterns**
-- **Generator commands** for scaffolding
-- **Authentication setup** with Rodauth
-- **Multi-tenancy** with entity scoping
-- **Query objects** for filtering and search
-
-### 🎨 **UI Customization**
-- **Component architecture** with Phlex
-- **Custom display blocks** with `phlexi_tag`
-- **Conditional rendering** with context awareness
-- **Layout customization** patterns
-
-### ⚡ **Best Practices**
-- **Performance optimization** techniques
-- **Security guidelines** and defaults
-- **Code organization** principles
-- **Development workflow** recommendations

data/docs/guide/deep-dive/authorization.md

@@ -1,189 +0,0 @@
-# Deep Dive: Authorization
-
-Plutonium provides a robust authorization system built on top of [Action Policy](https://actionpolicy.evilmartians.io/). It's designed to be secure by default while offering fine-grained control over every aspect of your application's access control.
-
-## Core Principles
-
-Authorization in Plutonium is handled by **Policy** classes. Every resource should have a corresponding policy that inherits from `Plutonium::Resource::Policy`.
-
-A policy's primary job is to answer the question: "Can the current `user` perform this `action` on this `record`?"
-
-```ruby
-class PostPolicy < Plutonium::Resource::Policy
-  # Can the user see a list of posts?
-  def index?
-    true # Everyone can see the list
-  end
-
-  # Can the user update this specific post?
-  def update?
-    # `record` is the post instance.
-    # `user` is the current authenticated user.
-    record.author == user || user.admin?
-  end
-
-  # ... other permissions
-end
-```
-
-## Secure by Default: The Permission Chain
-
-Plutonium policies are secure by default. If a permission is not explicitly granted, it's denied. This is achieved through a clear inheritance chain.
-
-::: code-group
-```ruby [Core Permissions]
-# These are the base permissions.
-# They both default to `false`. You MUST override them.
-def create?
-  false
-end
-
-def read?
-  false
-end
-```
-```ruby [Derived Permissions]
-# These permissions inherit from the core ones.
-# You can override them for more granular control.
-def update?
-  create?
-end
-
-def destroy?
-  create?
-end
-
-def index?
-  read?
-end
-
-def show?
-  read?
-end
-```
-:::
-
-::: danger Always Define Core Permissions
-Because `create?` and `read?` default to `false`, you must define them in your policy to grant any access. If `create?` is `false`, then `update?` and `destroy?` will also be `false` unless you explicitly override them.
-:::
-
-## Attribute & Association Permissions
-
-Beyond actions, policies also control access to a resource's data at a granular level.
-
-### Attribute Permissions
-
-Attribute permissions control which fields a user can see or submit in a form. They follow a similar inheritance chain.
-
-::: code-group
-```ruby [Read Attributes]
-# Controls which fields are returned for `index` and `show` actions.
-def permitted_attributes_for_read
-  # By default, auto-detects all columns in development,
-  # but MUST be overridden for production.
-end
-```
-```ruby [Create/Update Attributes]
-# Controls which fields are allowed in `create` and `update` actions.
-def permitted_attributes_for_create
-  # By default, auto-detects columns (minus some system ones)
-  # in development, but MUST be overridden for production.
-end
-
-def permitted_attributes_for_update
-  # Inherits from `permitted_attributes_for_create` by default.
-  permitted_attributes_for_create
-end
-```
-:::
-
-::: warning Override in Production
-The default auto-detection for attributes only works in development to speed up initial scaffolding. You **must** override `permitted_attributes_for_create` and `permitted_attributes_for_read` in your policies for them to work in production.
-:::
-
-### Association Permissions
-
-By default, no associations are permitted. You must explicitly list which related resources can be included.
-
-```ruby
-class PostPolicy < Plutonium::Resource::Policy
-  def permitted_associations
-    [:comments, :author]
-  end
-end
-```
-
-## Scoping: Filtering Collections
-
-A policy's `relation_scope` is used to filter down a collection of records to only what the current user should see. This is applied automatically on `index` pages.
-
-::: code-group
-```ruby [Simple Scope]
-class PostPolicy < Plutonium::Resource::Policy
-  relation_scope do |relation|
-    if user.admin?
-      relation # Admins see all posts
-    else
-      # Others only see their own posts or published posts
-      relation.where(author: user).or(relation.where(published: true))
-    end
-  end
-end
-```
-```ruby [Multi-Tenant Scope]
-class PostPolicy < Plutonium::Resource::Policy
-  relation_scope do |relation|
-    # `super` applies the portal's entity scoping first
-    # e.g., `relation.associated_with(current_organization)`
-    relation = super(relation)
-
-    # Then, apply additional logic
-    if user.admin?
-      relation
-    else
-      relation.where(published: true)
-    end
-  end
-end
-```
-:::
-
-## Authorization Context
-
-Policies have access to a `context` object. By default, Plutonium provides two:
-
--   **`user`**: The current authenticated user. This is **required**.
--   **`entity_scope`**: The current portal's multi-tenancy record (e.g., the current `Organization`). This is optional.
-
-You can add your own custom context objects for more complex scenarios.
-
-::: details Adding Custom Context
-Imagine you have a separate `Ability` system that you also want to check.
-
-**1. Define the context in the Policy:**
-```ruby
-class PostPolicy < ResourcePolicy
-  authorize :ability, allow_nil: true
-
-  def promote?
-    # You can now use `ability` in your permission checks
-    user.admin? && ability&.can?(:promote, record)
-  end
-end
-```
-
-**2. Provide the context from the Controller:**
-```ruby
-class PostsController < ResourceController
-  # This tells the policy how to find the `ability` object.
-  authorize :ability, through: :current_ability
-
-  private
-
-  def current_ability
-    # Your custom logic to find the ability object
-    Ability.new(user)
-  end
-end
-```
-:::

data/docs/guide/deep-dive/multitenancy.md

@@ -1,256 +0,0 @@
-# Deep Dive: Multitenancy
-
-Plutonium is designed to make building sophisticated, multi-tenant applications straightforward. Multitenancy allows you to serve distinct groups of users (like different companies or teams) from a single application instance, ensuring each group's data is kept private and isolated.
-
-This is achieved through a powerful feature called **Entity Scoping**, which automates data isolation, URL generation, and authorization with minimal setup.
-
-::: tip What You'll Learn
-- The core concept of Entity Scoping
-- A step-by-step guide to configuring multitenancy
-- The practical benefits of automatic data isolation and routing
-- Advanced patterns for complex multi-tenant scenarios
-- Best practices for security, testing, and performance
-:::
-
-## How Entity Scoping Works
-
-Entity Scoping is the heart of Plutonium's multitenancy. Instead of manually filtering data in every controller and model, you declare a **Scoping Entity** for a user-facing **Portal**. This entity is typically a model like `Organization`, `Account`, or `Workspace`.
-
-Once configured, Plutonium handles the rest automatically.
-
-::: code-group
-```ruby [Without Plutonium Scoping]
-# Manual filtering is required everywhere
-class PostsController < ApplicationController
-  def index
-    # Manually find the organization and scope posts
-    @organization = Organization.find(params[:organization_id])
-    @posts = @organization.posts
-  end
-
-  def create
-    # Manually associate new records with the organization
-    @organization = Organization.find(params[:organization_id])
-    @post = @organization.posts.build(post_params)
-    # ...
-  end
-end
-```
-
-```ruby [With Plutonium Scoping]
-# Scoping is automatic and declarative
-class PostsController < ResourceController
-  def index
-    # current_authorized_scope automatically returns posts scoped to the current organization
-    # When using path strategy: URL -> /organizations/123/posts
-    # When using subdomain strategy: URL -> /posts (on acme.yourapp.com)
-  end
-
-  def create
-    # resource_params automatically includes the current organization association
-    # Scoping works regardless of the strategy used
-  end
-end
-```
-:::
-
-## Setting Up Your Multi-Tenant Portal
-
-Configuring multitenancy involves three main steps: defining your strategy, implementing it, and ensuring your models are correctly associated.
-
-### 1. Configure Your Portal Engine
-
-First, you tell your portal which entity to scope to and which strategy to use. This is done in the portal's `engine.rb` file using `scope_to_entity`.
-
-A **Scoping Strategy** tells Plutonium how to identify the current tenant for each request.
-
-::: code-group
-```ruby [Path Strategy (Most Common)]
-# packages/admin_portal/lib/engine.rb
-# Tenant is identified by a URL parameter, e.g., /organizations/:organization_id
-scope_to_entity Organization, strategy: :path
-```
-
-```ruby [Custom Strategy (Subdomain)]
-# packages/customer_portal/lib/engine.rb
-# Tenant is identified by the a custom strategy that checks the subdomain, e.g., acme.yourapp.com
-scope_to_entity Organization, strategy: :current_organization
-```
-
-```ruby [Custom Parameter Key]
-# packages/client_portal/lib/engine.rb
-# Same as :path, but with a custom parameter name.
-scope_to_entity Client,
-  strategy: :path,
-  param_key: :client_slug # URL -> /clients/:client_slug
-```
-:::
-
-You can also use any custom name for your strategy method (the method name becomes the strategy).
-
-### 2. Implement the Strategy Method
-
-If you use any strategy other than `:path`, you must implement a controller method that returns the current tenant object. The method name must exactly match the strategy name.
-
-This logic typically lives in your portal's base controller concern.
-
-::: code-group
-```ruby [Subdomain Strategy]
-# packages/customer_portal/app/controllers/customer_portal/concerns/controller.rb
-private
-
-# Method name :current_organization matches the strategy
-def current_organization
-  @current_organization ||= Organization.find_by!(subdomain: request.subdomain)
-rescue ActiveRecord::RecordNotFound
-  redirect_to root_path, error: "Invalid organization subdomain"
-end
-```
-
-```ruby [Session-Based Strategy]
-# packages/internal_portal/app/controllers/internal_portal/concerns/controller.rb
-# In engine.rb: scope_to_entity Workspace, strategy: :current_workspace
-private
-
-def current_workspace
-  return @current_workspace if defined?(@current_workspace)
-
-  workspace_id = session[:workspace_id] || params[:workspace_id]
-  @current_workspace = current_user.workspaces.find(workspace_id)
-
-  session[:workspace_id] = @current_workspace.id # Remember for next request
-  @current_workspace
-rescue ActiveRecord::RecordNotFound
-  redirect_to workspace_selection_path, error: "Please select a workspace"
-end
-```
-:::
-
-### 3. Connect Your Models
-
-Plutonium needs to understand how your resources relate to the scoping entity. It automatically discovers these relationships in three ways:
-
-::: code-group
-```ruby [1. Direct Association (Preferred)]
-# The model belongs directly to the scoping entity.
-class Post < ApplicationRecord
-  belongs_to :organization # Direct link
-end
-```
-
-```ruby [2. Indirect Association]
-# The model belongs to another model that has the direct link.
-# Plutonium automatically follows the chain: Comment -> Post -> Organization
-class Comment < ApplicationRecord
-  belongs_to :post
-  has_one :organization, through: :post # Indirect link
-end
-```
-
-```ruby [3. Custom Scope (For Complex Cases)]
-# For complex relationships, you can define an explicit scope.
-# The scope name must be `associated_with_#{scoping_entity_name}`.
-class Invoice < ApplicationRecord
-  belongs_to :customer
-
-  scope :associated_with_organization, ->(organization) do
-    joins(customer: :organization_memberships)
-      .where(organization_memberships: { organization_id: organization.id })
-  end
-end
-```
-:::
-
-## The Benefits in Practice
-
-With this setup complete, you gain several powerful features across your portal.
-
-### Tenant-Aware Routing
-
-Your application's URLs are automatically transformed to include the tenant context, and Plutonium's URL helpers adapt accordingly.
-
-- **URL Transformation:** Routes like `/posts` and `/posts/123` become `/:organization_id/posts` and `/:organization_id/posts/123`.
-- **Automatic URL Generation:** The `resource_url_for` helper automatically includes the current tenant in all generated URLs, so links and forms work without any changes.
-
-```ruby
-# Both of these helpers are automatically aware of the current tenant.
-resource_url_for(Post) # => "/organizations/456/posts"
-form_with model: @post # action -> "/organizations/456/posts/123"
-```
-
-### Secure Data Scoping
-
-All data access is automatically and securely filtered to the current tenant.
-
-- **Query Scoping:** A query like `Post.all` is automatically converted to `current_scoped_entity.posts`. This prevents accidental data leaks.
-- **Record Scoping:** When fetching a single record (e.g., for `show` or `edit`), Plutonium ensures it belongs to the current tenant. If not, it raises an `ActiveRecord::RecordNotFound` error, just as if the record didn't exist.
-
-### Integrated Authorization
-
-The current `entity_scope` is seamlessly passed to your authorization policies, allowing for fine-grained, tenant-aware rules.
-
-```ruby
-class PostPolicy < Plutonium::Resource::Policy
-  # `entity_scope` is automatically available in all policy methods.
-  authorize :entity_scope, allow_nil: true
-
-  def update?
-    # A user can only update a post if it belongs to their current tenant
-    # AND they are the author of the post.
-    record.organization == entity_scope && record.author == user
-  end
-
-  relation_scope do |relation|
-    # `super` automatically applies the base entity scoping.
-    relation = super(relation)
-
-    # Add more logic: Admins can see all posts within their organization,
-    # but others can only see published posts.
-    user.admin? ? relation : relation.where(published: true)
-  end
-end
-```
-
-## Security Best Practices
-
-Securing a multi-tenant application is critical. While Plutonium provides strong defaults, you must ensure your implementation is secure.
-
-::: warning Always Validate Tenant Access
-A user might belong to multiple tenants. It's crucial to verify that the logged-in user has permission to access the tenant specified in the URL. Failure to do so could allow a user to see data from another organization they don't belong to.
-:::
-
-```ruby
-# ✅ Good: Proper tenant validation
-# In your custom strategy method or a before_action:
-private
-
-def current_organization
-  @current_organization ||= begin
-    # Find the organization from the URL
-    organization = Organization.find(params[:organization_id])
-
-    # CRITICAL: Verify the current user is a member of that organization
-    unless current_user.organizations.include?(organization)
-      raise ActionPolicy::Unauthorized, "Access denied to organization"
-    end
-
-    organization
-  end
-end
-
-# ❌ Dangerous: No access validation
-def current_organization
-  # This allows ANY authenticated user to access ANY organization's data
-  # simply by changing the ID in the URL.
-  Organization.find(params[:organization_id])
-end
-```
-
-## Advanced Patterns
-
-Plutonium's scoping is flexible enough to handle more complex scenarios.
-
-- **Multi-Level Tenancy:** For hierarchical tenancy (e.g., Company -> Department), you can apply the primary scope at the engine level and add secondary scoping logic inside your policies' `relation_scope`.
-- **Cross-Tenant Data Access:** For resources that can be shared, define a custom `associated_with_...` scope that includes both shared records and records belonging to the current tenant.
-- **Tenant Switching:** Build a controller that allows users to change their active tenant by updating a `session` key, then use a session-based scoping strategy to read it.
-- **API Multitenancy:** Create a custom scoping strategy (e.g., `:api_tenant`) that authenticates and identifies the tenant based on an API key or JWT from the request headers.