plutonium 0.33.1 → 0.34.0

data/.claude/skills/interaction/SKILL.md

@@ -0,0 +1,382 @@
+---
+name: interaction
+description: Plutonium interactions - encapsulated business logic for custom actions
+---
+
+# Plutonium Interactions
+
+Interactions encapsulate business logic into reusable, testable units. They handle input validation, execution, and outcomes.
+
+## Basic Structure
+
+```ruby
+# app/interactions/resource_interaction.rb (generated during install)
+class ResourceInteraction < Plutonium::Resource::Interaction
+end
+
+# app/interactions/publish_post_interaction.rb
+class PublishPostInteraction < ResourceInteraction
+  # Presentation
+  presents label: "Publish",
+           icon: Phlex::TablerIcons::Send,
+           description: "Make this post public"
+
+  # Attributes (inputs)
+  attribute :resource  # The record being acted upon
+  attribute :publish_date, :datetime, default: -> { Time.current }
+
+  # Form inputs (what user sees)
+  input :publish_date, as: :datetime
+
+  # Validations
+  validates :publish_date, presence: true
+
+  private
+
+  def execute
+    resource.update!(published_at: publish_date)
+    succeed(resource).with_message("Post published!")
+  rescue ActiveRecord::RecordInvalid => e
+    failed(e.record.errors)
+  end
+end
+```
+
+## Attributes
+
+Define inputs using ActiveModel attributes:
+
+```ruby
+attribute :resource                              # Record (for record actions)
+attribute :resources                             # Collection (for bulk actions)
+attribute :email, :string                        # String input
+attribute :count, :integer, default: 1           # With default
+attribute :active, :boolean, default: -> { true } # Callable default
+attribute :tags, :array                          # Array
+attribute :metadata, :hash                       # Hash
+attribute :date, :datetime                       # DateTime
+```
+
+## Form Inputs
+
+Define form fields with the `input` method (same as definitions):
+
+```ruby
+input :email
+input :role, as: :select, choices: %w[admin user]
+input :content, as: :text
+input :date, as: :date
+```
+
+See `definition-fields` skill for all input types and options.
+
+## Presentation
+
+Configure how the action appears in the UI:
+
+```ruby
+presents label: "Archive Record",
+         icon: Phlex::TablerIcons::Archive,
+         description: "Move to archive for later reference"
+```
+
+Access presentation:
+```ruby
+MyInteraction.label       # => "Archive Record"
+MyInteraction.icon        # => Phlex::TablerIcons::Archive
+MyInteraction.description # => "Move to archive..."
+```
+
+## Execution and Outcomes
+
+### The execute Method
+
+```ruby
+private
+
+def execute
+  # Your business logic here
+  # Must return succeed() or failed()
+end
+```
+
+### Success Outcomes
+
+```ruby
+# Basic success
+succeed(resource)
+
+# With message
+succeed(resource).with_message("Done!")
+succeed(resource).with_message("Warning!", :alert)
+
+# With redirect
+succeed(resource).with_redirect_response(posts_path)
+
+# With file download
+succeed(resource).with_file_response(file_path, filename: "report.pdf")
+
+# Chaining
+succeed(resource)
+  .with_message("Created!")
+  .with_redirect_response(resource_path(resource))
+```
+
+### Failure Outcomes
+
+```ruby
+# Basic failure
+failed("Something went wrong")
+
+# With ActiveModel errors
+failed(resource.errors)
+
+# With hash of errors
+failed(email: "is invalid", name: "is required")
+```
+
+### Chaining Interactions
+
+```ruby
+def execute
+  CreateUserInteraction.call(view_context:, **user_params)
+    .and_then { |result| SendWelcomeEmail.call(view_context:, user: result.value) }
+    .and_then { |result| LogActivity.call(view_context:, user: result.value) }
+    .with_message("User created and welcomed!")
+end
+```
+
+On failure, the chain short-circuits and returns the failure immediately.
+
+## Validations
+
+Use standard ActiveModel validations:
+
+```ruby
+validates :email, presence: true
+validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+validates :role, inclusion: { in: %w[admin user guest] }
+
+validate :custom_validation
+
+private
+
+def custom_validation
+  if resource.archived?
+    errors.add(:resource, "cannot be modified when archived")
+  end
+end
+```
+
+Validations run automatically before `execute`. If invalid, returns `failed()` with errors.
+
+## Interaction Types
+
+### Record Actions
+
+Act on a single record:
+
+```ruby
+class ArchiveInteraction < Plutonium::Resource::Interaction
+  attribute :resource  # Single record
+
+  def execute
+    resource.update!(archived: true)
+    succeed(resource)
+  end
+end
+```
+
+### Resource Actions
+
+Act at the collection/class level (no specific record):
+
+```ruby
+class ImportInteraction < Plutonium::Resource::Interaction
+  # No :resource attribute
+  attribute :file
+
+  input :file, as: :file
+
+  def execute
+    records = CSV.parse(file)
+    Post.import(records)
+    succeed(records)
+  end
+end
+```
+
+### Bulk Actions (Multiple Records)
+
+Act on multiple selected records:
+
+```ruby
+class BulkArchiveInteraction < Plutonium::Resource::Interaction
+  attribute :resources  # Collection of records
+
+  def execute
+    resources.update_all(archived: true)
+    succeed(resources).with_message("Archived #{resources.count} records")
+  end
+end
+```
+
+## Connecting to Definitions
+
+Register interactions as actions:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Record action (shows on individual records)
+  action :publish, interaction: PublishPostInteraction
+
+  # Resource action (shows at collection level)
+  action :import, interaction: ImportInteraction
+
+  # With options
+  action :archive,
+    interaction: ArchiveInteraction,
+    confirmation: "Are you sure?",
+    category: :danger,
+    position: 100
+end
+```
+
+### Action Options
+
+| Option | Description |
+|--------|-------------|
+| `interaction:` | The interaction class |
+| `confirmation:` | Confirmation message before execution |
+| `category:` | `:primary`, `:secondary`, `:danger` |
+| `position:` | Display order (lower = first) |
+| `turbo_frame:` | Turbo frame target (default: `remote_modal`) |
+| `icon:` | Override interaction icon |
+| `label:` | Override interaction label |
+
+## Policy Integration
+
+Control access with policy methods:
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def publish?
+    update? && record.draft?
+  end
+
+  def archive?
+    destroy? && !record.archived?
+  end
+
+  def import?
+    create?  # Resource-level action
+  end
+end
+```
+
+The policy method name matches the action name with `?`.
+
+## Accessing Context
+
+Inside interactions:
+
+```ruby
+def execute
+  # Access current user via view_context
+  current_user = view_context.controller.helpers.current_user
+
+  # Access the resource
+  resource.update!(updated_by: current_user)
+
+  succeed(resource)
+end
+```
+
+## Immediate vs Form Actions
+
+Plutonium automatically determines if an action needs a form:
+
+- **Has inputs defined** → Shows form first (GET), then executes (POST)
+- **No inputs** → Executes immediately (POST with confirmation)
+
+```ruby
+# Shows form (has inputs)
+class InviteUserInteraction < Plutonium::Resource::Interaction
+  attribute :resource
+  attribute :email
+  input :email  # This triggers form display
+end
+
+# Immediate execution (no inputs)
+class ArchiveInteraction < Plutonium::Resource::Interaction
+  attribute :resource
+  # No inputs = immediate with confirmation
+end
+```
+
+## Complete Example
+
+```ruby
+class Company::InviteUserInteraction < Plutonium::Resource::Interaction
+  presents label: "Invite User",
+           icon: Phlex::TablerIcons::UserPlus,
+           description: "Send an invitation email"
+
+  attribute :resource  # The company
+  attribute :email, :string
+  attribute :role, :string
+
+  input :email
+  input :role, as: :select, choices: -> { UserInvite.roles.keys }
+
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :role, presence: true, inclusion: { in: UserInvite.roles.keys }
+  validate :not_already_invited
+
+  private
+
+  def execute
+    invite = UserInvite.create!(
+      company: resource,
+      email: email,
+      role: role,
+      invited_by: current_user
+    )
+    UserInviteMailer.invitation(invite).deliver_later
+
+    succeed(resource)
+      .with_message("Invitation sent to #{email}")
+      .with_redirect_response(resource)
+  rescue ActiveRecord::RecordInvalid => e
+    failed(e.record.errors)
+  end
+
+  def not_already_invited
+    return unless email.present?
+
+    if UserInvite.exists?(company: resource, email: email, state: :pending)
+      errors.add(:email, "already has a pending invitation")
+    end
+  end
+
+  def current_user
+    view_context.controller.helpers.current_user
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep interactions focused** - One action per interaction
+2. **Use validations** - Validate all inputs before execution
+3. **Handle errors gracefully** - Rescue exceptions and return `failed()`
+4. **Return meaningful messages** - Help users understand what happened
+5. **Use `and_then` for chains** - Compose complex workflows from simple interactions
+6. **Test independently** - Interactions are easy to unit test
+
+## Related Skills
+
+- `definition-actions` - Declaring actions in definitions
+- `forms` - Custom interaction form templates
+- `policy` - Controlling access to actions
+- `resource` - How interactions fit in the architecture

data/.claude/skills/model/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: model
+description: Overview of Plutonium resource models - structure, setup, and best practices
+---
+
+# Plutonium Resource Models
+
+A model becomes a Plutonium resource by including `Plutonium::Resource::Record`. This provides enhanced ActiveRecord functionality for routing, labeling, field introspection, associations, and monetary handling.
+
+## Setup
+
+### Standard Setup
+
+```ruby
+# app/models/application_record.rb
+class ApplicationRecord < ActiveRecord::Base
+  include Plutonium::Resource::Record
+  primary_abstract_class
+end
+
+# app/models/resource_record.rb (optional abstract class)
+class ResourceRecord < ApplicationRecord
+  self.abstract_class = true
+end
+
+# app/models/property.rb
+class Property < ResourceRecord
+  # Now has access to all Plutonium features
+end
+```
+
+### What's Included
+
+`Plutonium::Resource::Record` includes six modules:
+
+| Module | Purpose |
+|--------|---------|
+| `HasCents` | Monetary value handling (cents → decimal) |
+| `Routes` | URL parameters, path customization |
+| `Labeling` | Human-readable `to_label` method |
+| `FieldNames` | Field introspection and categorization |
+| `Associations` | SGID support for secure serialization |
+| `AssociatedWith` | Entity scoping for multi-tenant apps |
+
+## Model Structure
+
+Follow the template structure (comment markers indicate where to add code):
+
+```ruby
+class Property < ResourceRecord
+  # add concerns above.
+
+  TYPES = {apartment: "Apartment", house: "House"}.freeze
+  # add constants above.
+
+  enum :state, archived: 0, active: 1
+  enum :property_class, residential: 0, commercial: 1
+  # add enums above.
+
+  has_cents :market_value_cents
+  # add model configurations above.
+
+  belongs_to :company
+  # add belongs_to associations above.
+
+  has_one :address
+  # add has_one associations above.
+
+  has_many :units
+  has_many :amenities, class_name: "PropertyAmenity"
+  # add has_many associations above.
+
+  has_one_attached :photo
+  has_many_attached :documents
+  # add attachments above.
+
+  scope :active, -> { where(state: :active) }
+  scope :by_company, ->(company) { where(company: company) }
+  # add scopes above.
+
+  validates :name, presence: true
+  validates :property_code, presence: true, uniqueness: {scope: :company_id}
+  # add validations above.
+
+  before_validation :generate_code, on: :create
+  # add callbacks above.
+
+  delegate :name, to: :company, prefix: true
+  # add delegations above.
+
+  has_rich_text :description
+  # add misc attribute macros above.
+
+  def full_address
+    address&.to_s
+  end
+
+  # add methods above. add private methods below.
+
+  private
+
+  def generate_code
+    self.property_code ||= SecureRandom.hex(4).upcase
+  end
+end
+```
+
+### Section Order
+
+1. **Concerns** - `include` statements
+2. **Constants** - `TYPES = {...}.freeze`, etc.
+3. **Enums** - `enum :state, ...`
+4. **Model configurations** - `has_cents`
+5. **belongs_to associations**
+6. **has_one associations**
+7. **has_many associations**
+8. **Attachments** - `has_one_attached`, `has_many_attached`
+9. **Scopes**
+10. **Validations**
+11. **Callbacks**
+12. **Delegations**
+13. **Misc attribute macros** - `has_rich_text`, `has_secure_token`, `has_secure_password`
+14. **Methods** - Public methods above, private methods below
+
+## Common Patterns
+
+### Archiving (State-Based)
+
+```ruby
+class Property < ResourceRecord
+  enum :state, archived: 0, active: 1
+
+  scope :active, -> { where(state: :active) }
+  scope :archived, -> { where(state: :archived) }
+
+  def archive!
+    update!(state: :archived)
+  end
+
+  def restore!
+    update!(state: :active)
+  end
+end
+```
+
+### Multi-Tenant Scoping
+
+```ruby
+class Property < ResourceRecord
+  belongs_to :company
+
+  # Compound uniqueness for multi-tenant
+  validates :property_code, uniqueness: {scope: :company_id}
+
+  # Custom scope for entity scoping
+  scope :associated_with_company, ->(company) { where(company: company) }
+end
+```
+
+### Custom Validation
+
+```ruby
+class Contact < ResourceRecord
+  validates :contact_type, presence: true
+
+  validate :ensure_contact_provided
+
+  private
+
+  def ensure_contact_provided
+    return unless [email, phone, website].all?(&:blank?)
+    errors.add(:base, "Please provide at least one contact method")
+  end
+end
+```
+
+### One-to-One Relationships
+
+```ruby
+# Parent side
+class Tenant < ResourceRecord
+  has_one :residential_profile, class_name: "ResidentialTenantProfile"
+  has_one :commercial_profile, class_name: "CommercialTenantProfile"
+end
+
+# Child side (unique index on foreign key)
+class ResidentialTenantProfile < ResourceRecord
+  belongs_to :tenant
+  # Migration: t.index :tenant_id, unique: true
+end
+```
+
+### Polymorphic Associations
+
+```ruby
+class Comment < ResourceRecord
+  belongs_to :commentable, polymorphic: true
+end
+
+class Post < ResourceRecord
+  has_many :comments, as: :commentable
+end
+
+class Photo < ResourceRecord
+  has_many :comments, as: :commentable
+end
+```
+
+## Labeling
+
+The `to_label` method provides human-readable record labels:
+
+```ruby
+# Automatic - checks :name, then :title, then fallback
+user = User.new(name: "John Doe")
+user.to_label  # => "John Doe"
+
+user = User.create(id: 1)
+user.to_label  # => "User #1"
+
+# Custom override
+class Product < ResourceRecord
+  def to_label
+    "#{name} (#{sku})"
+  end
+end
+```
+
+## Field Introspection
+
+Access field information programmatically:
+
+```ruby
+# All resource fields
+User.resource_field_names
+# => [:id, :name, :email, :company, :avatar, ...]
+
+# By category
+User.content_column_field_names           # Database columns
+User.belongs_to_association_field_names   # belongs_to associations
+User.has_one_association_field_names      # has_one associations
+User.has_many_association_field_names     # has_many associations
+User.has_one_attached_field_names         # Active Storage single
+User.has_many_attached_field_names        # Active Storage multiple
+```
+
+## Best Practices
+
+1. **Use enums for state** - `enum :state, archived: 0, active: 1` instead of soft-delete
+2. **Compound uniqueness** - Always scope uniqueness to tenant/parent
+3. **Organize with comments** - Use section headers for readability
+4. **Keep models focused** - Business logic in interactions, not models
+5. **Validate at boundaries** - Validate user input, trust internal code
+6. **Use scopes** - Define commonly used queries as scopes
+
+## Integration
+
+Models integrate with:
+- **Policies** - `resource_field_names` for auto-detection
+- **Definitions** - Field introspection for forms/displays
+- **Controllers** - `from_path_param` for lookups
+- **Query Objects** - Association detection for sorting
+
+## Related Skills
+
+- `model-features` - has_cents, associations, scopes, routes
+- `create-resource` - Scaffold generator for new resources