plutonium 0.50.0 → 0.51.0

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

@@ -1,396 +0,0 @@
----
-name: plutonium-controller
-description: Use BEFORE overriding a controller action, adding a hook, or changing redirect logic in a Plutonium controller. Also when customizing resource_params or presentation hooks.
----
-
-# Plutonium Controllers
-
-## 🚨 Critical (read first)
-- **Use generators.** `pu:res:scaffold` and `pu:res:conn` create controllers — never hand-write them.
-- **Don't override CRUD actions.** Customize via hooks (`resource_params`, `redirect_url_after_submit`, `preferred_action_after_submit`, presentation hooks). Overriding `create`/`update` usually breaks authorization, params filtering, or both.
-- **Prefer definitions and interactions.** UI config belongs in definitions; business logic belongs in interactions. The controller is thin by design.
-- **Named custom routes.** When adding custom member/collection routes, always use `as:` so `resource_url_for` can build URLs — especially for nested resources.
-- **Related skills:** `plutonium-definition` (interactive actions instead of controller actions), `plutonium-policy` (authorization), `plutonium-nested-resources` (parent/child routing), `plutonium-views` (custom page classes).
-
-**Controllers are generated automatically** - never create them manually:
-- `rails g pu:res:scaffold` creates the base controller
-- `rails g pu:res:conn` creates portal-specific controllers
-
-Controllers in Plutonium provide full CRUD functionality out of the box. You rarely need to customize them - definitions handle most UI configuration and policies handle authorization.
-
-## Base Classes
-
-```ruby
-# app/controllers/resource_controller.rb (generated during install)
-class ResourceController < ApplicationController
-  include Plutonium::Resource::Controller
-end
-
-# app/controllers/posts_controller.rb (generated per resource)
-class PostsController < ::ResourceController
-  # Empty - all CRUD actions inherited
-end
-```
-
-## What You Get for Free
-
-Every resource controller automatically provides:
-
-| Action | Route | Purpose |
-|--------|-------|---------|
-| `index` | GET /posts | List with pagination, search, filters, sorting |
-| `show` | GET /posts/:id | Display single record |
-| `new` | GET /posts/new | New record form |
-| `create` | POST /posts | Create record |
-| `edit` | GET /posts/:id/edit | Edit record form |
-| `update` | PATCH /posts/:id | Update record |
-| `destroy` | DELETE /posts/:id | Delete record |
-
-Plus interactive action routes for custom operations defined in definitions.
-
-## When to Customize
-
-**Use Definitions for:**
-- Field configuration (inputs, displays, columns)
-- Search, filters, scopes, sorting
-- Actions (interactive operations)
-- Form customization
-
-**Customize Controller for:**
-- Custom redirect logic
-- Special parameter processing
-- Non-standard authorization flows
-- External integrations
-- Response format changes
-
-## Override Hooks
-
-All customization is done by overriding private methods:
-
-### Redirect Hooks
-
-```ruby
-class PostsController < ::ResourceController
-  private
-
-  # Where to go after create/update: "show" (default), "edit", "new", "index"
-  def preferred_action_after_submit
-    "edit"
-  end
-
-  # Custom URL after create/update (overrides preferred_action_after_submit)
-  def redirect_url_after_submit
-    posts_path
-  end
-
-  # Custom URL after destroy
-  def redirect_url_after_destroy
-    posts_path
-  end
-end
-```
-
-### Parameter Hooks
-
-```ruby
-class PostsController < ::ResourceController
-  private
-
-  # Modify params before create/update
-  def resource_params
-    params = super
-    params[:tags] = params[:tags].split(",") if params[:tags].is_a?(String)
-    params
-  end
-end
-```
-
-### Query Hooks
-
-```ruby
-class PostsController < ::ResourceController
-  private
-
-  # Customize the index query
-  def filtered_resource_collection
-    base = current_authorized_scope
-    base = base.featured if params[:featured]
-    current_query_object.apply(base, raw_resource_query_params)
-  end
-end
-```
-
-### Presentation Hooks
-
-Control whether parent/entity fields appear in forms and displays:
-
-```ruby
-class PostsController < ::ResourceController
-  private
-
-  # Show parent field in displays (default: false)
-  def present_parent?
-    true
-  end
-
-  # Include parent field in forms (default: same as present_parent?)
-  def submit_parent?
-    true
-  end
-
-  # Show scoped entity in displays (default: false)
-  def present_scoped_entity?
-    true
-  end
-
-  # Include scoped entity in forms (default: same as present_scoped_entity?)
-  def submit_scoped_entity?
-    true
-  end
-end
-```
-
-## Custom Actions
-
-```ruby
-class PostsController < ::ResourceController
-  def publish
-    authorize_current!(resource_record!, to: :publish?)
-    resource_record!.update!(published: true)
-    redirect_to resource_url_for(resource_record!), notice: "Published!"
-  end
-end
-```
-
-**Important:** When adding custom routes, always use the `as:` option to name them:
-
-```ruby
-# config/routes.rb or portal routes
-resources :posts do
-  member do
-    post :publish, as: :publish  # Named route required!
-  end
-end
-```
-
-This ensures `resource_url_for` can generate correct URLs, especially for nested resources.
-
-Note: For most custom operations, use Interactive Actions in definitions instead.
-
-## Key Methods
-
-### Resource Access
-
-```ruby
-resource_class          # The model class (e.g., Post)
-resource_record!        # Current record (raises if not found)
-resource_record?        # Current record (nil if not found)
-resource_params         # Permitted params for create/update
-current_parent          # Parent record for nested routes
-```
-
-### Authorization
-
-```ruby
-authorize_current!(record, to: :action?)  # Check permission
-current_policy                            # Policy for current resource
-permitted_attributes                      # Allowed attributes for action
-current_authorized_scope                  # Scoped records user can access
-```
-
-### Definition Access
-
-```ruby
-current_definition      # Definition for current resource
-```
-
-### UI Building
-
-```ruby
-build_form              # Build form component
-build_detail            # Build show/detail component
-build_collection        # Build table component
-```
-
-### URL Generation
-
-```ruby
-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 from routes with the `nested_` prefix:
-
-```ruby
-# 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:
-
-```ruby
-# packages/admin_portal/lib/engine.rb
-module AdminPortal
-  class Engine < Rails::Engine
-    include Plutonium::Portal::Engine
-
-    config.after_initialize do
-      scope_to_entity Organization, strategy: :path
-    end
-  end
-end
-```
-
-Controllers automatically:
-- Scope all queries to the entity
-- Exclude entity field from forms (detected by association class)
-- Inject entity value on create/update
-- Provide `current_scoped_entity` method
-
-### Association Detection
-
-Plutonium auto-detects which `belongs_to` association points to the scoped entity class. This works even when `param_key` differs from the association name:
-
-```ruby
-# Portal config
-scope_to_entity Competition::Team, param_key: :team
-
-# Model (association name differs from param_key)
-class Match < ApplicationRecord
-  belongs_to :competition_team  # Plutonium finds this by class
-end
-```
-
-### Multiple Associations to Same Class
-
-If a model has multiple associations to the scoped entity class, Plutonium raises an error:
-
-```
-Match has multiple associations to Competition::Team: home_team, away_team.
-Plutonium cannot auto-detect which one to use for entity scoping.
-Override `scoped_entity_association` in your controller to specify the association.
-```
-
-Resolve by overriding `scoped_entity_association`:
-
-```ruby
-class MatchesController < ::ResourceController
-  private
-
-  def scoped_entity_association
-    :home_team  # Return the association name as a symbol
-  end
-end
-```
-
-## Authorization Verification
-
-Controllers verify authorization was performed:
-
-```ruby
-# These run after every action
-verify_authorize_current        # Ensures authorize_current! was called
-verify_current_authorized_scope # Ensures scope was loaded (except new/create)
-```
-
-To skip verification for custom actions:
-
-```ruby
-class PostsController < ::ResourceController
-  skip_verify_authorize_current only: [:custom_action]
-
-  def custom_action
-    # Handle authorization manually
-  end
-end
-```
-
-## Response Formats
-
-Controllers respond to multiple formats:
-
-```ruby
-def show
-  # Responds to:
-  # - HTML (default)
-  # - JSON (via RABL templates)
-  # - Turbo Stream (for Hotwire)
-end
-```
-
-## Portal-Specific Controllers
-
-Portal controllers inherit from the feature package's controller if one exists (and include the portal's `Concerns::Controller`). If no feature package controller exists, they inherit from the portal's `ResourceController`.
-
-```ruby
-# With feature package controller:
-class AdminPortal::PostsController < ::PostsController
-  include AdminPortal::Concerns::Controller
-end
-
-# Without feature package controller:
-class AdminPortal::PostsController < AdminPortal::ResourceController
-end
-```
-
-For non-resource portal pages (dashboard, settings), inherit from `PlutoniumController`:
-
-```ruby
-module AdminPortal
-  class DashboardController < PlutoniumController
-    def index
-      # Dashboard home
-    end
-  end
-end
-```
-
-## Best Practices
-
-1. **Keep controllers thin** - Use definitions for UI, policies for auth, interactions for logic
-2. **Don't override CRUD actions** - Customize via hooks (`resource_params`, `redirect_url_after_submit`)
-3. **Use interactive actions** - For custom operations, define in definition with interaction
-4. **Let authorization work** - Don't skip verification without good reason
-5. **Trust the framework** - Most customization belongs in definitions or policies
-
-## Related Skills
-
-- `plutonium` - How controllers fit in the resource architecture
-- `plutonium-policy` - Authorization (used by controllers)
-- `plutonium-definition` - Interactive actions (preferred over custom controller actions)
-- `plutonium-views` - Custom page, form, display, and table classes
-- `plutonium-nested-resources` - Parent/child routes and scoping
-- `plutonium-model` - Resource models

