plutonium 0.33.1 → 0.34.0

data/docs/getting-started/tutorial/01-setup.md

@@ -0,0 +1,118 @@
+# Chapter 1: Project Setup
+
+In this chapter, you'll create a new Plutonium application and explore its structure.
+
+## Creating the Application
+
+Open your terminal and run:
+
+```bash
+rails new blog -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+```
+
+This creates a new Rails application with Plutonium pre-configured.
+
+When prompted, accept the defaults or customize as needed. The template will:
+- Install the Plutonium gem
+- Configure TailwindCSS 4
+- Set up Rodauth for authentication
+- Create the database schema
+
+## Starting the Server
+
+```bash
+cd blog
+bin/dev
+```
+
+Visit `http://localhost:3000`. You should see a welcome page.
+
+## Project Structure
+
+Let's explore what was created:
+
+```
+blog/
+├── app/
+│   ├── controllers/         # Standard Rails controllers
+│   ├── definitions/         # Plutonium definitions (how resources render)
+│   ├── interactions/        # Business logic classes
+│   ├── models/              # Standard Rails models
+│   ├── policies/            # Authorization policies
+│   └── views/               # Phlex view components
+├── packages/                # Feature packages and portals
+│   └── .keep
+├── config/
+│   └── initializers/
+│       └── plutonium.rb     # Plutonium configuration
+└── ...
+```
+
+### Key Directories
+
+**`app/definitions/`** - Contains Definition classes that control how resources are displayed. Fields, forms, tables, and actions are configured here.
+
+**`app/policies/`** - Contains Policy classes that control authorization. Who can do what with each resource.
+
+**`app/interactions/`** - Contains Interaction classes for complex business logic. Used for custom actions beyond simple CRUD.
+
+**`packages/`** - Contains Feature Packages (business logic modules) and Portal Packages (web interfaces).
+
+## Understanding Packages
+
+Plutonium uses two types of packages:
+
+### Feature Packages
+
+Feature packages contain your business logic - models, definitions, policies, interactions, and controllers. They're Rails engines that can be shared across multiple portals.
+
+```
+packages/
+└── blogging/                # Feature package
+    ├── app/
+    │   ├── controllers/blogging/
+    │   ├── definitions/blogging/
+    │   ├── interactions/blogging/
+    │   ├── models/blogging/
+    │   ├── policies/blogging/
+    │   └── views/blogging/
+    └── lib/
+        └── engine.rb
+```
+
+### Portal Packages
+
+Portal packages are web interfaces that expose resources to users. Each portal can have its own authentication, authorization rules, and UI customizations.
+
+```
+packages/
+└── admin_portal/            # Portal package
+    ├── app/
+    │   ├── controllers/admin_portal/
+    │   └── views/admin_portal/
+    └── lib/admin_portal/
+        └── engine.rb
+```
+
+## Configuration
+
+Open `config/initializers/plutonium.rb`:
+
+```ruby
+Plutonium.configure do |config|
+  config.load_defaults 1.0
+
+  # Configure plutonium above.
+end
+```
+
+The defaults work well out of the box. Available options include:
+- `config.development` - Enable development mode
+- `config.cache_discovery` - Cache resource discovery (auto-configured per environment)
+- `config.assets.logo` - Custom logo path
+
+## What's Next
+
+In the next chapter, we'll create our first resource - the Post model with its definition and policy.
+
+[Continue to Chapter 2: Creating Your First Resource →](./02-first-resource)

data/docs/getting-started/tutorial/02-first-resource.md

