plutonium 0.50.0 → 0.51.0

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

@@ -1,360 +0,0 @@
----
-name: plutonium-nested-resources
-description: Use BEFORE configuring parent/child resource relationships, nested routes, or scoped URL generation with resource_url_for(parent:).
----
-
-# Nested Resources
-
-## 🚨 Critical (read first)
-- **Use `pu:res:scaffold` + `pu:res:conn`** for both parent and child. Nested routes are generated from the `belongs_to` + association on the parent — no manual route wiring.
-- **Parent scoping beats entity scoping.** When a parent is present, `default_relation_scope` scopes via the parent, not via `entity_scope`. Don't double-scope in the policy.
-- **Plutonium supports one level of nesting.** Grandparent → parent → child nested routes are NOT supported. Use top-level routes for deeper relationships.
-- **Named custom routes only.** When adding member/collection routes on a nested resource, always pass `as:` — otherwise `resource_url_for` will fail.
-- **Related skills:** `plutonium-entity-scoping` (how parent scoping interacts with entity scoping), `plutonium-policy` (parent scoping in `relation_scope`), `plutonium-controller` (presentation hooks), `plutonium-portal` (route registration).
-
-**Always use generators** to create both parent and child resources, then connect them to portals:
-```bash
-rails g pu:res:scaffold Company name:string --dest=main_app
-rails g pu:res:scaffold Property company:belongs_to name:string --dest=main_app
-rails g pu:res:conn Company Property --dest=admin_portal
-```
-
-Plutonium automatically creates nested routes for `has_many` and `has_one` 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
-register_resource ::CompanyProfile  # has belongs_to :company (has_one on Company)
-```
-
-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
-
-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. 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 parent scoping automatically
-    relation
-  end
-end
-```
-
-### How Parent Scoping Works
-
-For **has_many** associations, scoping uses the association directly:
-```ruby
-# 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:
-
-```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 (has_many)
-resource_url_for(Property, parent: company)
-# => /companies/123/nested_properties
-
-# Child record
-resource_url_for(property, parent: company)
-# => /companies/123/nested_properties/456
-
-# New child form
-resource_url_for(Property, action: :new, parent: company)
-# => /companies/123/nested_properties/new
-
-# Edit child
-resource_url_for(property, action: :edit, parent: company)
-# => /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
-
-# Interactions (composes with parent — see plutonium-interaction skill)
-resource_url_for(property, parent: company, interaction: :archive)
-# => /companies/123/nested_properties/456/record_actions/archive
-
-resource_url_for(Property, parent: company, interaction: :import)
-# => /companies/123/nested_properties/resource_actions/import
-
-resource_url_for(Property, parent: company, interaction: :bulk_delete, ids: [1, 2])
-# => /companies/123/nested_properties/bulk_actions/bulk_delete?ids[]=1&ids[]=2
-```
-
-### 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
-
-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.
-
-## 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/nested_properties` (parent → child)
-- ❌ `/companies/:company_id/nested_properties/:property_id/nested_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, as: :analytics
-    post :archive, as: :archive
-  end
-end
-```
-
-**Important:** Always use the `as:` option to name custom routes. This ensures `resource_url_for` can generate correct URLs for nested resources. Without named routes, URL generation will fail.
-
-Generates nested routes:
-- `/companies/:company_id/nested_properties/:id/analytics`
-- `/companies/:company_id/nested_properties/:id/archive`
-
-## Related Skills
-
-- `plutonium-portal` - Route registration
-- `plutonium-policy` - Authorization and scoping
-- `plutonium-controller` - Presentation hooks
-- `plutonium-model` - associated_with scope

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

