plutonium 0.26.8 → 0.26.9

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plutonium
 version: !ruby/object:Gem::Version
-  version: 0.26.8
+  version: 0.26.9
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-11 00:00:00.000000000 Z
+date: 2025-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -495,7 +495,7 @@ files:
 - docs/.vitepress/theme/custom.css
 - docs/.vitepress/theme/index.ts
 - docs/api-examples.md
-- docs/guide/cursor-rules.md
+- docs/guide/claude-code-guide.md
 - docs/guide/deep-dive/authorization.md
 - docs/guide/deep-dive/multitenancy.md
 - docs/guide/deep-dive/resources.md
@@ -531,13 +531,13 @@ files:
 - docs/modules/routing.md
 - docs/modules/table.md
 - docs/modules/ui.md
+- docs/public/CLAUDE.md
 - docs/public/android-chrome-192x192.png
 - docs/public/android-chrome-512x512.png
 - docs/public/apple-touch-icon.png
 - docs/public/favicon-16x16.png
 - docs/public/favicon-32x32.png
 - docs/public/favicon.ico
-- docs/public/plutonium.mdc
 - docs/public/plutonium.png
 - docs/public/site.webmanifest
 - docs/public/templates/base.rb

data/docs/public/plutonium.mdc

@@ -1,565 +0,0 @@
----
-description: Expert Plutonium framework guidelines for AI-assisted Rails development with auto-detection, resource architecture, component-based UI, and RAD patterns
-globs:
-alwaysApply: true
----
-You are an expert Ruby on Rails developer specializing in the Plutonium framework. This cursor rule compiles comprehensive guidelines for building robust, maintainable Plutonium applications.
-
-# Plutonium Framework Development Guidelines
-
-## Framework Overview
-
-Plutonium is a Rapid Application Development (RAD) toolkit that extends Rails with powerful conventions, patterns, and tools. It provides:
-- Resource-oriented architecture with declarative definitions
-- Modular packaging system (Feature Packages and Portal Packages)
-- Built-in authentication, authorization, and multi-tenancy
-- Component-based UI system built on Phlex
-- Business logic encapsulation through Interactions
-- Query objects for filtering and searching
-
-## Project Structure & Setup
-
-### Initial Setup
-- Use Ruby 3.2.2+ and Rails 7.1+
-- Create new apps with: `rails new app_name -a propshaft -j esbuild -c tailwind -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb`
-- For existing apps: `bin/rails app:template LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb`
-- Run `rails generate pu:core:install` after adding the gem
-
-### Directory Structure
-```
-app/
-├── controllers/
-│   ├── plutonium_controller.rb     # Base controller
-│   └── resource_controller.rb      # Base for resources
-├── definitions/                     # Resource definitions
-├── interactions/                    # Business logic
-├── models/
-└── policies/                       # Authorization policies
-config/
-├── initializers/plutonium.rb       # Main configuration
-└── packages.rb                     # Package registration
-packages/                           # Modular features
-```
-
-## Resource Architecture
-
-### Resource Components
-Every resource consists of 4 core components:
-1. **Model** - ActiveRecord model with `include Plutonium::Resource::Record`
-2. **Definition** - Declarative UI and behavior configuration
-3. **Policy** - Authorization and access control
-4. **Controller** - Auto-generated CRUD operations
-
-### Creating Resources
-```bash
-# Scaffold a complete resource
-rails generate pu:res:scaffold Post user:belongs_to title:string content:text 'published_at:datetime?'
-
-# Individual components
-rails generate pu:res:model Post title:string content:text
-rails generate pu:res:definition Post
-rails generate pu:res:policy Post
-```
-
-### Resource Models
-```ruby
-class Post < ApplicationRecord
-  include Plutonium::Resource::Record
-
-  belongs_to :user
-  has_many :comments, dependent: :destroy
-
-  validates :title, :content, presence: true
-
-  scope :published, -> { where.not(published_at: nil) }
-  scope :drafts, -> { where(published_at: nil) }
-end
-```
-
-### Resource Definitions
-```ruby
-class PostDefinition < Plutonium::Resource::Definition
-  # Field declarations are OPTIONAL - all attributes are auto-detected from the model
-  # You only need to declare fields when overriding auto-detected behavior
-
-  # These would be auto-detected from your Post model:
-  # - :title (string column) → :string field
-  # - :content (text column) → :text field
-  # - :published_at (datetime column) → :datetime field
-  # - :author (belongs_to association) → :association field
-
-  # Only declare fields when you want to override defaults:
-  field :content, as: :rich_text  # Override text → rich_text
-  field :status, as: :select, choices: %w[draft published archived]
-
-  # Display customization (show/index pages)
-  display :title, as: :string
-  display :content, as: :markdown
-  display :status, as: :string
-  display :author, as: :association
-
-  # Conditional displays (for table columns and show pages)
-  # Use for COSMETIC/STATE-BASED logic only, NOT authorization (use policies for that)
-  display :debug_info, condition: -> { Rails.env.development? }
-  display :internal_notes, condition: -> { object.status == 'draft' }
-  display :parent_category, condition: -> { current_parent.present? }
-
-  # Custom display with block (for complex rendering)
-  display :custom_field do |field|
-    # Return component instances directly in definition blocks (no 'render' needed)
-    CustomComponent.new(value: field.value)
-  end
-
-  # Advanced custom display with phlexi_tag (use sparingly)
-  display :status, as: :phlexi_tag, with: ->(value, attrs) {
-    # SGML methods available here because proc is evaluated in rendering context
-    span(class: "badge badge-#{value}") { value.humanize }
-  }
-
-  # Input configuration (new/edit forms)
-  input :title, placeholder: "Enter post title"  # No need for as: :string (auto-detected)
-  input :content, as: :rich_text
-  input :category, as: :select, choices: %w[Tech Business Lifestyle]
-
-  # New: Custom component classes
-  input :color_picker, as: ColorPickerComponent
-  display :status_badge, as: StatusBadgeComponent
-
-  # Input blocks for custom logic (must use form builder methods)
-  input :birth_date do |f|
-    case object.age_category
-    when 'adult'
-      f.date_tag(min: 18.years.ago.to_date)
-    else
-      f.date_tag
-    end
-  end
-
-  # Conditional inputs (for forms only)
-  # Use for COSMETIC/STATE-BASED logic only, NOT authorization (use policies for that)
-  input :debug_info, condition: -> { Rails.env.development? }
-  input :internal_notes, condition: -> { object.status == 'draft' }
-  input :parent_category, condition: -> { current_parent.present? }
-  input :team_projects, condition: -> { current_user.team_lead? }
-
-  # Search functionality
-  search do |scope, query|
-    scope.where("title ILIKE ? OR content ILIKE ?", "%#{query}%", "%#{query}%")
-  end
-
-  # Filters
-  filter :published, with: Plutonium::Query::Filters::Text, predicate: :eq
-  filter :category, with: Plutonium::Query::Filters::Text, predicate: :contains
-  filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
-
-  # Scopes (appear as buttons)
-  scope :published
-  scope :drafts
-  scope :recent, -> { where('created_at > ?', 1.week.ago) }
-
-  # Custom actions
-  action :publish, interaction: PublishPostInteraction, icon: Phlex::TablerIcons::Send
-  action :archive, interaction: ArchivePostInteraction, color: :warning
-
-  # Page customization
-  index_page_title "All Posts"
-  show_page_title "Post Details"
-end
-```
-
-### Available Field Types (Auto-Detected from Model)
-- Text: `:string`, `:text`, `:rich_text`, `:markdown`
-- Numeric: `:number`, `:integer`, `:decimal`
-- Boolean: `:boolean`
-- Date/Time: `:date`, `:datetime`, `:time`
-- Selection: `:select`, `:radio_buttons`, `:check_boxes`
-- Files: `:file` (with `multiple: true` for multiple files)
-- Associations: `:association`
-- Special: `:hidden`, `:email`, `:url`, `:color`
-
-### Conditional Rendering Guidelines
-
-**IMPORTANT**: Use conditions for COSMETIC/STATE-BASED logic only, NOT for authorization.
-
-#### ✅ Appropriate Uses
-- **Environment-based**: Show debug info in development only
-- **Object state-based**: Show fields based on record status
-- **Context-based**: Show fields based on parent presence
-- **Dynamic behavior**: Show dependent fields conditionally
-
-```ruby
-# Environment-based visibility
-display :debug_info, condition: -> { Rails.env.development? }
-
-# Object state-based visibility
-display :approval_date, condition: -> { object.approved? }
-input :rejection_reason, condition: -> { object.rejected? }
-
-# Parent context-based visibility
-display :parent_category, condition: -> { current_parent.present? }
-
-# Dynamic form behavior
-input :end_date, condition: -> { object.start_date.present? }
-```
-
-#### ❌ Inappropriate Uses
-Authorization logic belongs in policies, not conditions:
-
-```ruby
-# DON'T use conditions for role-based authorization
-display :admin_notes, condition: -> { current_user&.admin? }  # Use policy instead
-input :sensitive_data, condition: -> { current_user&.can_edit_sensitive? }  # Use policy instead
-```
-
-### Available Configuration Options
-
-#### Field Options
-```ruby
-field :name, as: :string, class: "custom-class", wrapper: {class: "field-wrapper"}
-```
-
-#### Input Options
-```ruby
-input :title,
-  as: :string,
-  placeholder: "Enter title",
-  required: true,
-  class: "custom-input",
-  wrapper: {class: "input-wrapper"},
-  data: {controller: "custom"},
-  condition: -> { object.status == 'draft' }  # Cosmetic condition only
-```
-
-#### Display Options
-```ruby
-display :content,
-  as: :markdown,
-  class: "prose",
-  wrapper: {class: "content-wrapper"},
-  condition: -> { Rails.env.development? }  # Cosmetic condition only
-```
-
-#### Choices Options (for selects)
-```ruby
-# Static choices
-input :category, as: :select, choices: %w[Tech Business Lifestyle]
-
-# Dynamic choices require block form
-input :author do |f|
-  choices = User.active.pluck(:name, :id)
-  f.select_tag choices: choices
-end
-
-# Dynamic choices with access to context
-input :team_members do |f|
-  choices = current_user.organization.users.active.pluck(:name, :id)
-  f.select_tag choices: choices
-end
-
-# Dynamic choices based on object state  
-input :related_posts do |f|
-  choices = if object.persisted?
-    Post.where.not(id: object.id).published.pluck(:title, :id)
-  else
-    []
-  end
-  f.select_tag choices: choices
-end
-```
-
-#### File Upload Options
-```ruby
-input :avatar, as: :file, multiple: false
-input :documents, as: :file, multiple: true
-# Note: Advanced file options like allowed_file_types and max_file_size
-# are not currently supported by the framework
-```
-
-### Resource Policies
-
-Policies control authorization and data access. They define who can perform what actions and what data users can see.
-
-```ruby
-class PostPolicy < Plutonium::Resource::Policy
-  # CRUD permissions
-  def index?
-    true # Everyone can view list
-  end
-
-  def show?
-    record.published? || record.author == user || user.admin?
-  end
-
-  def create?
-    user.present?
-  end
-
-  def update?
-    record.author == user || user.admin?
-  end
-
-  def destroy?
-    user.admin?
-  end
-
-  # Custom action permissions
-  def publish?
-    update? && record.draft?
-  end
-
-  # Attribute permissions - control which fields are accessible
-  def permitted_attributes_for_read
-    attrs = [:title, :content, :category, :published_at]
-    attrs << :internal_notes if user.admin?
-    attrs
-  end
-
-  def permitted_attributes_for_create
-    [:title, :content, :category]
-  end
-
-  def permitted_attributes_for_update
-    attrs = permitted_attributes_for_create
-    attrs << :slug if user.admin?
-    attrs
-  end
-
-  # Collection scoping - filter what records users can see
-  relation_scope do |relation|
-    relation = super(relation) # Apply entity scoping first
-
-    if user.admin?
-      relation
-    else
-      # Users see only their posts or published posts
-      relation.where(author: user).or(relation.where(published: true))
-    end
-  end
-
-  # Association permissions
-  def permitted_associations
-    [:comments, :author, :tags]
-  end
-end
-```
-
-## Business Logic with Interactions
-
-### Interaction Structure
-```ruby
-class PublishPostInteraction < Plutonium::Resource::Interaction
-  # Metadata for UI
-  presents label: "Publish Post",
-           icon: Phlex::TablerIcons::Send,
-           description: "Make this post visible to readers"
-
-  # Attributes (form inputs)
-  attribute :resource, class: Post
-  attribute :publish_date, :datetime, default: -> { Time.current }
-  attribute :notify_subscribers, :boolean, default: true
-
-  # Validations
-  validates :resource, presence: true
-  validates :publish_date, presence: true
-
-  private
-
-  def execute
-    # Business logic
-    resource.transaction do
-      resource.update!(
-        published_at: publish_date,
-        status: 'published'
-      )
-
-      # Side effects
-      NotifySubscribersJob.perform_later(resource) if notify_subscribers
-
-      # Return successful outcome
-      succeed(resource)
-        .with_message("Post published successfully!")
-        .with_redirect_response(resource_path(resource))
-    end
-  rescue => error
-    # Return failure outcome
-    failed(error.message)
-  end
-end
-```
-
-### Interaction Types (Auto-detected)
-- **Record Actions**: Have `attribute :resource` - work on single records
-- **Bulk Actions**: Have `attribute :resources` - work on multiple records
-- **Resource Actions**: Have neither - work at resource level (imports, etc.)
-
-### Interaction Execution Patterns
-- **Immediate**: Only `resource`/`resources` attribute → executes on click
-- **Modal**: Additional attributes → shows form modal first
-
-## Package Architecture
-
-### Feature Packages
-Contain business logic and domain models:
-```bash
-rails generate pu:pkg:package blogging
-```
-
-Structure:
-```
-packages/blogging/
-├── app/
-│   ├── models/blogging/
-│   ├── definitions/blogging/
-│   ├── policies/blogging/
-│   ├── interactions/blogging/
-│   └── controllers/blogging/
-└── lib/engine.rb
-```
-
-### Portal Packages
-Provide web interfaces with routing and authentication:
-```bash
-rails generate pu:pkg:portal admin
-```
-
-Portal Engine:
-```ruby
-module AdminPortal
-  class Engine < ::Rails::Engine
-    include Plutonium::Portal::Engine
-
-    # Multi-tenancy
-    scope_to_entity Organization, strategy: :path
-  end
-end
-```
-
-Portal Routes:
-```ruby
-AdminPortal::Engine.routes.draw do
-  register_resource Blog::Post
-  register_resource Blog::Comment
-  register_resource User
-end
-```
-
-Portal Controller:
-```ruby
-module AdminPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-      include Plutonium::Auth::Rodauth(:admin)
-
-      included do
-        before_action :ensure_admin_access
-        layout "admin_portal"
-      end
-
-      private
-
-      def ensure_admin_access
-        redirect_to root_path unless current_user&.admin?
-      end
-    end
-  end
-end
-```
-
-## Authentication & Authorization
-
-### Rodauth Setup
-```bash
-# Install Rodauth
-rails generate pu:rodauth:install
-
-# Create user account
-rails generate pu:rodauth:account user
-
-# Create admin account with MFA
-rails generate pu:rodauth:account admin --no-defaults \
-  --login --logout --remember --lockout \
-  --create-account --verify-account --close-account \
-  --change-password --reset-password --reset-password-notify \
-  --active-sessions --password-grace-period --otp \
-  --recovery-codes --audit-logging --internal-request
-```
-
-### Authentication Integration
-```ruby
-# In portal controller concerns
-include Plutonium::Auth::Rodauth(:user)     # For user authentication
-include Plutonium::Auth::Rodauth(:admin)    # For admin authentication
-include Plutonium::Auth::Public             # For public access
-```
-
-## Routing & Custom Routes
-
-### Resource Registration
-```ruby
-# Basic resource registration
-register_resource Post
-
-# Custom routes with member/collection actions
-register_resource Post do
-  member do
-    get :publish      # /posts/1/publish
-    post :archive     # /posts/1/archive
-  end
-
-  collection do
-    get :search       # /posts/search
-  end
-end
-```
-
-### Common Routing Errors
-
-#### "Unresolvable Association" Error
-When adding custom routes inside `register_resource` blocks, Plutonium may interpret them as nested resources and fail with:
-```
-RuntimeError (Could not resolve the association between 'Model' and 'Model')
-```
-
-**Problem**: Routes like this create nested resource interpretation:
-```ruby
-register_resource ::UniversalFlow::Definition do
-  get "editor", to: "universal_flow/definitions#editor"
-end
-```
-
-**Solutions**:
-
-1. **Add custom scope to model (Recommended)**:
-```ruby
-class UniversalFlow::Definition < ApplicationRecord
-  scope :associated_with_universal_flow_definition, ->(universal_flow_definition) {
-    all # or specific logic for your use case
-  }
-end
-```
-
-2. **Use member/collection routes**:
-```ruby
-register_resource ::UniversalFlow::Definition do
-  member do
-    get :editor
-  end
-end
-```
-
-3. **Create separate controller**:
-```ruby
-# In routes file
-get 'universal_flow/editor/:id', to: 'universal_flow/editor#show'
-
-# Create dedicated controller
-class UniversalFlow::EditorController < CustomerPortal::ResourceController
-  def show
-    @definition = UniversalFlow::Definition.find(params[:id])
-    authorize_current! @definition
-    # ... custom logic
-  end
-end
-```