plutonium 0.37.0 → 0.39.0

data/docs/guides/custom-actions.md

@@ -39,6 +39,20 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
+::: warning Always Name Custom Routes
+When adding custom routes for actions, always use the `as:` option:
+
+```ruby
+resources :posts do
+  collection do
+    get :reports, as: :reports  # Named route required!
+  end
+end
+```
+
+This ensures `resource_url_for` can generate correct URLs, especially for nested resources.
+:::
+
 **Note:** For custom operations with business logic, use Interactive Actions with an Interaction class.
 
 ## Interactive Actions with Interactions

data/docs/guides/index.md

@@ -27,6 +27,10 @@ These guides show you how to accomplish specific tasks, with complete examples.
 
 - [Theming](./theming) - Customize colors, styles, and branding
 
+### Help
+
+- [Troubleshooting](./troubleshooting) - Common issues and solutions
+
 ## Finding What You Need
 
 | I want to... | Guide |
@@ -39,6 +43,7 @@ These guides show you how to accomplish specific tasks, with complete examples.
 | Separate data by company | [Multi-tenancy](./multi-tenancy) |
 | Add search to a list | [Search and Filtering](./search-filtering) |
 | Change the color scheme | [Theming](./theming) |
+| Fix a confusing error | [Troubleshooting](./troubleshooting) |
 
 ## Looking for Reference Docs?
 

data/docs/guides/nested-resources.md

@@ -4,7 +4,7 @@ This guide covers setting up parent/child resource relationships.
 
 ## Overview
 
-Nested resources create URLs like `/posts/1/comments` where comments belong to a specific post. Plutonium automatically handles:
+Nested resources create URLs like `/posts/1/nested_comments` where comments belong to a specific post. Plutonium automatically handles:
 
 - Scoping queries to the parent
 - Assigning parent to new records
@@ -12,6 +12,8 @@ Nested resources create URLs like `/posts/1/comments` where comments belong to a
 - URL generation with parent context
 - Breadcrumb navigation
 
+Plutonium supports both `has_many` (plural routes) and `has_one` (singular routes) associations.
+
 ## Setting Up Nested Resources
 
 ### 1. Define the Association
@@ -20,12 +22,17 @@ Nested resources create URLs like `/posts/1/comments` where comments belong to a
 # Parent model
 class Post < ResourceRecord
   has_many :comments, dependent: :destroy
+  has_one :post_metadata, dependent: :destroy
 end
 
-# Child model
+# Child models
 class Comment < ResourceRecord
   belongs_to :post
 end
+
+class PostMetadata < ResourceRecord
+  belongs_to :post
+end
 ```
 
 ### 2. Register Both Resources
@@ -35,15 +42,25 @@ end
 AdminPortal::Engine.routes.draw do
   register_resource ::Post
   register_resource ::Comment
+  register_resource ::PostMetadata
 end
 ```
 
-Plutonium automatically creates nested routes based on the `belongs_to` association:
-- `GET /posts/:post_id/comments`
-- `GET /posts/:post_id/comments/new`
-- `GET /posts/:post_id/comments/:id`
+Plutonium automatically creates nested routes with a `nested_` prefix based on the `belongs_to` association:
+
+**has_many routes (plural):**
+- `GET /posts/:post_id/nested_comments`
+- `GET /posts/:post_id/nested_comments/new`
+- `GET /posts/:post_id/nested_comments/:id`
 - etc.
 
+**has_one routes (singular):**
+- `GET /posts/:post_id/nested_post_metadata`
+- `GET /posts/:post_id/nested_post_metadata/new`
+- `GET /posts/:post_id/nested_post_metadata/edit`
+
+The `nested_` prefix prevents route conflicts when the same resource is registered both as a top-level and nested resource.
+
 ### 3. Enable Association Panel
 
 Show comments on the post detail page:
@@ -112,30 +129,46 @@ parent_input_param  # => :post
 Use `resource_url_for` with the `parent:` option:
 
 ```ruby
-# Child collection
+# Child collection (has_many)
 resource_url_for(Comment, parent: @post)
-# => /posts/123/comments
+# => /posts/123/nested_comments
 
 # Child record
 resource_url_for(@comment, parent: @post)
-# => /posts/123/comments/456
+# => /posts/123/nested_comments/456
 
 # New child form
 resource_url_for(Comment, action: :new, parent: @post)
-# => /posts/123/comments/new
+# => /posts/123/nested_comments/new
 
 # Edit child
 resource_url_for(@comment, action: :edit, parent: @post)
-# => /posts/123/comments/456/edit
+# => /posts/123/nested_comments/456/edit
+
+# Singular resource (has_one)
+resource_url_for(@post_metadata, parent: @post)
+# => /posts/123/nested_post_metadata
+
+resource_url_for(PostMetadata, action: :new, parent: @post)
+# => /posts/123/nested_post_metadata/new
 ```
 
 Within a nested context, `parent:` defaults to `current_parent`:
 
 ```ruby
-# In CommentsController under /posts/:post_id/comments
+# In CommentsController under /posts/:post_id/nested_comments
 resource_url_for(@comment)  # parent: current_parent is automatic
 ```
 
