plutonium 0.33.0 → 0.34.0

data/docs/guide/tutorial/01-project-setup.md

@@ -1,75 +0,0 @@
-# 1. Project Setup
-
-Welcome to the Plutonium tutorial! In this guide, we'll build a complete blog application from scratch.
-
-First, let's get a new Rails application up and running with Plutonium installed.
-
-## Prerequisites
-
-Before you begin, make sure you have the following installed:
-
-- Ruby 3.2.2 or higher
-- Rails 7.1 or higher
-- Node.js and Yarn
-
-If you're new to Rails, we highly recommend the official [Rails Getting Started Guide](https://guides.rubyonrails.org/getting_started.html) first.
-
-## Create a New Rails App
-
-We'll use the Plutonium Rails template to create a new application. This is the fastest way to get started.
-
-Open your terminal and run the following command:
-
-```bash
-rails new plutonium_blog -a propshaft -j esbuild -c tailwind \
-  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
-```
-
-This command creates a new Rails app named `plutonium_blog` and configures it with:
-- `propshaft` for assets
-- `esbuild` for JavaScript bundling
-- `TailwindCSS` for styling
-- The base Plutonium gem and configurations
-
-## Explore the Project
-
-Once the command finishes, navigate into your new project's directory:
-
-```bash
-cd plutonium_blog
-```
-
-The installer has already set up the core files you need. Here are the most important ones for now:
-
-```
-plutonium_blog/
-├── app/
-│   ├── controllers/
-│   │   ├── plutonium_controller.rb # Base controller for Plutonium
-│   │   └── resource_controller.rb  # Base for all resource controllers
-│   └── views/
-│       └── layouts/
-│           └── resource.html.erb   # Default layout for Plutonium views
-├── config/
-│   ├── initializers/
-│   │   └── plutonium.rb           # Main Plutonium configuration
-│   └── packages.rb                # How custom packages are loaded
-└── packages/                      # Where you'll build your features
-    └── .keep
-```
-
-## Start the Server
-
-Let's boot up the Rails server to make sure everything is working correctly.
-
-```bash
-bin/dev
-```
-
-Open your web browser and navigate to [http://localhost:3000](http://localhost:3000). You should see the default Rails welcome page.
-
-## Next Steps
-
-Congratulations! You have a fresh Plutonium application ready to go.
-
-In the next chapter, we'll create our first **Feature Package** to house all the logic for our blog.

data/docs/guide/tutorial/02-creating-a-feature-package.md

@@ -1,45 +0,0 @@
-# 2. Creating a Feature Package
-
-Now that we have our Rails application, it's time to start organizing our code. In Plutonium, we do this using **Packages**.
-
-## What are Packages?
-
-Packages are like mini-Rails applications (Rails Engines) that live inside your main app. They help you group related code together, making your application more modular and easier to maintain.
-
-There are two main types of packages, but for now, we'll focus on **Feature Packages**.
-
-A **Feature Package** holds all the business logic for a specific feature. In our case, we'll create a `Blogging` package to hold everything related to blog posts and comments.
-
-## Generate the Package
-
-Plutonium comes with a generator to create feature packages. Run the following command in your terminal:
-
-```bash
-rails generate pu:pkg:package blogging
-```
-
-This command creates a new directory at `packages/blogging` with the structure for your new package.
-
-```
-packages/
-└── blogging/
-    ├── app/
-    │   ├── controllers/
-    │   │   └── blogging/           # Controllers for this package
-    │   ├── definitions/
-    │   │   └── blogging/           # Resource definitions
-    │   ├── interactions/
-    │   │   └── blogging/           # Business logic actions
-    │   ├── models/
-    │   │   └── blogging/           # ActiveRecord models
-    │   └── policies/
-    │       └── blogging/           # Authorization policies
-    └── lib/
-        └── engine.rb             # The engine configuration
-```
-
-Every file and class inside this package will be automatically namespaced under the `Blogging` module to prevent conflicts with other parts of your application.
-
-## Next Steps
-
-With our `Blogging` package in place, we're ready to define the core data models for our application. In the next chapter, we'll create the `Post` and `Comment` resources.

data/docs/guide/tutorial/03-defining-resources.md

@@ -1,90 +0,0 @@
-# 3. Defining Resources
-
-With our `Blogging` package ready, we can now define the core **Resources** of our feature: `Post` and `Comment`. But first, we need a way to represent users, since posts and comments will belong to a user.
-
-## Setting Up Users and Authentication
-
-Plutonium provides generators to quickly set up user authentication using the popular [Rodauth](https://rodauth.jeremyevans.net/) library.
-
-Run the following commands in your terminal:
-
-```bash
-# 1. Install Rodauth configuration
-rails generate pu:rodauth:install
-
-# 2. Generate a User model and authentication logic
-rails generate pu:rodauth:account user
-
-# 3. Run the database migrations
-rails db:migrate
-```
-
-This is a huge time-saver! It creates:
-- A `User` model (`app/models/user.rb`).
-- Database migrations for the `users` table.
-- All the necessary authentication logic (login, logout, sign up, password reset, etc.).
-
-Now that we have a `User` model, we can create our blog-specific resources.
-
-## Scaffolding the Post Resource
-
-A **Resource** in Plutonium is more than just a model; it's a combination of the model, its definition (how it's displayed), and its policy (who can do what).
-
-Let's scaffold our `Post` resource. It will have a title, some text content, and will belong to a `User`.
-
-```bash
-rails generate pu:res:scaffold Post user:belongs_to title:string content:text 'published_at:datetime?'
-```
-
-The generator will prompt you to choose which package this resource belongs to. **Select `blogging`**.
-
-This command generates several important files inside your `packages/blogging` directory:
-
-- `app/models/blogging/post.rb`: The ActiveRecord model.
-- `app/definitions/blogging/post_definition.rb`: The resource definition for UI.
-- `app/policies/blogging/post_policy.rb`: The authorization policy.
-- A database migration to create the `blogging_posts` table.
-
-Let's look at the generated model at `packages/blogging/app/models/blogging/post.rb`:
-
-```ruby
-# packages/blogging/app/models/blogging/post.rb
-class Blogging::Post < Blogging::ResourceRecord
-  belongs_to :user
-  validates :title, presence: true
-  validates :content, presence: true
-end
-```
-Notice it's correctly namespaced under `Blogging` and associated with the `User` model.
-
-Before we continue, run the migration to update your database:
-```bash
-rails db:migrate
-```
-
-## Scaffolding the Comment Resource
-
-Now, let's do the same for `Comment`. A comment will belong to a `User` and a `Post`.
-
-```bash
-rails generate pu:res:scaffold Comment user:belongs_to blogging/post:belongs_to body:text
-```
-
-Again, select the **`blogging`** package when prompted.
-
-::: tip Namespaced Associations
-Notice that we used `blogging/post` to specify the association. Plutonium's generators understand this and will correctly create the namespaced `Blogging::Post` association.
-:::
-
-This generates the model, definition, policy, and migration for comments.
-
-Run the migration for comments:
-```bash
-rails db:migrate
-```
-
-## Next Steps
-
-We've now set up users, authentication, and the core `Post` and `Comment` resources for our blog. However, there's no way to interact with them yet.
-
-In the next chapter, we'll create a **Portal** to provide a web interface for managing our new resources.

data/docs/guide/tutorial/04-creating-a-portal.md

@@ -1,101 +0,0 @@
-# 4. Creating a Portal
-
-We have our `Blogging` feature package with `Post` and `Comment` resources, but no user interface to manage them. Let's create a **Portal** to serve as a web interface for our blog.
-
-## What are Portal Packages?
-
-While Feature Packages hold business logic, **Portal Packages** provide the web interface. They are also Rails Engines, but they are responsible for things like:
-
-- Dashboards and layouts.
-- Routing requests to the correct resources.
-- Handling user authentication for the interface.
-
-We'll create a `Dashboard` portal for managing our blog.
-
-## Generate the Portal
-
-Plutonium has a generator for portals. In your terminal, run:
-
-```bash
-rails generate pu:pkg:portal dashboard
-```
-
-The generator will ask which authentication account to use. We already set up the `user` account with Rodauth, so **select `user`**.
-
-This creates a new package at `packages/dashboard_portal/` and wires it up for authentication.
-
-## Connect Resources to the Portal
-
-Now we need to tell our new `Dashboard` portal which resources it should manage. We can use the `pu:res:conn` (connect) generator for this.
-
-Run the connect generator:
-```bash
-rails generate pu:res:conn
-```
-
-It will ask you a series of questions:
-1.  **Select source feature**: Choose **`blogging`**.
-2.  **Select resources**: Use the spacebar to select both **`Blogging::Post`** and **`Blogging::Comment`**, then press Enter.
-3.  **Select destination portal**: Choose **`dashboard_portal`**.
-
-This command does the magic of connecting your feature logic to your UI. It updates the portal's routes file (`packages/dashboard_portal/config/routes.rb`) to register the resources:
-
-```ruby
-# packages/dashboard_portal/config/routes.rb
-DashboardPortal::Engine.routes.draw do
-  root to: "dashboard#index"
-
-  register_resource Blogging::Post
-  register_resource Blogging::Comment
-end
-```
-
-## Configure Application Routes
-
-There's one last step. We need to tell our main Rails application how to handle routing for authentication and the new dashboard.
-
-1.  **Update Rodauth Redirects**: We want users to be sent to the dashboard after they log in or sign up.
-
-    ```ruby [app/rodauth/user_rodauth_plugin.rb]
-    # ==> Redirects
-
-    # Redirect to home after login.
-    create_account_redirect "/" # [!code --]
-    create_account_redirect "/dashboard" # [!code ++]
-
-    # Redirect to home after login.
-    login_redirect "/" # [!code --]
-    login_redirect "/dashboard" # [!code ++]
-
-    # Redirect to home page after logout.
-    logout_redirect "/" # [!code --]
-    logout_redirect "/dashboard" # [!code ++]
-    ```
-
-2.  **Update Root Route**: We'll make the dashboard the root of our application.
-
-    ```ruby [config/routes.rb]
-    Rails.application.routes.draw do
-      # ...
-      # Defines the root path route ("/")
-      # root "posts#index" # [!code --]
-      root to: redirect("/dashboard") # [!code ++]
-    end
-    ```
-
-## See it in Action!
-
-Let's check our progress. Start your Rails server (`bin/dev`) and navigate to [http://localhost:3000](http://localhost:3000).
-
-You will be redirected to `/dashboard` and should see the login page.
-
-- **Sign up** for a new account.
-- After signing up, you'll be redirected to the dashboard. It will be empty for now, but this confirms the portal and authentication are working!
-
-![Plutonium Empty Dashboard](/tutorial/plutonium-posts-dashboard.png)
-
-## Next Steps
-
-We now have a functional dashboard! It's not very useful yet, though.
-
-In the next chapter, we will customize the user interface to display our posts and comments, and add navigation to make them accessible.

data/docs/guide/tutorial/05-customizing-the-ui.md

@@ -1,128 +0,0 @@
-# 5. Customizing the UI
-
-Our dashboard is functional, but it's not very user-friendly. In Plutonium, customizing the UI is a two-step process that respects the separation of concerns:
-
-1.  **Policy (`app/policies`)**: The policy file controls **what** a user is authorized to see or edit. This is a security layer.
-2.  **Definition (`app/definitions`)**: The definition file controls **how** those permitted fields are displayed and formatted. This is a presentation layer.
-
-Let's customize our `Post` resource by following this two-step process for the table, detail page, and form.
-
-## Customizing the Posts Table (Index View)
-
-First, we'll define **what** columns should appear in the posts table. This is an authorization concern, so we'll use the policy file.
-
-Open the post policy: `packages/blogging/app/policies/blogging/post_policy.rb`
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ... (other methods)
-
-  # 1. Define WHAT columns are visible in the table.
-  def permitted_attributes_for_index
-    [:user, :title, :published_at, :created_at]
-  end
-end
-```
-
-Next, we'll configure **how** these columns are displayed in the definition file.
-
-Open the post definition: `packages/blogging/app/definitions/blogging/post_definition.rb`
-
-```ruby
-# packages/blogging/app/definitions/blogging/post_definition.rb
-class Blogging::PostDefinition < Blogging::ResourceDefinition
-  # 2. Define HOW the permitted columns are rendered.
-  column :published_at, as: :datetime
-  column :created_at, as: :datetime
-end
-```
-
-The table now only shows the permitted columns, formatted as we specified.
-
-![Plutonium Posts Dashboard (Customized)](/tutorial/plutonium-posts-dashboard-customized.png)
-
-## Customizing the Post Detail Page (Show View)
-
-The same two-step process applies to the detail page.
-
-1.  **Policy**: Define what fields are visible with `permitted_attributes_for_show`.
-2.  **Definition**: Define how they are rendered with `display`.
-
-Let's define the fields in the policy. For this view, we want to show the `:content`.
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ...
-
-  def permitted_attributes_for_index
-    [:user, :title, :published_at, :created_at]
-  end
-
-  # 1. Define WHAT fields are visible on the show page.
-  def permitted_attributes_for_show
-    [:user, :title, :content, :published_at, :created_at]
-  end
-end
-```
-
-Now, let's configure the layout in the definition. We'll make each field take up the full width of the view.
-
-```ruby
-# packages/blogging/app/definitions/blogging/post_definition.rb
-class Blogging::PostDefinition < Blogging::ResourceDefinition
-  display :user, wrapper: { class: "col-span-full" }
-  display :title, wrapper: { class: "col-span-full" }
-  display :content, wrapper: { class: "col-span-full" }
-  display :published_at, wrapper: { class: "col-span-full" }
-  display :created_at, wrapper: { class: "col-span-full" }
-end
-```
-
-![Plutonium Posts Detail (Customized)](/tutorial/plutonium-posts-detail-customized.png)
-
-## Customizing the Post Form
-
-Finally, we'll customize the `new` and `edit` forms.
-
-1.  **Policy**: Use `permitted_attributes_for_create` and `_for_update` to control which fields can be submitted.
-2.  **Definition**: Use the `input` helper to control how the form inputs are rendered.
-
-First, the policy. We don't want the user to be able to set the `published_at` date directly in the form.
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ...
-
-  # 1. Define WHAT fields can be submitted in the form.
-  def permitted_attributes_for_create
-    [:user_id, :title, :content]
-  end
-
-  def permitted_attributes_for_update
-    permitted_attributes_for_create
-  end
-end
-```
-
-Now, the definition. We'll use the `input` helper to specify that `:content` should use a rich text editor.
-
-```ruby
-# packages/blogging/app/definitions/blogging/post_definition.rb
-class Blogging::PostDefinition < Blogging::ResourceDefinition
-  # ... (display helpers from above)
-
-  # 2. Define HOW the form inputs are rendered.
-  input :content, as: :rich_text # Use a rich text editor
-end
-```
-
-By separating what is permitted from how it is rendered, Plutonium gives you both security and flexibility.
-
-## Next Steps
-
-Our UI is now much more polished. We've used the **Policy** and **Definition** files together to customize our `Post` resource.
-
-In the next chapter, we'll add custom business logic by creating an **Action** to publish a draft post.

data/docs/guide/tutorial/06-adding-custom-actions.md

@@ -1,101 +0,0 @@
-# 6. Adding Custom Actions
-
-Our application now handles the basics of creating, reading, updating, and deleting posts and comments. But what about business logic that isn't simple CRUD? For this, Plutonium has **Actions**.
-
-An Action is a piece of business logic you can execute on a resource. We'll create a "Publish" action for our posts.
-
-Create a new file for our "interaction" at:
-`packages/blogging/app/interactions/blogging/post_interactions/publish.rb`
-
-## Implement the Interaction
-
-The "Interaction" is where the business logic for an action lives. Open the newly created file and let's implement the logic to publish a post.
-
-We want the action to set the `published_at` timestamp on the post.
-
-```ruby
-# packages/blogging/app/interactions/blogging/post_interactions/publish.rb
-module Blogging
-  module PostInteractions
-    class Publish < Plutonium::Resource::Interaction
-      # Define the attributes this interaction accepts
-      attribute :resource, class: "Blogging::Post"
-
-      # Define how this action is presented in the UI
-      presents label: "Publish Post",
-               description: "Make this post available for the public to see."
-
-      private
-
-      # The core business logic
-      def execute
-        if resource.update(published_at: Time.current )
-          succeed(resource)
-            .with_message("Post was successfully published.")
-            .with_redirect_response(resource)
-        else
-          failed(resource.errors)
-        end
-      end
-    end
-  end
-end
-```
-
-This class defines what the action needs (`resource`, `published_at`), how it looks (`presents`), and what it does (`execute`).
-
-## Configure the Action
-
-Now that we've defined the logic, we need to add the action to our `Post` resource and configure its visibility. We'll do this in the post's **definition** file.
-
-`packages/blogging/app/definitions/blogging/post_definition.rb`
-
-Add the `action` configuration:
-
-```ruby
-# packages/blogging/app/definitions/blogging/post_definition.rb
-class Blogging::PostDefinition < Blogging::ResourceDefinition
-  # ... (display helpers from the previous chapter)
-
-  action :publish,
-    interaction: "Blogging::PostInteractions::Publish"
-end
-```
-
-## Control Visibility with a Policy
-
-Plutonium actions are secure by default. If an action doesn't have a corresponding policy method allowing it, it won't be displayed.
-
-Let's define the logic for our `publish` action. We only want to show the "Publish" button if the post hasn't been published yet.
-
-Open the post policy file:
-`packages/blogging/app/policies/blogging/post_policy.rb`
-
-Add the `publish?` method:
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ... (other methods from previous chapters)
-
-  def publish?
-    # Only allow publishing if the user can update the post
-    # and the post has not been published yet.
-    update? && record.published_at.nil?
-  end
-end
-```
-
-This policy does two things:
-1. It ensures the user has permission to `update?` the post.
-2. It checks that `published_at` is `nil`.
-
-Now, go to the show page for a post you created. You should see the "Publish" button. Click it, and the `published_at` field will be set. Because `record.published_at.nil?` is now false, the policy will prevent the action from being shown again. The button disappears!
-
-![Plutonium Posts Publish Action](/tutorial/plutonium-publish-post.png)
-
-## Next Steps
-
-We've successfully added custom business logic to our application. Actions are a powerful way to build complex, maintainable features.
-
-In the final chapter of this tutorial, we'll tighten up security by implementing proper authorization rules.

data/docs/guide/tutorial/07-implementing-authorization.md

@@ -1,90 +0,0 @@
-# 7. Implementing Authorization
-
-Our blog is now fully functional, but it's not very secure. Any user can edit or delete any other user's posts. Let's fix this by implementing proper authorization rules using Plutonium's **Policy** system.
-
-## Understanding Policies
-
-For every resource, there is a corresponding Policy class that controls access. The policy methods (like `update?` or `destroy?`) return `true` or `false` to grant or deny permission.
-
-## Securing Post Actions
-
-Let's start by restricting the `update` and `publish` actions for posts. Open the post policy file:
-
-`packages/blogging/app/policies/blogging/post_policy.rb`
-
-Now, let's modify the policy to check if the current user (`user`) is the owner of the post (`record`).
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # Users can only update their own posts
-  def update?
-    record.user_id == user.id
-  end
-
-  # Only the owner can publish their post
-  def publish?
-    update? # Inherits from update?
-  end
-end
-```
-By default, `destroy?` also inherits from `update?`, so this one change secures all write operations.
-
-## Securing Comment Actions
-
-We should apply the same logic to comments. Open the comment policy:
-
-`packages/blogging/app/policies/blogging/comment_policy.rb`
-
-And add the same ownership check:
-
-```ruby
-# packages/blogging/app/policies/blogging/comment_policy.rb
-class Blogging::CommentPolicy < Blogging::ResourcePolicy
-  def update?
-    record.user_id == user.id
-  end
-end
-```
-
-## Scoping Visible Data
-
-We've secured the actions, but there's one more problem: every user can see every post in the index view. We should scope the list of posts so that users only see their own.
-
-This is done with the `relation_scope` in the post policy file. This scope is applied to all queries for the `Post` resource.
-
-`packages/blogging/app/policies/blogging/post_policy.rb`
-
-```ruby
-# packages/blogging/app/policies/blogging/post_policy.rb
-class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # ... (update? and publish? methods)
-
-  # Scope all queries to only include the current user's posts
-  relation_scope do |scope|
-    scope.where(user: user)
-  end
-end
-```
-Now, the posts index page will only show posts created by the currently logged-in user. This is a critical feature for multi-tenant applications.
-
-## Tutorial Complete!
-
-Congratulations! You have built a complete, secure, and modular blog application with Plutonium.
-
-You've learned how to:
-- Set up a Plutonium project.
-- Organize features into **Packages**.
-- Define and scaffold **Resources**.
-- Build a web interface with **Portals**.
-- Customize the UI.
-- Add custom business logic with **Actions**.
-- Secure your application with **Policies**.
-
-### Where to Go Next?
-
-You now have a strong foundation to build your own applications. To learn more about specific topics, check out our **Deep Dive Guides**:
-
-- **[Resources](./../deep-dive/resources.md)**: An in-depth look at fields, associations, filters, and more.
-- **[Authorization](./../deep-dive/authorization.md)**: A detailed guide to policies, scopes, and entity-based authorization.
-- ... more guides coming soon!