plutonium 0.50.0 → 0.51.0

data/docs/guides/creating-packages.md

@@ -1,381 +1,179 @@
 # Creating Packages
 
-This guide covers creating and organizing Feature Packages and Portal Packages.
+Organize your app into feature and portal packages.
 
-## Package Types
+## Goal
 
-| Type | Purpose | Generator |
-|------|---------|-----------|
-| **Feature Package** | Business logic (models, definitions, policies) | `rails g pu:pkg:package NAME` |
-| **Portal Package** | Web interface (routes, auth, UI) | `rails g pu:pkg:portal NAME` |
+Domain code (models, policies, definitions, interactions) lives in **feature packages**. Web interfaces (controllers, views, routes, auth) live in **portal packages**. Both are Rails engines with Plutonium conventions on top.
 
-## Creating a Feature Package
+## Two types
 
-### Using the Generator
+| Type | Purpose | Generator | Examples |
+|---|---|---|---|
+| **Feature** | Business logic | `pu:pkg:package NAME` | `blogging`, `billing`, `inventory` |
+| **Portal** | Web interface | `pu:pkg:portal NAME` | `admin_portal`, `customer_portal`, `public_portal` |
+
+🚨 Don't mix the two. Feature packages have NO routes, views, or controllers. Portal packages have NO models or interactions.
+
+## Feature package
+
+### 1. Generate
 
 ```bash
 rails g pu:pkg:package blogging
 ```
 
-### Generated Structure
+### 2. Structure
 
 ```
 packages/blogging/
 ├── app/
-│   ├── controllers/blogging/
-│   │   └── resource_controller.rb
-│   ├── definitions/blogging/
-│   │   └── resource_definition.rb
-│   ├── interactions/blogging/
-│   │   └── resource_interaction.rb
-│   ├── models/blogging/
-│   │   └── resource_record.rb
-│   ├── policies/blogging/
-│   │   └── resource_policy.rb
-│   └── views/blogging/
-└── lib/
-    └── engine.rb
+│   ├── models/blogging/             # Blogging::Post
+│   ├── definitions/blogging/        # Blogging::PostDefinition
+│   ├── policies/blogging/           # Blogging::PostPolicy
+│   └── interactions/blogging/       # Blogging::PublishPostInteraction
+├── db/migrate/
+└── lib/engine.rb
 ```
 
-### Engine Configuration
-
-```ruby
-# packages/blogging/lib/engine.rb
-module Blogging
-  class Engine < Rails::Engine
-    include Plutonium::Package::Engine
-  end
-end
-```
-
-### Namespacing
-
-All classes are auto-namespaced:
-- `app/models/blogging/post.rb` → `Blogging::Post`
-- `app/policies/blogging/post_policy.rb` → `Blogging::PostPolicy`
-
-## Creating a Portal Package
-
-### Using the Generator
+### 3. Create resources inside it
 
 ```bash
-rails g pu:pkg:portal admin
+rails g pu:res:scaffold Blogging::Post title:string --dest=blogging
+rails db:migrate
 ```
 
-### Generator Options
-
-| Option | Description |
-|--------|-------------|
-| `--auth=NAME` | Rodauth account to authenticate with |
-| `--public` | Grant public access (no authentication) |
-| `--byo` | Bring your own authentication |
+### 4. Expose it via a portal
 
 ```bash
-# Non-interactive examples
-rails g pu:pkg:portal admin --auth=admin
-rails g pu:pkg:portal api --public
-rails g pu:pkg:portal custom --byo
-```
-
-Without flags, the generator prompts interactively.
-
-### Generated Structure
-
-```
-packages/admin_portal/
-├── app/
-│   ├── controllers/admin_portal/
-│   │   ├── concerns/controller.rb
-│   │   ├── dashboard_controller.rb
-│   │   ├── plutonium_controller.rb
-│   │   └── resource_controller.rb
-│   ├── definitions/admin_portal/
-│   │   └── resource_definition.rb
-│   ├── policies/admin_portal/
-│   │   └── resource_policy.rb
-│   └── views/admin_portal/
-│       └── dashboard/index.html.erb
-├── config/
-│   └── routes.rb
-└── lib/
-    └── engine.rb
-```
-
-### Portal Engine
-
-```ruby
-# packages/admin_portal/lib/engine.rb
-module AdminPortal
-  class Engine < Rails::Engine
-    include Plutonium::Portal::Engine
-
-    config.after_initialize do
-      # Multi-tenancy (optional)
-      scope_to_entity Organization, strategy: :path
-    end
-  end
-end
+rails g pu:res:conn Blogging::Post --dest=admin_portal
 ```
 
-### Portal Authentication
+## Portal package
 
-Authentication is configured in the controller concern based on generator options:
+### 1. Generate
 