+### Cross-Package URL Generation
+
+Generate URLs for resources in a different package:
+
+```ruby
+# From AdminPortal, generate URL to CustomerPortal resource
+resource_url_for(@comment, parent: @post, package: CustomerPortal)
+```
+
 ## Presentation Hooks
 
 Control whether the parent field appears:
@@ -167,23 +200,47 @@ The parent is authorized for `:read?` before being returned:
 authorize! parent, to: :read?
 ```
 
-### Entity Scope Context
+### Parent Scoping Context
 
-The parent is passed to child policies as `entity_scope`:
+For nested resources, policies receive `parent` and `parent_association` context. This is used for automatic query scoping:
 
 ```ruby
 class CommentPolicy < ResourcePolicy
-  def create?
-    # entity_scope is the parent post
-    entity_scope.present? && user.can_comment_on?(entity_scope)
-  end
+  # Available context:
+  # - parent: the parent record (e.g., Post instance)
+  # - parent_association: the association name (e.g., :comments)
+  # - entity_scope: the scoped entity (for multi-tenancy)
 
-  def update?
-    record.user_id == user.id
+  relation_scope do |relation|
+    relation = super(relation)  # Applies parent scoping automatically
+    relation
   end
+end
+```
 
-  def destroy?
-    record.user_id == user.id || entity_scope&.user_id == user.id
+**Parent scoping takes precedence over entity scoping** - when a parent is present, the policy scopes via the parent association rather than the entity scope. This prevents double-scoping since the parent was already authorized and entity-scoped.
+
+### has_many vs has_one Scoping
+
+For **has_many** associations, scoping uses the association directly:
+```ruby
+parent.send(parent_association)  # e.g., post.comments
+```
+
+For **has_one** associations, scoping uses a where clause:
+```ruby
+relation.where(foreign_key => parent.id)  # e.g., where(post_id: post.id)
+```
+
+### Entity Scope Fallback
+
+When no parent is present (top-level resource access), entity_scope is used:
+
+```ruby
+class CommentPolicy < ResourcePolicy
+  def create?
+    # entity_scope is available for multi-tenancy
+    entity_scope.present? && user.can_comment_on?(entity_scope)
   end
 end
 ```
@@ -195,7 +252,7 @@ Add role-based filtering on top of parent scoping:
 ```ruby
 class CommentPolicy < ResourcePolicy
   relation_scope do |relation|
-    relation = super(relation)  # Applies associated_with(entity_scope)
+    relation = super(relation)  # Applies parent scoping first
 
     if user.moderator?
       relation
@@ -206,6 +263,33 @@ class CommentPolicy < ResourcePolicy
 end
 ```
 
+### default_relation_scope is Required
+
+Plutonium verifies that `default_relation_scope` is called in every `relation_scope` to prevent multi-tenancy leaks:
+
+```ruby
+# ❌ This will raise an error
+relation_scope do |relation|
+  relation.where(approved: true)  # Missing default_relation_scope!
+end
+
+# ✅ Correct
+relation_scope do |relation|
+  default_relation_scope(relation).where(approved: true)
+end
+```
+
+When overriding an inherited scope but still wanting parent scoping:
+
+```ruby
+class AdminCommentPolicy < CommentPolicy
+  relation_scope do |relation|
+    # Replace inherited scope but keep parent scoping
+    default_relation_scope(relation)
+  end
+end
+```
+
 ## Association Panels
 
 Associations listed in `permitted_associations` appear on the parent's show page:
@@ -257,15 +341,34 @@ class PostPolicy < ResourcePolicy
 end
 ```
 
+## has_one Associations
+
+Plutonium supports `has_one` associations with singular routes:
+
+```ruby
+class Post < ResourceRecord
+  has_one :post_metadata, dependent: :destroy
+end
+```
+
+Routes generated:
+- `GET /posts/:post_id/nested_post_metadata` - Show metadata
+- `GET /posts/:post_id/nested_post_metadata/new` - New metadata form
+- `GET /posts/:post_id/nested_post_metadata/edit` - Edit metadata form
+- `PATCH /posts/:post_id/nested_post_metadata` - Update metadata
+- `DELETE /posts/:post_id/nested_post_metadata` - Delete metadata
+
+Note: No `:id` parameter in singular routes - only one record can exist per parent.
+
 ## Nesting Depth
 
 Plutonium supports **one level of nesting**:
 
