plutonium 0.33.1 → 0.34.0

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

@@ -0,0 +1,302 @@
+---
+name: controller
+description: Plutonium resource controllers - CRUD actions, customization, and integration
+---
+
+# Plutonium 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
+```
+
+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
+```
+
+## Nested Resources
+
+Parent records are automatically resolved:
+
+```ruby
+# Route: /users/:user_id/posts/:id
+class PostsController < ::ResourceController
+  # current_parent returns the User
+  # resource_record! returns the Post scoped to that User
+end
+```
+
+Parent fields are automatically excluded from forms/displays. Override with presentation hooks (see above).
+
+## 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
+- Provide `current_scoped_entity` method
+
+## 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
+
+Each portal can have its own controller override:
+
+```ruby
+# packages/admin_portal/app/controllers/admin_portal/posts_controller.rb
+module AdminPortal
+  class PostsController < ResourceController
+    private
+
+    def preferred_action_after_submit
+      "index"  # Admin prefers list view
+    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
+
+- `resource` - How controllers fit in the resource architecture
+- `policy` - Authorization (used by controllers)
+- `definition-actions` - Interactive actions (preferred over custom controller actions)
+- `views` - Custom page, form, display, and table classes
+- `nested-resources` - Parent/child routes and scoping
+- `model` - Resource models

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

@@ -0,0 +1,240 @@
+---
+name: create-resource
+description: Generate Plutonium resources with models, migrations, controllers, policies, and definitions
+---
+
+# Create Resource Skill
+
+Use the `pu:res:scaffold` generator to create complete resources in Plutonium applications.
+
+## 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 |
+
+### Decimal with Precision
+
+The `{precision,scale}` syntax **only works for decimal types**:
+
+```bash
+'latitude:decimal{11,8}'           # precision: 11, scale: 8
+'amount:decimal{10,2}'             # precision: 10, scale: 2
+'latitude:decimal?{11,8}'          # nullable with precision
+```
+
+**Note**: For default values on other types (boolean, integer, etc.), edit the migration manually.
+
+### 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
+```
+
+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
+
+```ruby
+t.boolean :is_active, default: true
+t.integer :status, default: 0
+t.integer :count, null: true, default: 0
+```
+
+## 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