@@ -0,0 +1,180 @@
+# Chapter 2: Creating Your First Resource
+
+In this chapter, you'll create the Post resource - the core of our blog application.
+
+## What is a Resource?
+
+In Plutonium, a **resource** is a complete unit consisting of:
+- **Model** - The data structure (ActiveRecord)
+- **Definition** - How the resource renders (fields, actions, UI)
+- **Policy** - Who can do what (authorization)
+- **Controller** - HTTP handling (auto-generated or custom)
+
+## Generating a Feature Package
+
+First, let's create a feature package to hold our blogging logic:
+
+```bash
+rails generate pu:pkg:package blogging
+```
+
+This creates:
+
+```
+packages/blogging/
+├── app/
+│   ├── controllers/blogging/
+│   ├── definitions/blogging/
+│   ├── interactions/blogging/
+│   ├── models/blogging/
+│   ├── policies/blogging/
+│   └── views/blogging/
+└── lib/
+    └── engine.rb
+```
+
+## Generating the Post Resource
+
+Now generate the Post resource inside the blogging package:
+
+```bash
+rails generate pu:res:scaffold Post title:string body:text 'published:boolean?' --dest=blogging
+```
+
+This creates:
+
+### Model (`packages/blogging/app/models/blogging/post.rb`)
+
+```ruby
+class Blogging::Post < Blogging::ResourceRecord
+  # Add validations, associations, and business logic here
+end
+```
+
+### Definition (`packages/blogging/app/definitions/blogging/post_definition.rb`)
+
+```ruby
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  # Customize field rendering, forms, and UI here
+end
+```
+
+### Policy (`packages/blogging/app/policies/blogging/post_policy.rb`)
+
+```ruby
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  def create?
+    true
+  end
+
+  def read?
+    true
+  end
+
+  def permitted_attributes_for_create
+    [:title, :body, :published]
+  end
+
+  def permitted_attributes_for_read
+    [:title, :body, :published]
+  end
+
+  def permitted_associations
+    %i[]
+  end
+end
+```
+
+### Migration
+
+```ruby
+class CreateBloggingPosts < ActiveRecord::Migration[8.0]
+  def change
+    create_table :blogging_posts do |t|
+      t.string :title, null: false
+      t.text :body, null: false
+      t.boolean :published
+
+      t.timestamps
+    end
+  end
+end
+```
+
+## Running the Migration
+
+```bash
+rails db:migrate
+```
+
+## Creating a Portal
+
+Resources need a portal to be accessible via the web. Let's create an admin portal:
+
+```bash
+rails generate pu:pkg:portal admin
+```
+
+This creates the AdminPortal package with authentication configured.
+
+## Connecting the Resource
+
+Connect the Post resource to the admin portal:
+
+```bash
+rails generate pu:res:conn Blogging::Post --dest=admin_portal
+```
+
+This:
+1. Adds routes for Post in the admin portal
+2. Creates a portal-specific controller
+3. Registers the resource with the portal
+
+## Starting the Server
+
+```bash
+bin/dev
+```
+
+Visit `http://localhost:3000/admin/blogging/posts`. You should see:
+- An empty posts table
+- A "New Post" button
+- Search and filter options
+
+Try creating a post. The form is automatically generated from your model's attributes.
+
+## Understanding Auto-Detection
+
+Notice that we wrote almost no configuration code. Plutonium auto-detected:
+
+- **Fields** from the model's columns
+- **Validations** from the model's validators
+- **Associations** from belongs_to/has_many
+- **Form inputs** based on column types
+- **Table columns** from the policy's permitted attributes
+
+This is Plutonium's core philosophy: **convention over configuration**. You only write code when you need to change the defaults.
+
+## Customizing Table Columns
+
+By default, Plutonium shows all permitted attributes in the table. To customize which columns appear, use the policy's `permitted_attributes_for_index` method:
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+module Blogging
+  class PostPolicy < Blogging::ResourcePolicy
+    # Control which columns appear in the index table
+    def permitted_attributes_for_index
+      [:title, :published, :created_at]
+    end
+  end
+end
+```
+
+Refresh the page. The table now shows only the columns you specified.
+
+## What's Next
+
+Our resource is working, but anyone can access it. In the next chapter, we'll add authentication with Rodauth.
+
+[Continue to Chapter 3: Setting Up Authentication →](./03-authentication)

data/docs/getting-started/tutorial/03-authentication.md

@@ -0,0 +1,246 @@
+# Chapter 3: Setting Up Authentication
+
+In this chapter, you'll configure Rodauth for user authentication.
+
+## What is Rodauth?
+
+Rodauth is a Ruby authentication framework that Plutonium uses for:
+- User registration and login
+- Password reset and email verification
+- Multi-factor authentication
+- Session management
+
+Plutonium integrates Rodauth seamlessly with its portal system.
+
+## Setting Up Authentication
+
+If you used the Plutonium template, Rodauth is already installed. If not:
+
+```bash
+rails generate pu:rodauth:install
+rails db:migrate
+```
+
+## Creating an Account Type
+
+Plutonium supports multiple account types. For admin accounts that cannot self-register, use the `admin` generator:
+
+```bash
+rails generate pu:rodauth:admin admin
+```
+
+This creates:
+
+### Account Model (`app/models/admin.rb`)
+
+```ruby
+class Admin < ResourceRecord
+  include Rodauth::Rails.model(:admin)
+end
+```
+
+### Rodauth Plugin (`app/rodauth/admin_rodauth_plugin.rb`)
+
+```ruby
+class AdminRodauthPlugin < RodauthPlugin
+  configure do
+    # Multi-phase login, 2FA, lockout, audit logging enabled
+    enable :login, :remember, :logout, ...
+
+    # No public signup - accounts created via rake task
+    before_create_account_route do
+      request.halt unless internal_request?
+    end
+  end
+end
+```
+
+The generator also creates migrations for the account table and authentication features.
+
+## Configuring the Portal
+
+Authentication is configured in the portal's controller concern. Update it to use Rodauth:
+
+```ruby
+# packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb
+module AdminPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+      include Plutonium::Auth::Rodauth(:admin)
+    end
+  end
+end
+```
+
+This provides `current_user` and authentication helpers throughout the portal.
+
+## Running Migrations
+
+```bash
+rails db:migrate
+```
+
+## Testing Authentication
+
+Restart your server:
+
+```bash
+bin/dev
+```
+
+Visit `http://localhost:3000/admin/blogging/posts`. You'll be redirected to the login page.
+
+### Creating an Admin Account
+
+Admin accounts are created via rake task (web registration is disabled for security):
+
+```bash
+rails rodauth:admin
+# Or with EMAIL environment variable:
+EMAIL=admin@example.com rails rodauth:admin
+```
+
+The task will prompt for an email if not provided and send a verification email with password setup instructions.
+
+Now log in with the account you created.
+
+## Customizing the Login Page
+
+The login page uses Plutonium's default theme. To customize it:
+
+```ruby
+# packages/admin_portal/app/views/admin_portal/auth/login.rb
+module AdminPortal
+  module Auth
+    class Login < Plutonium::Auth::View::Login
+      def page_title
+        "Admin Login"
+      end
+
+      def welcome_message
+        "Sign in to manage your blog"
+      end
+    end
+  end
+end
+```
+
+## Email Configuration
+
+For password reset and email verification, configure Action Mailer:
+
+```ruby
+# config/environments/development.rb
+config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }
+config.action_mailer.delivery_method = :letter_opener # Or :smtp for real emails
+```
+
+## Creating the User Account Type
+
+Our blog needs users (authors) who can create posts. Let's create a User account type that allows self-registration:
+
+```bash
+rails generate pu:rodauth:account user
+rails db:migrate
+```
+
+This creates a `User` model similar to `Admin`, but with public registration enabled.
+
+### Linking Posts to Users
+
+Now we can add the author relationship to our Post model. Generate a migration:
+
+```bash
+rails generate migration AddUserToBloggingPosts user:belongs_to
+```
+
+Update the migration to add the foreign key:
+
+```ruby
+class AddUserToBloggingPosts < ActiveRecord::Migration[8.0]
+  def change
+    add_reference :blogging_posts, :user, null: false, foreign_key: true
+  end
+end
+```
+
+Run the migration:
+
+```bash
+rails db:migrate
+```
+
+Update the Post model to include the association:
+
+```ruby
+# packages/blogging/app/models/blogging/post.rb
+class Blogging::Post < Blogging::ResourceRecord
+  belongs_to :user
+  # ... existing code
+end
+```
+
+Also update the Post policy to include user in permitted attributes:
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  def permitted_attributes_for_create
+    [:title, :body, :published, :user_id]
+  end
+
+  def permitted_attributes_for_read
+    [:title, :body, :published, :user, :created_at]
+  end
+
+  def permitted_associations
+    %i[user]
+  end
+end
+```
+
+Now posts are linked to their authors, which we'll use for authorization in the next chapter.
+
+## Multiple Account Types
+
+You can have different account types for different portals:
+
+```bash
+# Create an author account type (if using a different name than "user")
+rails generate pu:rodauth:account author
+```
+
+Then configure each portal's controller concern:
+
+```ruby
+# packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb
+include Plutonium::Auth::Rodauth(:admin)
+
+# packages/author_portal/app/controllers/author_portal/concerns/controller.rb
+include Plutonium::Auth::Rodauth(:author)
+```
+
+## Session Configuration
+
+Rodauth sessions can be configured in the Rodauth plugin:
+
+```ruby
+# app/rodauth/admin_rodauth_plugin.rb
+class AdminRodauthPlugin < RodauthPlugin
+  configure do
+    # Session expires after 30 days
+    session_expiration_seconds 30.days.to_i
+
+    # Require re-authentication for sensitive actions
+    password_grace_period 3600
+  end
+end
+```
+
+## What's Next
+
+Users can now log in, but anyone can do anything. In the next chapter, we'll implement authorization policies to control access.
+
+[Continue to Chapter 4: Implementing Authorization →](./04-authorization)

data/docs/getting-started/tutorial/04-authorization.md

@@ -0,0 +1,170 @@
+# Chapter 4: Implementing Authorization
+
+In this chapter, you'll implement authorization policies to control who can do what.
+
+## Understanding Policies
+
+Plutonium uses policy classes to control authorization at three levels:
+
+1. **Action Permissions** - Can the user perform this action? (create, read, update, delete)
+2. **Attribute Permissions** - Which attributes can the user see/modify?
+3. **Scope Permissions** - Which records can the user access?
+
+## The Policy Class
+
+Open the post policy:
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # By default, all actions are permitted
+  # Let's add some restrictions
+end
+```
+
+## Action Permissions
+
+Let's implement basic CRUD permissions:
+
+```ruby
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # Anyone can view published posts
+  def read?
+    record.published? || owner?
+  end
+
+  # Only the owner can edit
+  def update?
+    owner?
+  end
+
+  # Only the owner can delete
+  def destroy?
+    owner?
+  end
+
+  # Anyone authenticated can create
+  def create?
+    true
+  end
+
+  private
+
+  def owner?
+    record.user_id == user.id
+  end
+end
+```
+
+## Understanding the Policy Context
+
+Inside a policy, you have access to:
+
+| Accessor | Description |
+|----------|-------------|
+| `user` | The current authenticated user |
+| `record` | The resource being authorized |
+| `entity_scope` | Parent record for scoping (e.g., Organization in multi-tenant apps) |
+
+```ruby
+def some_permission?
+  user          # => Current user (from authentication)
+  record        # => The Post instance being checked
+  entity_scope  # => Parent record for multi-tenancy (or nil)
+end
+```
+
+## Attribute Permissions
+
+Control which fields users can view and modify:
+
+```ruby
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # Attributes allowed in forms (create/update)
+  def permitted_attributes_for_create
+    [:title, :body, :user_id]
+  end
+
+  def permitted_attributes_for_update
+    if owner?
+      [:title, :body, :published]
+    else
+      [] # Non-owners can't edit
+    end
+  end
+
+  # Attributes visible in views
+  def permitted_attributes_for_read
+    if owner? || record.published?
+      [:title, :body, :published, :created_at, :user]
+    else
+      [:title] # Limited view for unpublished posts
+    end
+  end
+end
+```
+
+## Scope Permissions
+
+Control which records appear in listings:
+
+```ruby
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # Called when listing posts
+  def relation_scope(relation)
+    if admin?
+      relation # Admins see everything
+    else
+      relation.where(published: true).or(relation.where(user_id: user.id))
+    end
+  end
+
+  private
+
+  def admin?
+    user.respond_to?(:admin?) && user.admin?
+  end
+end
+```
+
+## Portal-Specific Policies
+
+Different portals can have different policies. Create a portal-specific policy:
+
+```ruby
+# packages/admin_portal/app/policies/admin_portal/blogging/post_policy.rb
+class AdminPortal::Blogging::PostPolicy < ::Blogging::PostPolicy
+  # Admins can do everything
+  def read?
+    true
+  end
+
+  def update?
+    true
+  end
+
+  def destroy?
+    true
+  end
+
+  def relation_scope(relation)
+    relation # No scope restrictions for admins
+  end
+end
+```
+
+Plutonium automatically uses the portal-specific policy when available.
+
+## Learn More
+
+Plutonium policies extend [ActionPolicy](https://actionpolicy.evilmartians.io/). See the ActionPolicy documentation for advanced features like:
+
+- [Aliases](https://actionpolicy.evilmartians.io/#/aliases) - Group actions under common rules
+- [Pre-checks](https://actionpolicy.evilmartians.io/#/pre_checks) - Skip checks for certain users (e.g., admins)
+- [Caching](https://actionpolicy.evilmartians.io/#/caching) - Cache authorization results
+
+## What's Next
+
+We have CRUD working with proper authorization. In the next chapter, we'll add a custom "Publish" action using Interactions.
+
+[Continue to Chapter 5: Adding Custom Actions →](./05-custom-actions)