-- `/posts/:post_id/comments` (parent → child)
-- `/comments/:comment_id/replies` (parent → child)
+- `/posts/:post_id/nested_comments` (parent → child)
+- `/comments/:comment_id/nested_replies` (parent → child)
 
 Not supported:
-- `/posts/:post_id/comments/:comment_id/replies` (grandparent → parent → child)
+- `/posts/:post_id/nested_comments/:comment_id/nested_replies` (grandparent → parent → child)
 
 ### Working with Deep Hierarchies
 
@@ -285,19 +388,23 @@ Add member/collection routes:
 ```ruby
 register_resource ::Comment do
   member do
-    post :approve
-    post :flag
+    post :approve, as: :approve
+    post :flag, as: :flag
   end
   collection do
-    get :pending
+    get :pending, as: :pending
   end
 end
 ```
 
+::: warning Always Name Custom Routes
+Always use the `as:` option when defining custom routes. This ensures `resource_url_for` can generate correct URLs. Without named routes, URL generation will fail for nested resources.
+:::
+
 Generates nested routes:
-- `POST /posts/:post_id/comments/:id/approve`
-- `POST /posts/:post_id/comments/:id/flag`
-- `GET /posts/:post_id/comments/pending`
+- `POST /posts/:post_id/nested_comments/:id/approve`
+- `POST /posts/:post_id/nested_comments/:id/flag`
+- `GET /posts/:post_id/nested_comments/pending`
 
 ## Breadcrumbs
 

data/docs/guides/troubleshooting.md