@@ -1,198 +0,0 @@
----
-name: plutonium-package
-description: Use BEFORE creating a feature package or portal package via pu:pkg:package / pu:pkg:portal, or organizing a Plutonium app into modular engines.
----
-
-# Plutonium Packages
-
-## 🚨 Critical (read first)
-- **Use the generators.** `pu:pkg:package` for feature packages, `pu:pkg:portal` for portal packages — never hand-write engine files or directory structures.
-- **Feature vs portal is a hard split.** Feature packages hold models/policies/definitions/interactions; portal packages hold controllers/views/routes/auth. Don't mix.
-- **Package classes are auto-namespaced** (`packages/blogging/app/models/blogging/post.rb` → `Blogging::Post`). Don't fight the namespacing.
-- **Cross-package resource references** use the full namespace: `rails g pu:res:conn Blogging::Post --dest=admin_portal`.
-- **Related skills:** `plutonium-portal` (portal-specific features), `plutonium-create-resource` (creating resources in packages), `plutonium-installation` (package loading).
-
-Packages are specialized Rails engines for organizing code. There are two types:
-
-| Type | Purpose | Generator |
-|------|---------|-----------|
-| **Feature** | Business logic (models, policies, interactions) | `rails g pu:pkg:package NAME` |
-| **Portal** | Web interface (controllers, views, auth) | `rails g pu:pkg:portal NAME` |
-
-## Feature Packages
-
-Contain domain logic without web interface:
-
-```bash
-rails g pu:pkg:package blogging
-```
-
-### Structure
-
-```
-packages/blogging/
-├── app/
-│   ├── models/blogging/
-│   │   ├── post.rb
-│   │   └── comment.rb
-│   ├── definitions/blogging/
-│   │   ├── post_definition.rb
-│   │   └── comment_definition.rb
-│   ├── policies/blogging/
-│   │   ├── post_policy.rb
-│   │   └── comment_policy.rb
-│   └── interactions/blogging/
-│       └── publish_post_interaction.rb
-├── db/migrate/
-└── lib/
-    └── engine.rb
-```
-
-### Engine
-
-```ruby
-module Blogging
-  class Engine < Rails::Engine
-    include Plutonium::Package::Engine
-  end
-end
-```
-
-### Namespacing
-
-All classes are auto-namespaced:
-- `app/models/blogging/post.rb` → `Blogging::Post`
-- `app/policies/blogging/post_policy.rb` → `Blogging::PostPolicy`
-
-## Portal Packages
-
-Provide web interfaces for specific user types:
-
-```bash
-rails g pu:pkg:portal admin
-rails g pu:pkg:portal dashboard
-```
-
-### Structure
-
-```
-packages/admin_portal/
-├── app/
-│   ├── controllers/admin_portal/
-│   │   ├── concerns/controller.rb
-│   │   ├── dashboard_controller.rb
-│   │   ├── plutonium_controller.rb
-│   │   └── resource_controller.rb
-│   ├── definitions/admin_portal/     # Portal-specific overrides
-│   ├── policies/admin_portal/        # Portal-specific overrides
-│   └── views/
-│       └── layouts/admin_portal.html.erb
-├── config/
-│   └── routes.rb
-└── lib/
-    └── engine.rb
-```
-
-### Engine
-
-```ruby
-module AdminPortal
-  class Engine < Rails::Engine
-    include Plutonium::Portal::Engine
-
-    config.after_initialize do
-      # Optional: multi-tenancy
-      scope_to_entity Organization, strategy: :path
-    end
-  end
-end
-```
-
-See `plutonium-portal` skill for portal-specific features.
-
-## Package Loading
-
-Packages are loaded via `config/packages.rb`:
-
-```ruby
-# config/packages.rb (generated during install)
-Dir.glob(File.expand_path("../packages/**/lib/engine.rb", __dir__)) do |package|
-  load package
-end
-```
-
-This is required in `config/application.rb`.
-
-## Creating Resources in Packages
-
-```bash
-# In main app
-rails g pu:res:scaffold Post title:string --dest=main_app
-
-# In feature package
-rails g pu:res:scaffold Blogging::Post title:string --dest=blogging
-```
-
-## Connecting Resources to Portals
-
-Resources must be connected to portals to be accessible:
-
-```bash
-rails g pu:res:conn Post --dest=admin_portal
-rails g pu:res:conn Blogging::Post --dest=admin_portal
-```
-
-This creates:
-- Portal-specific controller
-- Portal-specific policy (optional)
-- Portal-specific definition (optional)
-- Route registration
-
-## When to Use Each Type
-
-### Feature Packages
-
-Use for:
-- Domain-specific models and logic
-- Reusable business functionality
-- Shared code across portals
-
-Examples: `blogging`, `billing`, `inventory`, `user_management`
-
-### Portal Packages
-
-Use for:
-- User-facing interfaces
-- Role-specific access (admin, customer, public)
-- Different authentication requirements
-
-Examples: `admin_portal`, `dashboard_portal`, `public_portal`, `api_portal`
-
-## Typical Architecture
-
-```
-packages/
-├── blogging/              # Feature: blog functionality
-│   └── models, definitions, policies
-├── billing/               # Feature: payment/invoicing
-│   └── models, definitions, policies
-├── admin_portal/          # Portal: admin interface
-│   └── controllers, views, routes
-└── dashboard_portal/      # Portal: user dashboard
-    └── controllers, views, routes
-```
-
-## Migration Integration
-
-Package migrations are automatically integrated:
-
-```bash
-rails db:migrate  # Runs migrations from all packages
-```
-
-## Related Skills
-
-- `plutonium-portal` - Portal-specific features (auth, entity scoping, routes)
-- `plutonium` - Resource architecture overview
-- `plutonium-portal` - Connecting resources to portals
-- `plutonium-create-resource` - Creating resources