-```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
-```
-
-For public access:
-
-```ruby
-include Plutonium::Auth::Public
+```bash
+rails g pu:pkg:portal admin --auth=user
 ```
 
-For custom authentication:
+Options:
 
-```ruby
-included do
-  helper_method :current_user
-end
+- `--auth=NAME` — Rodauth account to authenticate with.
+- `--public` — public access, no auth.
+- `--byo` — bring your own auth.
+- `--scope=CLASS` — entity class for multi-tenancy.
 
-def current_user
-  # Your authentication logic
-  @current_user ||= User.find_by(api_key: request.headers["X-API-Key"])
-end
-```
-
-## Portal Routes
-
-The portal generator creates routes and auto-mounts to the main app:
+### 2. Mount it
 
 ```ruby
-# packages/admin_portal/config/routes.rb
-AdminPortal::Engine.routes.draw do
-  root to: "dashboard#index"
-
-  # Register resources here
-  register_resource ::Post
-  register_resource Blogging::Comment
-end
-
-# Also adds to main app routes:
-# config/routes.rb (auto-generated)
+# config/routes.rb
 Rails.application.routes.draw do
-  constraints Rodauth::Rails.authenticate(:admin) do
+  constraints Rodauth::Rails.authenticate(:user) do
     mount AdminPortal::Engine, at: "/admin"
   end
 end
 ```
 
-### Custom Routes on Resources
-
-Add member or collection routes with a block:
-
-```ruby
-register_resource ::Post do
-  member do
-    get :preview
-    post :publish
-  end
-  collection do
-    get :archived
-  end
-end
-```
-
-## Package Loading
-
-Packages are loaded via `config/packages.rb` (generated during install):
-
-```ruby
-# config/packages.rb
-Dir.glob(File.expand_path("../packages/**/lib/engine.rb", __dir__)) do |package|
-  load package
-end
-```
-
-This is automatically required in `config/application.rb`.
-
-## Adding Resources to Packages
+### 3. Connect resources
 
 ```bash
-# Add to main app
-rails g pu:res:scaffold Post title:string --dest=main_app
-
-# Add to a feature package
-rails g pu:res:scaffold Post title:string --dest=blogging
+rails g pu:res:conn Post Blogging::Post --dest=admin_portal
 ```
 
-Resources are namespaced:
+See [Reference › App › Portals](/reference/app/portals) for the full portal surface.
 
-```ruby
-# packages/blogging/app/models/blogging/post.rb
-module Blogging
-  class Post < Blogging::ResourceRecord
-    # Model code
-  end
-end
-```
-
-## Connecting Resources to Portals
+## Auto-namespacing
 
-Resources must be connected to portals to be accessible:
+Every file under `app/<kind>/blogging/` resolves to `Blogging::*`:
 
-```bash
-# Connect main app resource
-rails g pu:res:conn Post --dest=admin_portal
-
-# Connect namespaced resource
-rails g pu:res:conn Blogging::Post --dest=admin_portal
-```
-
-## Entity Scoping (Multi-tenancy)
-
-Automatically scope all data to a parent entity:
+- `app/models/blogging/post.rb` → `Blogging::Post`
+- `app/policies/blogging/post_policy.rb` → `Blogging::PostPolicy`
 
-### Path Strategy
+Each feature package gets base classes — `Blogging::ApplicationRecord`, `Blogging::ResourceRecord`, `Blogging::ResourcePolicy`, `Blogging::ResourceDefinition`, `Blogging::ResourceInteraction` — that inherit from the main app's.
 
-Entity ID in URL path:
+## Cross-package references
 
-```ruby
-# packages/admin_portal/lib/engine.rb
-config.after_initialize do
-  scope_to_entity Organization, strategy: :path
-end
+```bash
+rails g pu:res:scaffold Comment user:belongs_to blogging/post:belongs_to body:text --dest=comments
 ```
 
-Routes become: `/organizations/:organization_id/posts`
+The `blogging/post` syntax expands to `Blogging::Post`.
 
-### Custom Strategy
+## When to use which
 
-Implement your own lookup method:
+### Feature package
 