@@ -0,0 +1,82 @@
+# Troubleshooting
+
+Common issues and their solutions when working with Plutonium.
+
+## Resource Class Detection
+
+### "Failed to determine the resource class" Error
+
+**Error messages:**
+```
+NameError: Failed to determine the resource class for MyPortal::PostMetadataController.
+Rails singularized "PostMetadata" to "PostMetadatum", but "PostMetadata" exists.
+Add an inflection rule to config/initializers/inflections.rb.
+```
+
+or:
+
+```
+NameError: Failed to determine the resource class.
+Please call `controller_for(MyResource)` in MyPortal::MyResourceController.
+```
+
+**Cause:** Plutonium infers the resource class from the controller name by singularizing it. For resources with names that don't follow standard Rails pluralization (like `PostMetadata`), Rails may singularize incorrectly (`PostMetadata` → `PostMetadatum`). Plutonium detects this and provides a helpful error message.
+
+**Solution:** Add a custom inflection rule in `config/initializers/inflections.rb`:
+
+```ruby
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  # Preserve "Metadata" when singularizing (e.g., PostMetadata stays PostMetadata)
+  inflect.singular(/(M)etadata$/i, '\1etadata')
+end
+```
+
+This ensures Rails correctly handles the singularization throughout your application, including:
+- Controller to model resolution
+- Route generation
+- Association lookups
+
+**Alternative:** If you can't modify inflections, explicitly set the resource class in your controller:
+
+```ruby
+class MyPortal::PostMetadataController < MyPortal::ResourceController
+  controller_for Blogging::PostMetadata
+end
+```
+
+### Common Words Needing Inflection Rules
+
+| Word | Without Rule | With Rule | Inflection |
+|------|--------------|-----------|------------|
+| Metadata | `PostMetadatum` | `PostMetadata` | `inflect.singular(/(M)etadata$/i, '\1etadata')` |
+| Media | `PostMedium` | `PostMedia` | `inflect.singular(/(M)edia$/i, '\1edia')` |
+| Data | `PostDatum` | `PostData` | `inflect.singular(/(D)ata$/i, '\1ata')` |
+| Criteria | `SearchCriterium` | `SearchCriteria` | `inflect.singular(/(C)riteria$/i, '\1riteria')` |
+
+## URL Generation
+
+### Wrong URLs for Nested Resources
+
+**Symptom:** URLs for nested resources include unexpected IDs or route to the wrong path.
+
+**Cause:** Rails "param recall" fills in missing parameters from the current request when generating URLs. This can cause issues when both top-level and nested routes exist for the same resource.
+
+**Solution:** Plutonium handles this automatically by using named route helpers for nested resources. Ensure you're using `resource_url_for` instead of `url_for`:
+
+```ruby
+# Good - uses Plutonium's smart URL generation
+resource_url_for(@comment, parent: @post)
+
+# May have issues with param recall
+url_for(controller: 'comments', action: 'show', id: @comment.id)
+```
+
+## Need More Help?
+
+If you encounter an issue not covered here, please [open an issue](https://github.com/radioactive-labs/plutonium-core/issues) on GitHub.
+
+## Related
+
+- [Nested Resources Guide](./nested-resources)
+- [Adding Resources Guide](./adding-resources)
+- [Rails Inflections Documentation](https://api.rubyonrails.org/classes/ActiveSupport/Inflector/Inflections.html)

data/docs/og-image.html

@@ -0,0 +1,84 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    body {
+      width: 1200px;
+      height: 630px;
+      background: #1e2330;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    }
+
+    .container {
+      display: flex;
+      flex-direction: row;
+      align-items: center;
+      gap: 60px;
+    }
+
+    .logo {
+      width: 260px;
+      height: 260px;
+      object-fit: contain;
+    }
+
+    .content {
+      display: flex;
+      flex-direction: column;
+      gap: 16px;
+    }
+
+    .title {
+      font-size: 88px;
+      font-weight: 700;
+      color: #ffffff;
+      letter-spacing: -1px;
+    }
+
+    .tagline {
+      font-size: 40px;
+      color: #b8bcc8;
+      font-weight: 400;
+    }
+
+    .features {
+      display: flex;
+      gap: 24px;
+      margin-top: 12px;
+      font-size: 26px;
+      color: #e07c5a;
+      font-weight: 500;
+    }
+
+    .features span:not(:last-child)::after {
+      content: '·';
+      margin-left: 24px;
+      color: #e07c5a;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <img src="public/plutonium.png" alt="Plutonium" class="logo">
+    <div class="content">
+      <div class="title">Plutonium</div>
+      <div class="tagline">Build Rails Apps in Minutes, Not Days</div>
+      <div class="features">
+        <span>Convention-driven</span>
+        <span>AI-ready</span>
+        <span>Fully customizable</span>
+      </div>
+    </div>
+  </div>
+</body>
+</html>

data/docs/reference/controller/index.md

@@ -219,11 +219,15 @@ end
 # In portal routes or config/routes.rb
 register_resource Post do
   member do
-    post :publish
+    post :publish, as: :publish  # Always use as: option!
   end
 end
 ```
 
+::: warning Always Name Custom Routes
+Always use the `as:` option when defining custom routes. This ensures `resource_url_for` can generate correct URLs, especially for nested resources.
+:::
+
 ## Authorization
 
 ### Automatic Authorization
@@ -258,7 +262,7 @@ end
 Parent records are automatically resolved:
 
 ```ruby
-# Route: /users/:user_id/posts/:id
+# Route: /users/:user_id/nested_posts/:id
 class PostsController < ::ResourceController
   # current_parent returns the User
   # resource_record! returns the Post scoped to that User

data/docs/reference/definition/actions.md

@@ -39,6 +39,20 @@ class PostDefinition < Plutonium::Resource::Definition
 end
 ```
 
+::: warning Always Name Custom Routes
+When adding custom routes for actions, always use the `as:` option:
+
+```ruby
+resources :posts do
+  collection do
+    get :reports, as: :reports  # Named route required!
+  end
+end
+```
+
+This ensures `resource_url_for` can generate correct URLs, especially for nested resources.
+:::
+
 **Note:** For custom operations with business logic, use **Interactive Actions** with an Interaction class.
 
 ## Interactive Actions

data/docs/reference/definition/fields.md

@@ -232,6 +232,39 @@ column :status, align: :center  # Center
 column :amount, align: :end     # Right
 ```
 
+## Value Formatting
+
+Use `formatter` for simple value transformations without a full block:
+
+```ruby
+# Truncate long text
+column :description, formatter: ->(value) { value&.truncate(30) }
+
+# Format numbers
+column :price, formatter: ->(value) { "$%.2f" % value if value }
+
+# Transform values
+column :status, formatter: ->(value) { value&.humanize&.upcase }
+```
+
+The `formatter` option:
+- Receives the field value as its argument
+- Returns the transformed value for display
+- Works with `column` and `display` declarations
+- Is simpler than block syntax when you only need to transform the value
+
+**formatter vs block:** Use `formatter` when you only need the value. Use a block when you need access to the full record:
+
+```ruby
+# formatter - receives just the value
+column :name, formatter: ->(value) { value&.titleize }
+
+# block - receives the full record
+column :full_name do |record|
+  "#{record.first_name} #{record.last_name}"
+end
+```
+
 ## Nested Inputs
 
 Render inline forms for associated records. Requires `accepts_nested_attributes_for` on the model.

data/docs/reference/model/index.md

@@ -67,7 +67,7 @@ class Comment < ResourceRecord
 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.
+When both `Post` and `Comment` are registered in a portal, Plutonium automatically creates nested routes (`/posts/:post_id/nested_comments`). Queries are automatically scoped to the parent via the association.
 
 See the [Nested Resources Guide](/guides/nested-resources) for details.