plutonium 0.37.0 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 117694b8e7d907c2c28a78439aaf85d32c8a682fe220777a51152cef561b6a9d
-  data.tar.gz: f44605f40590d45730bf734f3cd9868d233c60dd9a25269f33e56957f7c7898a
+  metadata.gz: 1a3ade68b80487615f8ad46432edb306cde755d712e7222b11705427f9a283ca
+  data.tar.gz: 10e95e8c085c8b7229929f50517fce9d964a1ff2ca31b0ee20662ca863c88f47
 SHA512:
-  metadata.gz: bf00b14c0db29e36d7c85ef6069ff1a7eea4fa2a1db6c4acd3d1cca841852ead636f81dcd0ae147b4dd985958001d7ee906c60abd0e02428758e315e9383726d
-  data.tar.gz: e8d74bf2b18faf507d3b4f9b46c586a4bcc6fe02048b9bbc5abbdf173fee3017dbe8bde1ab6176f65347fea98caef0f662fde838f05cdf4fe244e8ad37efd8aa
+  metadata.gz: e4a5ac3024c168686c6c315d2d7fa280c708a7e807580a422cb20223b6ccf2f95e96876e6a56d9ca88ee8fcbb63cc906dba33ad02af73a62f167bd91431a1a08
+  data.tar.gz: a0644bf92081d308e0ef306d38168d63138864c54534fea161c20b9f2d79e8556914239dd3122854686e0fee140758f9aa49b2b9c72248a48868045405fffbd5

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

@@ -194,22 +194,45 @@ build_collection        # Build table component
 resource_url_for(@post)                    # URL for record
 resource_url_for(@post, action: :edit)     # Edit URL
 resource_url_for(Post)                     # Index URL
+
+# With parent (nested resources)
+resource_url_for(@comment, parent: @post)  # Nested URL
+resource_url_for(Comment, action: :new, parent: @post)
+
+# Cross-package URLs
+resource_url_for(@post, package: AdminPortal)
 ```
 
 ## Nested Resources
 
-Parent records are automatically resolved:
+Parent records are automatically resolved from routes with the `nested_` prefix:
 
 ```ruby
-# Route: /users/:user_id/posts/:id
+# Route: /users/:user_id/nested_posts/:id
 class PostsController < ::ResourceController
   # current_parent returns the User
+  # current_nested_association returns :posts
   # resource_record! returns the Post scoped to that User
 end
 ```
 
+### Key Methods for Nested Resources
+
+```ruby
+current_parent             # Parent record (e.g., User instance)
+current_nested_association # Association name (e.g., :posts)
+parent_route_param         # URL param (e.g., :user_id)
+parent_input_param         # Form param (e.g., :user)
+```
+
 Parent fields are automatically excluded from forms/displays. Override with presentation hooks (see above).
 
+### has_one Support
+
+For `has_one` associations, routes are singular:
+- `/users/:user_id/nested_profile` (no `:id` param)
+- Index redirects to show (or new if no record exists)
+
 ## Entity Scoping (Multi-tenancy)
 
 When a portal is scoped to an entity:

data/.claude/skills/plutonium-definition-fields/SKILL.md

@@ -321,6 +321,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
+```
+
 ### Custom Column Rendering
 
 Use a block to customize how a column value is displayed. The block receives the raw record:

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

@@ -5,7 +5,7 @@ description: Plutonium nested resources - parent/child routes, scoping, and URL
 
 # Nested Resources
 
-Plutonium automatically creates nested routes for `has_many` associations, scopes queries to the parent, and handles URL generation.
+Plutonium automatically creates nested routes for `has_many` and `has_one` associations, scopes queries to the parent, and handles URL generation.
 
 ## How It Works
 
@@ -15,12 +15,17 @@ When you register resources with parent-child relationships:
 # In portal routes
 register_resource ::Company
 register_resource ::Property  # has belongs_to :company
+register_resource ::CompanyProfile  # has belongs_to :company (has_one on 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
+Plutonium automatically creates nested routes with a `nested_` prefix:
+- `/companies/:company_id/nested_properties` - Properties scoped to company (has_many)
+- `/companies/:company_id/nested_properties/new` - New property for company
+- `/companies/:company_id/nested_properties/:id` - Property in company context
+- `/companies/:company_id/nested_company_profile` - Singular profile (has_one)
+- `/companies/:company_id/nested_company_profile/new` - New profile for company
+
+The `nested_` prefix prevents route conflicts when the same resource is registered both as a top-level and nested resource.
 
 ## Automatic Behavior
 