-```ruby
-config.after_initialize do
-  scope_to_entity Organization, strategy: :current_organization
-end
+When the code:
 
-# In controller concern
-def current_organization
-  @current_organization ||= Organization.find_by!(subdomain: request.subdomain)
-end
-```
+- Could be reused across multiple portals (admin and customer both edit `Blogging::Post`).
+- Has no inherent UI / auth.
+- You want isolated from other domains (`billing` shouldn't depend on `blogging`).
 
-## Package Best Practices
+### Portal package
 
-### 1. Single Responsibility
-Each feature package should handle one domain:
-- `blogging` - Posts, comments, categories
-- `inventory` - Products, stock, warehouses
-- `billing` - Invoices, payments, subscriptions
+When the code:
 
-### 2. Clear Naming
-- Feature packages: domain nouns (`blogging`, `billing`)
-- Portal packages: role + portal (`admin_portal`, `api_portal`)
+- Has a specific auth flow (admin vs customer vs public).
+- Renders different views of the same underlying resources.
+- Needs different policies / definitions per audience.
 
-### 3. Minimal Cross-Dependencies
-Limit dependencies between feature packages. If two packages are tightly coupled, consider merging them.
+### When NOT to make a package
 
-### 4. Portal Customization
-Put UI customizations in portal packages, not feature packages:
+For an app that doesn't need cross-portal sharing, just put resources in `--dest=main_app`. Packages add organization, not power.
 
-```ruby
-# Good: Portal-specific definition
-# packages/admin_portal/app/definitions/admin_portal/post_definition.rb
-
-# Bad: Feature package with portal-specific code
-# packages/blogging/app/definitions/blogging/admin_post_definition.rb
-```
-
-## Multiple Portals Pattern
-
-Common pattern for different user types:
+## Typical architecture
 
 ```
 packages/
-├── blogging/           # Feature: blog functionality
-├── billing/            # Feature: payment/invoicing
-├── admin_portal/       # Portal: admin interface
-├── dashboard_portal/   # Portal: user dashboard
-└── public_portal/      # Portal: public read-only
+├── blogging/                # Feature: blog functionality
+├── billing/                 # Feature: payments/invoicing
+├── admin_portal/            # Portal: admin interface
+└── customer_portal/         # Portal: customer dashboard
 ```
 
-Each portal can:
-- Have different authentication
-- Show different fields
-- Allow different actions
-- Use different layouts
+The portals expose the features. A single feature can be exposed by multiple portals — usually with different policies and definitions per portal.
 
-## Portal-Specific Overrides
+## Package loading
 
-### Override Definition
+Generated by `pu:core:install`:
 
 ```ruby
-# packages/admin_portal/app/definitions/admin_portal/post_definition.rb
-class AdminPortal::PostDefinition < ::PostDefinition
-  # Add portal-specific scopes
-  scope :my_posts, -> { where(user: current_user) }
+# config/packages.rb
+Dir.glob(File.expand_path("../packages/**/lib/engine.rb", __dir__)) do |package|
+  load package
 end
 ```
 
-### Override Policy
-
-```ruby
-# packages/admin_portal/app/policies/admin_portal/post_policy.rb
-class AdminPortal::PostPolicy < ::PostPolicy
-  include AdminPortal::ResourcePolicy
-
-  def destroy?
-    true  # Admins can delete
-  end
-
-  def permitted_attributes_for_create
-    %i[title content featured internal_notes]  # More fields
-  end
-end
-```
+Loaded from `config/application.rb`. Migrations from all packages are picked up by `rails db:migrate` automatically.
 
-### Override Controller
+## Per-portal overrides
 
 ```ruby
-# packages/admin_portal/app/controllers/admin_portal/posts_controller.rb
-class AdminPortal::PostsController < ::PostsController
-  include AdminPortal::Concerns::Controller
+# Definition — different fields per portal
+class AdminPortal::PostDefinition < ::PostDefinition
+  input :internal_notes, as: :text     # admins see this; customers don't
+  scope :pending_review
+end
 
-  private
+# Policy — different rules per portal
+class AdminPortal::PostPolicy < ::PostPolicy
+  include AdminPortal::ResourcePolicy
 
-  def preferred_action_after_submit
-    "index"
-  end
+  def destroy? = true
+  def permitted_attributes_for_create = %i[title content featured internal_notes]
 end
 ```
 
-## Controller Hierarchy
-
-Portal controllers inherit from the feature package's controller if one exists (and include the portal's `Concerns::Controller`). If no feature package controller exists, they inherit from the portal's `ResourceController`.
+## Common issues
 
-```ruby
-# With feature package controller:
-class AdminPortal::PostsController < ::PostsController
-  include AdminPortal::Concerns::Controller
-end
-
-# Without feature package controller:
-class AdminPortal::PostsController < AdminPortal::ResourceController
-end
-```
+- **Class not loading** — namespace must match the directory: `app/models/blogging/post.rb` MUST be `Blogging::Post`.
+- **Migration not running** — package migrations are auto-included. If they aren't running, check `config/packages.rb` is loaded from `application.rb`.
+- **Cross-package association fails** — use `blogging/post:belongs_to` in `pu:res:scaffold`, OR manually set `class_name: "Blogging::Post"` on the `belongs_to`.
 
 ## Related
 
-- [Adding Resources](./adding-resources)
-- [Authentication](./authentication)
-- [Multi-tenancy](./multi-tenancy)
+- [Reference › App › Packages](/reference/app/packages) — full package surface
+- [Reference › App › Portals](/reference/app/portals) — portal-specific configuration
+- [Adding resources](./adding-resources) — `pu:res:scaffold` and `pu:res:conn`
+- [Authentication](./authentication) — portal auth setup