plutonium 0.33.1 → 0.34.0

data/docs/modules/package.md

@@ -1,151 +0,0 @@
----
-title: Package Module
----
-
-# Package Module
-
-The Package module provides the foundation for modular application organization in Plutonium. It enables Rails engines to work within the Plutonium ecosystem by providing specialized engine configuration and view path management.
-
-::: tip
-The core of the Package module is `Plutonium::Package::Engine`, which should be included in your package's `engine.rb` file.
-:::
-
-## Overview
-
-- **Engine Foundation**: Provides base functionality for all Plutonium packages (which are Rails Engines).
-- **View Path Control**: Manages view lookups for proper isolation between packages.
-- **Migration Management**: Automatically includes package migrations in the application's migration path.
-
-## Usage
-
-The primary way to use the Package module is by including `Plutonium::Package::Engine` in your package's engine file. This is handled automatically by the generators.
-
-::: code-group
-```bash [Generate a Feature Package]
-rails generate pu:pkg:package blogging
-```
-```ruby [packages/blogging/lib/engine.rb]
-module Blogging
-  class Engine < Rails::Engine
-    # This inclusion provides the core package functionality.
-    include Plutonium::Package::Engine
-  end
-end
-```
-:::
-
-::: code-group
-```bash [Generate a Portal Package]
-rails generate pu:pkg:portal admin
-```
-```ruby [packages/admin_portal/lib/engine.rb]
-module AdminPortal
-  class Engine < Rails::Engine
-    # Portal::Engine includes Package::Engine, so you get both.
-    include Plutonium::Portal::Engine
-  end
-end
-```
-:::
-
-## Key Features
-
-### View Path Management
-
-The Package module intentionally prevents Rails from automatically adding a package's view paths to the global lookup. Instead, view resolution is handled at the controller level by Plutonium's `Bootable` concern. This provides finer-grained control and ensures that packages remain isolated.
-
-### Migration Integration
-
-Package migrations are automatically detected and added to the application's main `db/migrate` path. This allows you to run `rails db:migrate` from your application root, and it will correctly process migrations from all your packages.
-
-::: details Package Engine Implementation
-The `Plutonium::Package::Engine` concern handles this automatically.
-```ruby
-# lib/plutonium/package/engine.rb
-module Plutonium
-  module Package
-    module Engine
-      extend ActiveSupport::Concern
-
-      included do
-        # This block hijacks the default Rails view path initializer
-        # and replaces it with an empty one, giving Plutonium control.
-        config.before_configuration do
-          # ... logic to find and disable the default `add_view_paths` initializer
-        end
-
-        # This initializer appends the package's migrations to the host app.
-        initializer :append_migrations do |app|
-          unless app.root.to_s.match root.to_s
-            config.paths["db/migrate"].expanded.each do |expanded_path|
-              app.config.paths["db/migrate"] << expanded_path
-            end
-          end
-        end
-      end
-    end
-  end
-end
-```
-:::
-
-## Package Loading
-
-Packages are loaded automatically via `config/packages.rb`, which is created by the `pu:core:install` generator. This file simply finds and loads all `engine.rb` files within your `packages/` directory.
-
-```ruby
-# config/packages.rb
-# This file is required in `config/application.rb`
-
-Dir.glob(File.expand_path("../packages/**/lib/engine.rb", __dir__)) do |package|
-  load package
-end
-```
-
-::: tip
-You can package and ship your packages as gems.
-:::
-
-## Generator Integration
-
-### Package Generator
-
-```bash
-# Create a feature package
-rails generate pu:pkg:package blogging
-```
-
-Generates the basic structure with `Plutonium::Package::Engine` included.
-
-### Portal Generator
-
-```bash
-# Create a portal package
-rails generate pu:pkg:portal admin
-```
-
-Generates a portal structure with `Plutonium::Portal::Engine` (which includes Package::Engine).
-
-## Package Types
-
-The package system supports two main types:
-
-1. **Feature Packages**: Business logic packages that include `Plutonium::Package::Engine`
-2. **Portal Packages**: User interface packages that include `Plutonium::Portal::Engine`
-
-Both types benefit from the foundational features provided by the Package module.
-
-## Best Practices
-
-1. **Use Generators**: Always use `pu:pkg:package` or `pu:pkg:portal` generators
-2. **Namespace Consistency**: Keep package names consistent with their directory structure
-3. **Migration Organization**: Place package-specific migrations in the package's `db/migrate` directory
-4. **Engine Simplicity**: Keep engine.rb files minimal - they're just configuration points
-
-## Integration with Other Modules
-
-The Package module works closely with:
-- **Portal Module**: Provides the foundation for portal functionality
-- **Generator Module**: Scaffolds package structure
-- **Core Module**: Integrates with controller bootable system
-- **Routing Module**: Supports resource registration within packages

data/docs/modules/policy.md