@@ -81,26 +86,45 @@ end
 
 ## Query Scoping
 
-Collections are automatically scoped to the parent via policies:
+Collections are automatically scoped to the parent via policies. The policy receives `parent` and `parent_association` context:
 
 ```ruby
 class PropertyPolicy < ResourcePolicy
+  # parent: the parent record (e.g., Company instance)
+  # parent_association: the association name (e.g., :properties)
+
   relation_scope do |relation|
-    relation = super(relation)  # Applies associated_with(entity_scope)
-    # entity_scope is the current_parent
+    relation = super(relation)  # Applies parent scoping automatically
     relation
   end
 end
 ```
 
-The `associated_with` scope finds records belonging to the parent:
+### How Parent Scoping Works
 
+For **has_many** associations, scoping uses the association directly:
 ```ruby
-# Automatic detection via belongs_to
-Property.associated_with(company)
-# => Property.where(company: company)
+# parent.properties => Company#properties
+parent.send(parent_association)
 ```
 
+For **has_one** associations, scoping uses a where clause:
+```ruby
+# Property.where(company_id: company.id) with limit
+relation.where(foreign_key => parent.id)
+```
+
+### Parent vs Entity Scope
+
+When a parent is present, parent scoping takes precedence over entity scoping:
+
+```ruby
+# With parent: scopes via parent association
+# Without parent: falls back to entity_scope (multi-tenancy)
+```
+
+This prevents double-scoping - the parent was already authorized and entity-scoped during its own authorization.
+
 ### Custom Association Scope
 
 For complex relationships, define a custom scope:
@@ -118,21 +142,37 @@ end
 Use `resource_url_for` with the `parent:` option:
 
 ```ruby
-# Child collection
+# Child collection (has_many)
 resource_url_for(Property, parent: company)
-# => /companies/123/properties
+# => /companies/123/nested_properties
 
 # Child record
 resource_url_for(property, parent: company)
-# => /companies/123/properties/456
+# => /companies/123/nested_properties/456
 
 # New child form
 resource_url_for(Property, action: :new, parent: company)
-# => /companies/123/properties/new
+# => /companies/123/nested_properties/new
 
 # Edit child
 resource_url_for(property, action: :edit, parent: company)
-# => /companies/123/properties/456/edit
+# => /companies/123/nested_properties/456/edit
+
+# Singular resource (has_one)
+resource_url_for(company_profile, parent: company)
+# => /companies/123/nested_company_profile
+
+resource_url_for(CompanyProfile, action: :new, parent: company)
+# => /companies/123/nested_company_profile/new
+```
+
+### Cross-Package URL Generation
+
+Generate URLs for resources in a different package:
+
+```ruby
+# From AdminPortal, generate URL to CustomerPortal resource
+resource_url_for(property, parent: company, package: CustomerPortal)
 ```
 
 ## Association Panels
@@ -192,12 +232,32 @@ resource_params
 
 You don't need to include hidden fields for the parent in forms.
 
+## has_one Associations
+
+Plutonium supports both `has_many` and `has_one` associations:
+
+```ruby
+class Company < ResourceRecord
+  has_many :properties           # Plural routes
+  has_one :company_profile       # Singular routes
+end
+```
+
+Routes generated:
+- `has_many`: `/companies/:id/nested_properties` (plural, with `:id` param)
+- `has_one`: `/companies/:id/nested_company_profile` (singular, no `:id` param)
+
+For has_one associations:
+- Index redirects to show (or new if no record exists)
+- Only one record can exist per parent
+- Forms don't show parent field (determined by URL)
+
 ## Nesting Limitations
 
 Plutonium supports **one level of nesting**:
 
-- ✅ `/companies/:company_id/properties` (parent → child)
-- ❌ `/companies/:company_id/properties/:property_id/units` (grandparent → parent → child)
+- ✅ `/companies/:company_id/nested_properties` (parent → child)
+- ❌ `/companies/:company_id/nested_properties/:property_id/nested_units` (grandparent → parent → child)
 
 ## Common Patterns
 

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

