plutonium 0.23.4 → 0.23.5

data/docs/.vitepress/config.ts

@@ -9,6 +9,7 @@ export default defineConfig(withMermaid({
   title: "Plutonium",
   description: "The Ultimate Rapid Application Development Toolkit (RADKit) for Rails",
   head: [["link", { rel: "icon", href: `${base}favicon.ico` }]],
+  ignoreDeadLinks: 'localhostLinks',
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     logo: "/plutonium.png",
@@ -17,38 +18,78 @@ export default defineConfig(withMermaid({
     },
     nav: [
       { text: "Home", link: "/" },
-      { text: "Guide", link: "/guide/getting-started" },
+      { text: "Guide", link: "/guide/introduction/01-what-is-plutonium" },
+      { text: "Tutorial", link: "/guide/tutorial/01-project-setup" },
+      { text: "Modules", link: "/modules/" },
       { text: "Demo", link: "https://plutonium-app.onrender.com/" }
     ],
     sidebar: {
       '/guide/': [
-
+        {
+          text: "Getting Started",
+          items: [
+            { text: "Installation", link: "/guide/getting-started/01-installation" },
+          ]
+        },
         {
           text: "Introduction",
           items: [
-            { text: "What is Plutonium?", link: "/guide/what-is-plutonium" },
-            { text: "Tutorial", link: "/guide/tutorial" },
+            { text: "What is Plutonium?", link: "/guide/introduction/01-what-is-plutonium" },
+            { text: "Core Concepts", link: "/guide/introduction/02-core-concepts" },
           ]
         },
         {
-          text: "Getting Started",
+          text: "Tutorial (Building a Blog)",
+          collapsed: false,
           items: [
-            { text: "Overview", link: "/guide/getting-started/" },
-            { text: "Installation", link: "/guide/getting-started/installation" },
-            { text: "Core Concepts", link: "/guide/getting-started/core-concepts" },
-            { text: "Resources", link: "/guide/getting-started/resources" },
-            { text: "Authorization", link: "/guide/getting-started/authorization" },
+            { text: "1. Project Setup", link: "/guide/tutorial/01-project-setup" },
+            { text: "2. Creating a Feature Package", link: "/guide/tutorial/02-creating-a-feature-package" },
+            { text: "3. Defining Resources", link: "/guide/tutorial/03-defining-resources" },
+            { text: "4. Creating a Portal", link: "/guide/tutorial/04-creating-a-portal" },
+            { text: "5. Customizing the UI", link: "/guide/tutorial/05-customizing-the-ui" },
+            { text: "6. Adding Custom Actions", link: "/guide/tutorial/06-adding-custom-actions" },
+            { text: "7. Implementing Authorization", link: "/guide/tutorial/07-implementing-authorization" },
           ]
         },
-        // { text: "Quick Start", link: "/installation" },
-
-        // {
-        //   text: "Examples",
-        //   items: [
-        //     { text: "Markdown Examples", link: "/installation" },
-        //     { text: "Runtime API Examples", link: "/api-examples" }
-        //   ]
-        // }
+        {
+          text: "Deep Dive",
+          items: [
+            { text: "Resources", link: "/guide/deep-dive/resources" },
+            { text: "Authorization", link: "/guide/deep-dive/authorization" },
+            { text: "Modules", link: "/modules/" },
+          ]
+        },
+        {
+          text: "Developer Tools",
+          items: [
+            { text: "Cursor Rules", link: "/guide/cursor-rules" },
+          ]
+        }
+      ],
+      '/modules/': [
+        {
+          text: "Modules",
+          items: [
+            { text: "Overview", link: "/modules/" },
+            { text: "Action", link: "/modules/action" },
+            { text: "Authentication", link: "/modules/authentication" },
+            { text: "Configuration", link: "/modules/configuration" },
+            { text: "Core", link: "/modules/core" },
+            { text: "Definition", link: "/modules/definition" },
+            { text: "Display", link: "/modules/display" },
+            { text: "Form", link: "/modules/form" },
+            { text: "Generator", link: "/modules/generator" },
+            { text: "Interaction", link: "/modules/interaction" },
+            { text: "Package", link: "/modules/package" },
+            { text: "Policy", link: "/modules/policy" },
+            { text: "Portal", link: "/modules/portal" },
+            { text: "Query", link: "/modules/query" },
+            { text: "Resource Record", link: "/modules/resource_record" },
+            { text: "Routing", link: "/modules/routing" },
+            { text: "Table", link: "/modules/table" },
+            { text: "UI", link: "/modules/ui" },
+          ]
+        }
       ]
     },
     socialLinks: [

data/docs/guide/cursor-rules.md

@@ -0,0 +1,75 @@
+---
+title: Cursor Rules for Plutonium Development
+---
+
+<script setup>
+import { withBase } from 'vitepress'
+</script>
+
+# Cursor Rules for Plutonium Development
+
+This page provides comprehensive cursor rules for building Plutonium applications effectively. These rules are designed to help AI assistants and developers understand the framework's patterns and best practices.
+
+## Quick Start
+
+**Download the Rules File**: <a :href="withBase('/plutonium.mdc')" target="_blank">📄 plutonium.mdc</a>
+
+**Or download directly from your terminal**:
+
+::: code-group
+
+```bash [Unix/Linux/macOS/WSL]
+mkdir -p .cursor/rules && curl -o .cursor/rules/plutonium.mdc https://radioactive-labs.github.io/plutonium-core/plutonium.mdc
+```
+
+```cmd [Windows]
+mkdir .cursor\rules 2>nul & curl -o .cursor\rules\plutonium.mdc https://radioactive-labs.github.io/plutonium-core/plutonium.mdc
+```
+
+:::
+
+## Using These Rules
+
+Cursor uses Project Rules stored in `.cursor/rules/` directory:
+
+1. **Download the rules file**: Right-click the link above and "Save As" to download the `.plutonium.mdc` file
+2. **Open Cursor Settings** → Rules → Project Rules
+3. **Click "Add new rule"** and give it a name (e.g., "plutonium")
+4. **Copy the downloaded content** into the new rule file
+5. The rule will be saved as `.cursor/rules/plutonium.mdc`
+
+**Legacy Method**: You can also place the downloaded `.plutonium.mdc` file in your project root, but this method is deprecated.
+
+## What's Included
+
+The cursor rules file contains comprehensive guidelines for:
+
+### 🏗️ **Framework Architecture**
+- Resource-oriented development patterns
+- Package architecture (Feature & Portal packages)
+- Component-based UI with Phlex
+- Business logic through Interactions
+
+### 📝 **Resource Development**
+- **Auto-detection philosophy** - Field types are automatically detected from models
+- **Definition patterns** - Only override when needed
+- **Policy-based authorization** - Fine-grained permissions
+- **Interaction-driven business logic** - Encapsulated operations
+
+### 🔧 **Development Patterns**
+- **Generator commands** for scaffolding
+- **Authentication setup** with Rodauth
+- **Multi-tenancy** with entity scoping
+- **Query objects** for filtering and search
+
+### 🎨 **UI Customization**
+- **Component architecture** with Phlex
+- **Custom display blocks** with `phlexi_tag`
+- **Conditional rendering** with context awareness
+- **Layout customization** patterns
+
+### ⚡ **Best Practices**
+- **Performance optimization** techniques
+- **Security guidelines** and defaults
+- **Code organization** principles
+- **Development workflow** recommendations

data/docs/guide/deep-dive/authorization.md

@@ -0,0 +1,189 @@
+# Deep Dive: Authorization
+
+Plutonium provides a robust authorization system built on top of [Action Policy](https://actionpolicy.evilmartians.io/). It's designed to be secure by default while offering fine-grained control over every aspect of your application's access control.
+
+## Core Principles
+
+Authorization in Plutonium is handled by **Policy** classes. Every resource should have a corresponding policy that inherits from `Plutonium::Resource::Policy`.
+
+A policy's primary job is to answer the question: "Can the current `user` perform this `action` on this `record`?"
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  # Can the user see a list of posts?
+  def index?
+    true # Everyone can see the list
+  end
+
+  # Can the user update this specific post?
+  def update?
+    # `record` is the post instance.
+    # `user` is the current authenticated user.
+    record.author == user || user.admin?
+  end
+
+  # ... other permissions
+end
+```
+
+## Secure by Default: The Permission Chain
+
+Plutonium policies are secure by default. If a permission is not explicitly granted, it's denied. This is achieved through a clear inheritance chain.
+
+::: code-group
+```ruby [Core Permissions]
+# These are the base permissions.
+# They both default to `false`. You MUST override them.
+def create?
+  false
+end
+
+def read?
+  false
+end
+```
+```ruby [Derived Permissions]
+# These permissions inherit from the core ones.
+# You can override them for more granular control.
+def update?
+  create?
+end
+
+def destroy?
+  create?
+end
+
+def index?
+  read?
+end
+
+def show?
+  read?
+end
+```
+:::
+
+::: danger Always Define Core Permissions
+Because `create?` and `read?` default to `false`, you must define them in your policy to grant any access. If `create?` is `false`, then `update?` and `destroy?` will also be `false` unless you explicitly override them.
+:::
+
+## Attribute & Association Permissions
+
+Beyond actions, policies also control access to a resource's data at a granular level.
+
+### Attribute Permissions
+
+Attribute permissions control which fields a user can see or submit in a form. They follow a similar inheritance chain.
+
+::: code-group
+```ruby [Read Attributes]
+# Controls which fields are returned for `index` and `show` actions.
+def permitted_attributes_for_read
+  # By default, auto-detects all columns in development,
+  # but MUST be overridden for production.
+end
+```
+```ruby [Create/Update Attributes]
+# Controls which fields are allowed in `create` and `update` actions.
+def permitted_attributes_for_create
+  # By default, auto-detects columns (minus some system ones)
+  # in development, but MUST be overridden for production.
+end
+
+def permitted_attributes_for_update
+  # Inherits from `permitted_attributes_for_create` by default.
+  permitted_attributes_for_create
+end
+```
+:::
+
+::: warning Override in Production
+The default auto-detection for attributes only works in development to speed up initial scaffolding. You **must** override `permitted_attributes_for_create` and `permitted_attributes_for_read` in your policies for them to work in production.
+:::
+
+### Association Permissions
+
+By default, no associations are permitted. You must explicitly list which related resources can be included.
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  def permitted_associations
+    [:comments, :author]
+  end
+end
+```
+
+## Scoping: Filtering Collections
+
+A policy's `relation_scope` is used to filter down a collection of records to only what the current user should see. This is applied automatically on `index` pages.
+
+::: code-group
+```ruby [Simple Scope]
+class PostPolicy < Plutonium::Resource::Policy
+  relation_scope do |relation|
+    if user.admin?
+      relation # Admins see all posts
+    else
+      # Others only see their own posts or published posts
+      relation.where(author: user).or(relation.where(published: true))
+    end
+  end
+end
+```
+```ruby [Multi-Tenant Scope]
+class PostPolicy < Plutonium::Resource::Policy
+  relation_scope do |relation|
+    # `super` applies the portal's entity scoping first
+    # e.g., `relation.associated_with(current_organization)`
+    relation = super(relation)
+
+    # Then, apply additional logic
+    if user.admin?
+      relation
+    else
+      relation.where(published: true)
+    end
+  end
+end
+```
+:::
+
+## Authorization Context
+
+Policies have access to a `context` object. By default, Plutonium provides two:
+
+-   **`user`**: The current authenticated user. This is **required**.
+-   **`entity_scope`**: The current portal's multi-tenancy record (e.g., the current `Organization`). This is optional.
+
+You can add your own custom context objects for more complex scenarios.
+
+::: details Adding Custom Context
+Imagine you have a separate `Ability` system that you also want to check.
+
+**1. Define the context in the Policy:**
+```ruby
+class PostPolicy < ResourcePolicy
+  authorize :ability, allow_nil: true
+
+  def promote?
+    # You can now use `ability` in your permission checks
+    user.admin? && ability&.can?(:promote, record)
+  end
+end
+```
+
+**2. Provide the context from the Controller:**
+```ruby
+class PostsController < ResourceController
+  # This tells the policy how to find the `ability` object.
+  authorize :ability, through: :current_ability
+
+  private
+
+  def current_ability
+    # Your custom logic to find the ability object
+    Ability.new(user)
+  end
+end
+```
+:::

data/docs/guide/{getting-started → deep-dive}/resources.md

@@ -248,3 +248,140 @@ end
 - Remember to scope resources appropriately
 - Test your interactions and policies
 :::
+
+# Deep Dive: Building a Resource
+
+In Plutonium, a **Resource** is the central concept for managing your application's data. It's more than just a model—it's a complete package that includes the model, controller, policy, views, and all the configuration that ties them together.
+
+This guide will walk you through building a complete `Post` resource from scratch, demonstrating how Plutonium's different modules work together to create a powerful and consistent user experience.
+
+## 1. Generating the Resource
+
+We'll start with the scaffold generator, which creates all the necessary files for our `Post` resource.
+
+```bash
+rails generate pu:res:scaffold Post user:belongs_to title:string content:text published_at:datetime
+```
+
+This command generates:
+- A `Post` model with the specified attributes and a `belongs_to :user` association.
+- A `PostsController`.
+- A `PostPolicy` with basic permissions.
+- A `PostDefinition` file, which will be the focus of this guide.
+
+## 2. Configuring Display & Forms (The Definition File)
+
+The **Definition** file (`app/definitions/post_definition.rb`) is where you declaratively configure how your resource is displayed and edited. Let's start by defining the fields for our table, detail page, and form.
+
+::: code-group
+```ruby [app/definitions/post_definition.rb]
+class PostDefinition < Plutonium::Resource::Definition
+  # Configure the table (index view)
+  column :user, label: "Author"
+  column :published_at, as: :datetime
+
+  # Configure the detail page (show view)
+  display :user, label: "Author"
+  display :published_at, as: :datetime
+  display :content, as: :rich_text
+
+  # Configure the form (new/edit views)
+  input :user, as: :select, label: "Author" # Explicitly use a select input
+  input :content, as: :rich_text
+end
+```
+```ruby [app/policies/post_policy.rb]
+# In the policy, we must permit these attributes to be read and written.
+class PostPolicy < Plutonium::Resource::Policy
+  # ...
+
+  def permitted_attributes_for_read
+    [:title, :user, :published_at, :content]
+  end
+
+  def permitted_attributes_for_create
+    [:title, :user_id, :content]
+  end
+
+  def permitted_attributes_for_update
+    permitted_attributes_for_create
+  end
+end
+```
+:::
+
+Here, we've used the `display` helper to control the `index` and `show` views, and the `input` helper for the forms. We've also specified `:rich_text` to get a WYSIWYG editor for our content. Notice that we also had to permit these attributes in the policy.
+
+## 3. Adding a Custom Action
+
+Standard CRUD is great, but most applications have custom business logic. Let's add a "Publish" action. This involves creating an **Interaction** for the logic and registering it in the definition.
+
+::: code-group
+```ruby [app/interactions/post_interactions/publish.rb]
+module PostInteractions
+  class Publish < Plutonium::Resource::Interaction
+    attribute :resource, class: "Post"
+
+    private
+
+    def execute
+      resource.update(published_at: Time.current)
+      succeed(resource).with_message("Post was successfully published.")
+    end
+  end
+end
+```
+```ruby [app/definitions/post_definition.rb]
+class PostDefinition < Plutonium::Resource::Definition
+  # ... (display and input helpers)
+
+  action :publish,
+    interaction: "PostInteractions::Publish",
+    category: :primary
+end
+```
+```ruby [app/policies/post_policy.rb]
+class PostPolicy < Plutonium::Resource::Policy
+  # ... (attribute permissions)
+
+  # An action is only visible if its policy returns true.
+  def publish?
+    # Only show the publish button if the post is not yet published.
+    update? && record.published_at.nil?
+  end
+end
+```
+:::
+
+We now have a "Publish" button on our `Post` detail page that only appears when appropriate, thanks to the combination of the Interaction, Definition, and Policy.
+
+## 4. Configuring Search, Filters, and Sorting
+
+To make our resource table more useful, let's add search, filtering, and sorting capabilities. This is all handled declaratively in the definition file.
+
+```ruby
+# app/definitions/post_definition.rb
+class PostDefinition < Plutonium::Resource::Definition
+  # ... (display, input, and action helpers)
+
+  # Enable full-text search across title and content
+  search do |scope, query|
+    scope.where("title ILIKE :q OR content ILIKE :q", q: "%#{query}%")
+  end
+
+  # Add filters to the sidebar
+  filter :published, with: ->(scope, value) { value ? scope.where.not(published_at: nil) : scope.where(published_at: nil) }, as: :boolean
+  filter :user, as: :select, collection: -> { User.pluck(:name, :id) }
+
+  # Define named scopes that appear as buttons
+  scope :all
+  scope :published, -> { where.not(published_at: nil) }
+  scope :drafts, -> { where(published_at: nil) }
+
+  # Configure which columns are sortable
+  sort :title
+  sort :published_at
+end
+```
+
+With just a few lines of code, we now have a powerful and interactive table view for our posts, complete with a search bar, filter sidebar, scope buttons, and sortable columns. This demonstrates how the **Resource** module integrates seamlessly with the **Query** module.

data/docs/guide/getting-started/{installation.md → 01-installation.md}

@@ -136,72 +136,6 @@ end
 You can use your existing authentication system by implementing the `current_user` method in `ResourceController`.
 :::
 
-<!--
-## Asset Pipeline Setup
-
-### JavaScript Setup
-
-
-Plutonium uses modern JavaScript features. Here's how to set it up:
-
-1. Install required npm packages:
-
-::: code-group
-```bash [importmap]
-bin/importmap pin @radioactive-labs/plutonium
-```
-
-```bash [esbuild]
-yarn add @radioactive-labs/plutonium
-```
-:::
-
-
-2. Configure JavaScript:
-
-::: code-group
-```js [app/javascript/controllers/index.js]
-import { application } from "controllers/application"
-import { registerControllers } from "@radioactive-labs/plutonium" // [!code ++]
-registerControllers(application) // [!code ++]
-```
-
-```js [app/javascript/application.js]
-import "@hotwired/turbo-rails"
-import "controllers"
-```
-:::
-
-### CSS Setup
-
-Plutonium uses Tailwind CSS. Configure it in your `tailwind.config.js`:
-
-```js
-const defaultTheme = require('tailwindcss/defaultTheme')
-
-module.exports = {
-  content: [
-    './app/views/**/*.erb',
-    './app/helpers/**/*.rb',
-    './app/javascript/**/*.js',
-    './app/components/**/*.{erb,rb}',
-    './node_modules/@radioactive-labs/plutonium/**/*.{js,ts}'
-  ],
-  theme: {
-    extend: {
-      fontFamily: {
-        sans: ['Inter var', ...defaultTheme.fontFamily.sans],
-      },
-    },
-  },
-  plugins: [
-    require('@tailwindcss/forms'),
-    require('flowbite/plugin')
-  ],
-}
-```
--->
-
 ## Optional Enhancements
 
 ### Database Performance
@@ -229,42 +163,3 @@ rails generate pu:gem:annotated
 # Set up environment variables
 rails generate pu:gem:dotenv
 ```
-
-<!--
-## Verification
-
-Verify your installation:
-
-```bash
-# Start your Rails server
-rails server
-
-# Check your logs for any warnings or errors
-tail -f log/development.log
-
-# Generate and test a sample resource
-rails generate pu:res:scaffold Post title:string content:text
-```
-
-Visit `http://localhost:3000/posts` to verify everything is working.
--->
-
-<!--
-::: tip Next Steps
-Now that you have Plutonium installed and configured, you're ready to:
-1. [Create your first resource](/guide/resources/creating-resources)
-2. [Set up your first package](/guide/packages/creating-packages)
-3. [Configure authorization](/guide/authorization/basic-setup)
-:::
--->
-
-<!--
-### Getting Help
-
-If you run into issues:
-
-1. Check the [FAQ](/guide/faq)
-2. Search [GitHub Issues](https://github.com/radioactive-labs/plutonium-core/issues)
-3. Join our [Discord Community](https://discord.gg/plutonium)
-4. Create a new [GitHub Issue](https://github.com/radioactive-labs/plutonium-core/issues/new)
--->

data/docs/guide/index.md

@@ -0,0 +1,28 @@
+---
+layout: home
+title: Plutonium Documentation
+hero:
+  name: Plutonium Documentation
+  text: A RAD toolkit for Rails
+  tagline: Build better applications, faster.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/introduction/01-what-is-plutonium
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/radioactive-labs/plutonium
+features:
+  - title: Introduction
+    details: Learn about the core concepts and architecture of Plutonium.
+    link: /guide/introduction/01-what-is-plutonium
+  - title: Tutorial
+    details: A step-by-step guide to building your first application.
+    link: /guide/tutorial/01-project-setup
+  - title: Deep Dive Guides
+    details: In-depth explanations of specific Plutonium features.
+    link: /guide/deep-dive/resources
+  - title: Module Documentation
+    details: Detailed documentation for each Plutonium module.
+    link: /modules/
+---