@@ -1,176 +0,0 @@
----
-title: Policy Module
----
-
-# Policy Module
-
-The Policy module provides comprehensive authorization and access control for Plutonium applications. Built on top of [ActionPolicy](https://actionpolicy.evilmartians.io/), it offers fine-grained permissions, resource scoping, and entity-based authorization with a secure-by-default approach.
-
-::: tip
-The base policy class is `Plutonium::Resource::Policy`. Resource policies are typically located in `app/policies/`.
-:::
-
-## Overview
-
-- **Resource-Level Authorization**: Control access to CRUD operations and custom actions.
-- **Attribute-Level Permissions**: Fine-grained control over which fields a user can see or edit.
-- **Association Control**: Manage access to related resources.
-- **Entity Scoping**: Built-in support for multi-tenant authorization.
-- **Secure Defaults**: Policies default to denying access, requiring explicit permission.
-
-## Basic Policy Structure
-
-Resource policies inherit from `Plutonium::Resource::Policy` and define methods to control access.
-
-::: code-group
-```ruby [app/policies/post_policy.rb]
-class PostPolicy < Plutonium::Resource::Policy
-  # Who can see a list of posts?
-  def index?
-    true # Everyone can see the list
-  end
-
-  # Who can see a single post?
-  def show?
-    record.published? || user == record.author || user.admin?
-  end
-
-  # Who can create a post?
-  def create?
-    user.present? # Any signed-in user
-  end
-
-  # Who can update a post?
-  def update?
-    user == record.author || user.admin?
-  end
-
-  # Who can destroy a post?
-  def destroy?
-    user.admin? # Only admins
-  end
-
-  # Who can run the custom 'publish' action?
-  def publish?
-    update? && record.draft? # Can only publish if you can update
-  end
-end
-```
-```ruby [Authorization Context]
-# Policies automatically receive context from the controller.
-class Plutonium::Resource::Policy < ActionPolicy::Base
-  # `user` is the current authenticated user. It is required.
-  authorize :user, allow_nil: false
-
-  # `entity_scope` is the current portal's scoping entity (e.g., Organization).
-  # It is optional.
-  authorize :entity_scope, allow_nil: true
-end
-```
-:::
-
-::: danger Secure by Default
-If a permission method (like `create?` or `publish?`) is not defined in your policy, it will default to `false`. You must explicitly grant permissions.
-:::
-
-## Attribute Permissions
-
-You can control which attributes (fields) are visible or editable based on the action and user.
-
-::: code-group
-```ruby [Read Permissions]
-class PostPolicy < Plutonium::Resource::Policy
-  # Defines which attributes are visible on `show` and `index` pages.
-  def permitted_attributes_for_read
-    # Start with a base set of attributes
-    attrs = [:title, :content, :category, :published_at]
-    # Add admin-only attributes conditionally
-    attrs << :internal_notes if user.admin?
-    attrs
-  end
-end
-```
-```ruby [Create/Update Permissions]
-class PostPolicy < Plutonium::Resource::Policy
-  # Defines which attributes can be submitted in `new` and `edit` forms.
-  def permitted_attributes_for_create
-    [:title, :content, :category]
-  end
-
-  def permitted_attributes_for_update
-    # Inherits from create by default, but can be customized.
-    attrs = permitted_attributes_for_create
-    attrs << :slug if user.admin? # Only admins can edit the slug
-    attrs
-  end
-end
-```
-:::
-
-::: details Full Permission Hierarchy
-Plutonium uses a hierarchical permission system. Defining a core action permission (like `read?` or `create?`) automatically grants permission for related actions unless you override them.
-
-**Action Permissions:**
-- `index?` and `show?` inherit from `read?`
-- `new?` inherits from `create?`
-- `edit?` inherits from `update?`
-- `update?` and `destroy?` inherit from `create?` by default.
-
-**Attribute Permissions:**
-- `_for_show` and `_for_index` inherit from `_for_read`.
-- `_for_new` inherits from `_for_create`.
-- `_for_edit` inherits from `_for_update`.
-:::
-
-## Scoping Collections
-
-Use `relation_scope` to filter which records appear in a collection (e.g., on the `index` page).
-
-::: code-group
-```ruby [Simple Scope]
-class PostPolicy < Plutonium::Resource::Policy
-  relation_scope do |relation|
-    # make sure to call super unless you want to bypass the default behavior
-    # plutonium offers
-    relation = super(relation)
-
-    if user.admin?
-      relation # Admins see all posts
-    else
-      # Other users 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
-```
-:::
-
-## Association Permissions
-
-Control which associated resources can be accessed or rendered.
-
-```ruby
-class PostPolicy < Plutonium::Resource::Policy
-  # This determines which associations can be rendered in the UI,
-  # especially for nested forms or displays.
-  def permitted_associations
-    [:comments, :author, :tags]
-  end
-end
-```