@@ -182,13 +182,13 @@ relation_scope do |relation|
 end
 ```
 
-### With Entity Scoping
+### With Parent Scoping (Nested Resources)
 
-Call `super` to preserve automatic entity scoping:
+For nested resources, call `super` to apply automatic parent scoping:
 
 ```ruby
 relation_scope do |relation|
-  relation = super(relation)  # Apply entity scope first
+  relation = super(relation)  # Applies parent scoping automatically
 
   if user.admin?
     relation
@@ -198,6 +198,71 @@ relation_scope do |relation|
 end
 ```
 
+**Parent scoping takes precedence over entity scoping.** When a parent is present:
+- For `has_many`: scopes via `parent.association_name`
+- For `has_one`: scopes via `where(foreign_key: parent.id)`
+
+### With Entity Scoping (Multi-tenancy)
+
+When no parent is present, `super` applies entity scoping:
+
+```ruby
+relation_scope do |relation|
+  relation = super(relation)  # Apply entity scope if no parent
+
+  if user.admin?
+    relation
+  else
+    relation.where(published: true)
+  end
+end
+```
+
+### default_relation_scope is Required
+
+Plutonium verifies that `default_relation_scope` is called in every `relation_scope`. This prevents accidental multi-tenancy leaks when overriding scopes.
+
+```ruby
+# ❌ This will raise an error
+relation_scope do |relation|
+  relation.where(published: true)  # Missing default_relation_scope!
+end
+
+# ✅ Correct - call default_relation_scope
+relation_scope do |relation|
+  default_relation_scope(relation).where(published: true)
+end
+
+# ✅ Also correct - super calls default_relation_scope
+relation_scope do |relation|
+  super(relation).where(published: true)
+end
+```
+
+When overriding an inherited scope:
+
+```ruby
+class AdminPostPolicy < PostPolicy
+  relation_scope do |relation|
+    # Replace inherited scope but keep Plutonium's parent/entity scoping
+    default_relation_scope(relation)
+  end
+end
+```
+
+### Skipping Default Scoping (Rare)
+
+If you intentionally need to skip scoping, call `skip_default_relation_scope!`:
+
+```ruby
+relation_scope do |relation|
+  skip_default_relation_scope!
+  relation  # No parent/entity scoping applied
+end
+```
+
+Consider using a separate portal instead of skipping scoping.
+
 ## Portal-Specific Policies
 
 Override policies per portal:
@@ -306,9 +371,31 @@ end
 Policies have access to:
 
 ```ruby
-user         # Current user (required)
-record       # The resource being authorized
-entity_scope # Current scoped entity (for multi-tenancy)
+user               # Current user (required)
+record             # The resource being authorized
+entity_scope       # Current scoped entity (for multi-tenancy)
+parent             # Parent record for nested resources (nil if not nested)
+parent_association # Association name on parent (e.g., :comments)
+```
+
+### Nested Resource Context
+
+For nested resources (e.g., `/posts/123/nested_comments`), the policy receives:
+
+```ruby
+class CommentPolicy < ResourcePolicy
+  def create?
+    # parent is the Post instance
+    # parent_association is :comments
+    parent.present? && user.can_comment_on?(parent)
+  end
+
+  relation_scope do |relation|
+    # super() uses parent and parent_association for scoping
+    relation = super(relation)
+    relation
+  end
+end
 ```
 
 ### Custom Context

data/CHANGELOG.md

@@ -1,3 +1,39 @@
+## [0.38.0] - 2026-01-25
+
+### 🚀 Features
+
+- *(core)* Handle ActionPolicy::Unauthorized for non-HTML formats
+- *(interactive_actions)* Add non-HTML response handlers for successful actions
+- *(routing)* Add has_one nested resource support
+- *(routing)* [**breaking**] Refactor nested resource URL generation with named route helpers
+- *(policy)* Add default_relation_scope method with verification
+- *(nested)* Use association names for nested resource titles and breadcrumbs
+
+### 🐛 Bug Fixes
+
+- Remove duplicate kv store controller and move improvements into original
+- *(filters)* Improve association filter class resolution
+- *(ui)* Improve dropdown positioning with viewport boundary
+- *(crud)* Use correct action attributes for form re-rendering on errors
+- *(form)* Distinguish empty vs not-submitted key-value store fields
+- *(controller)* Use existing record context for form param extraction
+
+### 📚 Documentation
+
+- *(definition)* Document formatter option for columns and displays
+- Cleanup review definition
+- Add troubleshooting guide for inflection issue
+- Update nested resource routes to use nested_ prefix
+
+### 🧪 Testing
+
+- Refactor tests to use real module implementations instead of mocks
+
+### ⚙️ Miscellaneous Tasks
+
+- Use chokidar to fix dev build cyclic dependency issues
+- Warn when running tests without Appraisal
+- Switch to yarn
 ## [0.37.0] - 2026-01-21
 
 ### 🚀 Features

data/CLAUDE.md

@@ -77,16 +77,16 @@ When working on JavaScript or CSS in `src/`:
 
 ```bash
 # Watch mode (rebuilds on changes to src/build/)