data/.claude/skills/plutonium-create-resource/SKILL.md

@@ -1,303 +0,0 @@
----
-name: plutonium-create-resource
-description: Use BEFORE running pu:res:scaffold or creating any new resource. Also when picking field types or generator options. Covers field syntax and scaffold options.
----
-
-# Create Resource Skill
-
-## 🚨 Critical (read first)
-- **Always use `pu:res:scaffold`.** Never hand-write models, migrations, policies, definitions, or controllers. Plutonium's conventions rely on files it generated.
-- **Always pass `--dest`** (`--dest=main_app` or `--dest=package_name`) to skip the interactive destination prompt.
-- **Quote fields with `?` or `{}`** to prevent shell expansion: `'field:type?'`, `'field:decimal{10,2}'`, `'field:decimal?{10,2}'`.
-- **Run `pu:res:conn` next** to connect the resource to a portal — without it, the resource is invisible.
-- **Related skills:** `plutonium-model` (model structure), `plutonium-definition` (UI config), `plutonium-policy` (authorization), `plutonium-portal` (connecting to portals).
-
-Use the `pu:res:scaffold` generator to create complete resources in Plutonium applications.
-
-## Quick checklist
-
-Creating a new resource:
-
-1. Pick a destination: `--dest=main_app` or `--dest=package_name`.
-2. Identify field types (see field type syntax below). Quote fields with `?` or `{}`.
-3. Run `rails g pu:res:scaffold ResourceName field:type ... --dest=<dest>`.
-4. Review the generated migration — add cascade deletes, composite indexes, defaults.
-5. Run `rails db:migrate`.
-6. Run `rails g pu:res:conn ResourceName --dest=<portal_name>` to connect to a portal.
-7. Verify routes: `bin/rails routes | grep resource_name`.
-8. Customize the policy (`permitted_attributes_for_read`, `permitted_attributes_for_create`) as needed.
-9. Open the portal route in the browser.
-
-## Command Syntax
-
-```bash
-rails g pu:res:scaffold MODEL_NAME \
-    field1:type \
-    field2:type \
-    --dest=DESTINATION
-```
-
-**IMPORTANT**: Always specify `--dest` to avoid interactive prompts:
-- `--dest=main_app` for resources in the main application
-- `--dest=package_name` for resources in a feature package
-
-**IMPORTANT**: Quote fields containing `?` or `{}` to prevent shell expansion:
-```bash
-'field:type?'              # Nullable - must quote
-'field:decimal{10,2}'      # Options - must quote
-'field:decimal?{10,2}'     # Both - must quote
-```
-
-## From Existing Models
-
-For existing Rails projects with models you want to convert to Plutonium resources:
-
-### Option 1: Model already includes Plutonium::Resource::Record
-
-```bash
-rails g pu:res:scaffold Post --no-migration --dest=main_app
-```
-
-This generates only the definition, policy, and controller - leaving your model unchanged.
-
-### Option 2: Let the generator update the model
-
-```bash
-rails g pu:res:scaffold Post --dest=main_app
-```
-
-Run without attributes to auto-import fields from `model.content_columns`. This regenerates the model file, so review changes carefully.
-
-### Don't forget to include the module
-
-Your model must include `Plutonium::Resource::Record` (directly or via inheritance):
-
-```ruby
-class Post < ApplicationRecord
-  include Plutonium::Resource::Record
-end
-
-# Or inherit from a base class
-class Post < ResourceRecord
-end
-```
-
-## Field Type Syntax
-
-Format: `name:type:index_type`
-
-### Basic Types
-
-| Syntax | Result |
-|--------|--------|
-| `name:string` | Required string |
-| `'name:string?'` | Nullable string |
-| `age:integer` | Required integer |
-| `'age:integer?'` | Nullable integer |
-| `active:boolean` | Required boolean |
-| `'active:boolean?'` | Nullable boolean |
-| `content:text` | Required text |
-| `'content:text?'` | Nullable text |
-| `birth_date:date` | Required date |
-| `'anniversary:date?'` | Nullable date |
-| `starts_at:datetime` | Required datetime |
-| `'ends_at:datetime?'` | Nullable datetime |
-| `alarm_time:time` | Required time |
-| `'reminder_time:time?'` | Nullable time |
-| `metadata:json` | JSON field |
-| `settings:jsonb` | JSONB (PostgreSQL) |
-| `external_id:uuid` | UUID field |
-
-### PostgreSQL-Specific Types
-
-These types work in both PostgreSQL and SQLite (automatically mapped):
-
-| Type | PostgreSQL | SQLite |
-|------|------------|--------|
-| `jsonb` | `jsonb` | `json` |
-| `hstore` | `hstore` | `json` |
-| `uuid` | `uuid` | `string` |
-| `inet` | `inet` | `string` |
-| `cidr` | `cidr` | `string` |
-| `macaddr` | `macaddr` | `string` |
-| `ltree` | `ltree` | `string` |
-
-### Default Values
-
-Use `{default:value}` syntax for default values:
-
-```bash
-'status:string{default:draft}'           # String default
-'active:boolean{default:true}'           # Boolean default (true/false/yes/1)
-'priority:integer{default:0}'            # Integer default
-'rating:float{default:4.5}'              # Float default
-'status:string?{default:pending}'        # Nullable with default
-```
-
-### JSON/JSONB Default Values
-
-Supports nested braces for structured defaults:
-
-```bash
-'metadata:jsonb{default:{}}'             # Empty hash
-'tags:jsonb{default:[]}'                 # Empty array
-'settings:jsonb{default:{"theme":"dark"}}' # Object with values
-'config:jsonb?{default:{}}'              # Nullable with empty hash default
-```
-
-Default values are parsed as JSON first. If JSON parsing fails, the value is treated as a string (or coerced based on column type for integers, floats, and booleans).
-
-### Decimal with Precision and Default
-
-```bash
-'amount:decimal{10,2}'                   # precision: 10, scale: 2
-'price:decimal{10,2,default:0}'          # with default value
-'balance:decimal?{15,2,default:0}'       # nullable with precision and default
-```
-
-### References/Associations
-
-```bash
-company:belongs_to                 # Required foreign key
-'parent:belongs_to?'               # Nullable (null: true + optional: true)
-user:references                    # Same as belongs_to
-blogging/post:belongs_to           # Cross-package reference
-'author:belongs_to{class_name:User}'     # Custom class_name (author_id -> User)
-'reviewer:belongs_to?{class_name:User}'  # Nullable with class_name
-```
-
-Nullable references generate:
-- Migration: `null: true`
-- Model: `belongs_to :parent, optional: true`
-
-### Index Types (third segment)
-
-```bash
-email:string:index                 # Regular index
-email:string:uniq                  # Unique index
-```
-
-### Special Types
-
-```bash
-password_digest                    # has_secure_password
-auth_token:token                   # has_secure_token (auto unique index)
-content:rich_text                  # has_rich_text
-avatar:attachment                  # has_one_attached
-photos:attachments                 # has_many_attached
-price_cents:integer                # has_cents (money field)
-```
-
-Token fields automatically get a unique index in the migration.
-
-## Generator Options
-
-- `--dest=DESTINATION` - Target destination (**always required** to avoid prompts)
-  - `main_app` for main application resources
-  - `package_name` for feature package resources
-- `--no-model` - Skip model generation (keeps existing model)
-- `--no-migration` - Skip migration generation (use with `--no-model` for existing models)
-
-## What Gets Generated
-
-For **main_app** resources:
-1. **Model** - `app/models/model_name.rb`
-2. **Migration** - `db/migrate/xxx_create_model_names.rb`
-3. **Controller** - `app/controllers/model_names_controller.rb`
-4. **Policy** - `app/policies/model_name_policy.rb`
-5. **Definition** - `app/definitions/model_name_definition.rb`
-
-For **packaged** resources:
-1. **Model** - `app/models/package_name/model_name.rb`
-2. **Migration** - `db/migrate/xxx_create_package_name_model_names.rb`
-3. **Controller** - `packages/package_name/app/controllers/package_name/model_names_controller.rb`
-4. **Policy** - `packages/package_name/app/policies/package_name/model_name_policy.rb`
-5. **Definition** - `packages/package_name/app/definitions/package_name/model_name_definition.rb`
-
-## Migration Customizations
-
-The generator creates basic migrations. **Always review and customize** the migration before running:
-
-### Inline Indexes (preferred)
-
-```ruby
-create_table :model_names do |t|
-  t.belongs_to :parent, null: false, foreign_key: true
-  t.string :name, null: false
-
-  t.timestamps
-
-  t.index :name
-  t.index [:parent_id, :name], unique: true
-end
-```
-
-### Cascade Delete
-
-```ruby
-t.belongs_to :parent, null: false, foreign_key: {on_delete: :cascade}
-```
-
-### Default Values
-
-Default values can be set directly in the generator using `{default:value}` syntax (see Field Type Syntax above). For more complex defaults or expressions, edit the migration:
-
-```ruby
-t.boolean :is_active, default: true
-t.integer :status, default: 0
-t.datetime :published_at, default: -> { "CURRENT_TIMESTAMP" }
-```
-
-## Examples
-
-### Main App Resource
-
-```bash
-rails g pu:res:scaffold Post \
-    user:belongs_to \
-    title:string \
-    'content:text?' \
-    'published_at:datetime?' \
-    --dest=main_app
-```
-
-### Resource with Precision and Indexes
-
-```bash
-rails g pu:res:scaffold Property \
-    company:belongs_to \
-    code:string:uniq \
-    'latitude:decimal{11,8}' \
-    'longitude:decimal?{11,8}' \
-    'value:decimal?{15,2}' \
-    'notes:text?' \
-    --dest=main_app
-```
-
-### Optional Association
-
-```bash
-rails g pu:res:scaffold Comment \
-    user:belongs_to \
-    'parent:belongs_to?' \
-    body:text \
-    --dest=blogging
-```
-
-### Cross-Package Reference
-
-```bash
-rails g pu:res:scaffold Comment \
-    user:belongs_to \
-    blogging/post:belongs_to \
-    body:text \
-    --dest=comments
-```
-
-## After Generation
-
-1. **Review and customize the migration** (add cascade delete, defaults, composite indexes)
-2. Run `rails db:migrate`
-3. Connect resource to portal: `rails g pu:res:conn Post --dest=admin_portal`
-4. Customize policy permissions as needed
-5. Add definition customizations for UI behavior