-npm run dev
+yarn dev
 
 # Production build (to app/assets/)
-npm run build
+yarn build
 ```
 
-- `npm run dev` - watches and rebuilds to `src/build/` for development
-- `npm run build` - compiles to `app/assets/` for release
+- `yarn dev` - watches and rebuilds to `src/build/` for development
+- `yarn build` - compiles to `app/assets/` for release
 
-**Always run `npm run dev`** in a terminal when working on frontend code.
+**Always run `yarn dev`** in a terminal when working on frontend code.
 
 ### Running Tests
 
@@ -114,10 +114,8 @@ Generators are in `lib/generators/pu/`. Test by:
 ### Documentation
 
 ```bash
-cd docs
-pnpm install
-pnpm dev          # Local preview at localhost:5173
-pnpm build        # Build for production
+yarn docs:dev      # Local preview at localhost:5173
+yarn docs:build    # Build for production
 ```
 
 ## Code Conventions
@@ -212,4 +210,4 @@ This:
 ### Update documentation
 1. Edit files in `docs/`
 2. If user-facing behavior, update relevant skill in `.claude/skills/`
-3. Run `pnpm build` to verify no broken links
+3. Run `yarn docs:build` to verify no broken links

data/CONTRIBUTING.md

@@ -104,7 +104,7 @@ git push origin main --tags
 
 ```bash
 bundle install
-npm install
+yarn install
 ```
 
 ### Environment
@@ -123,10 +123,10 @@ Frontend source is in `src/`. When making JS or CSS changes:
 
 ```bash
 # Watch mode - keeps rebuilding as you edit
-npm run dev
+yarn dev
 
 # Production build - run before committing
-npm run build
+yarn build
 ```
 
 ### Running Tests
@@ -160,10 +160,8 @@ bin/dev
 ### Documentation
 
 ```bash
-cd docs
-pnpm install
-pnpm dev          # Preview at localhost:5173
-pnpm build        # Check for errors
+yarn docs:dev      # Preview at localhost:5173
+yarn docs:build    # Check for errors
 ```
 
 ### Changelog Generation (optional)
@@ -180,7 +178,7 @@ cargo install git-cliff  # via Rust
 2. Create a feature branch: `git checkout -b feat/my-feature`
 3. Make your changes with conventional commits
 4. Run tests: `bundle exec appraisal rake test`
-5. Build assets: `npm run build`
+5. Build assets: `yarn build`
 6. Push and create a pull request
 
 ## Questions?

data/Rakefile

@@ -8,7 +8,7 @@ Dir.glob("lib/tasks/**/*.rake").each { |r| load r }
 task default: %i[test standard]
 
 task :assets do
-  `npm run build`
+  `yarn build`
 end
 
 # https://stackoverflow.com/questions/15707940/rake-before-task-hook
@@ -20,3 +20,18 @@ Rake::TestTask.new do |t|
   t.test_files = FileList["test/**/*_test.rb"]
   t.verbose = true
 end
+
+# Warn users to run tests through Appraisal
+Rake::Task["test"].enhance do
+  # This runs after test completes successfully - no action needed
+end
+
+task :check_appraisal do
+  unless ENV["BUNDLE_GEMFILE"]&.include?("gemfiles/")
+    warn "\n⚠️  Tests should be run through Appraisal for the correct gem environment:"
+    warn "   bundle exec appraisal rails-8.1 rake test"
+    warn "   bundle exec appraisal rake test  # runs all Rails versions\n\n"
+  end
+end
+
+Rake::Task["test"].enhance [:check_appraisal]