plutonium 0.50.0 → 0.51.0

data/docs/reference/app/generators.md

@@ -0,0 +1,517 @@
+# Generators
+
+Plutonium's `pu:*` CLI generators. Discoverable via `rails g pu:<tab>`. Always pass `--dest=` to skip prompts.
+
+## Catalog
+
+| Generator | Purpose |
+|---|---|
+| [`pu:core:install`](#pu-core-install) | Initial Plutonium setup (base classes, config, layouts) |
+| [`pu:core:assets`](#pu-core-assets) | Set up custom Tailwind + Stimulus toolchain |
+| [`pu:res:scaffold`](#pu-res-scaffold) | New resource (model, migration, controller, policy, definition) |
+| [`pu:res:conn`](#pu-res-conn) | Connect a resource to a portal |
+| [`pu:pkg:package`](#pu-pkg-package) | New feature package |
+| [`pu:pkg:portal`](#pu-pkg-portal) | New portal package |
+| [`pu:rodauth:install`](#pu-rodauth-install) | Install Rodauth base |
+| [`pu:rodauth:account`](#pu-rodauth-account) | Basic Rodauth account |
+| [`pu:rodauth:admin`](#pu-rodauth-admin) | Hardened admin account (2FA, lockout, audit) |
+| [`pu:saas:setup`](#pu-saas-setup) | **Meta** — user + entity + membership + portal + profile + welcome + invites |
+| [`pu:saas:user`](#individual-saas-generators) | Individual: SaaS user account |
+| [`pu:saas:entity`](#individual-saas-generators) | Individual: entity model |
+| [`pu:saas:membership`](#individual-saas-generators) | Individual: membership join model |
+| [`pu:saas:portal`](#individual-saas-generators) | Individual: entity-scoped portal |
+| [`pu:saas:welcome`](#individual-saas-generators) | Individual: onboarding / select-entity flow |
+| [`pu:saas:api_client`](#pu-saas-api-client) | API client for M2M auth |
+| [`pu:profile:install`](#pu-profile-install) | Profile resource + security section |
+| [`pu:profile:setup`](#pu-profile-setup) | Meta — `pu:profile:install` + `pu:profile:conn` |
+| [`pu:profile:conn`](#pu-profile-conn) | Connect profile to a portal as a singular resource |
+| [`pu:invites:install`](#pu-invites-install) | User invitations package |
+| [`pu:invites:invitable`](#pu-invites-invitable) | Mark a model as invitable |
+| [`pu:eject:layout`](#pu-eject-layout) | Eject base layout for customization |
+| [`pu:eject:shell`](#pu-eject-shell) | Eject topbar/sidebar partials |
+| [`pu:test:install`](#pu-test-install) | Install `Plutonium::Testing` scaffolding |
+| [`pu:test:scaffold`](#pu-test-scaffold) | Scaffold integration tests per (resource × portal) |
+| [`pu:core:update`](#pu-core-update) | Update plutonium gem + npm package |
+| [`pu:skills:sync`](#pu-skills-sync) | Sync Plutonium Claude skills into the project |
+
+::: tip Unattended mode
+All generators block on prompts by default. Pass `--dest=`, `--auth=`, `--force`, `--skip-bundle`, `--quiet` etc. to run in scripts/CI. See [App › Unattended execution](./index#unattended-execution).
+:::
+
+---
+
+## Resource generators
+
+### `pu:res:scaffold`
+
+Generate a complete resource: model, migration, controller, policy, definition.
+
+```bash
+rails g pu:res:scaffold Post user:belongs_to title:string 'content:text?' --dest=main_app
+```
+
+| Option | Description |
+|---|---|
+| `--dest=NAME` | Destination package (`main_app` or `<package>`) — required for unattended runs |
+| `--no-model` | Skip model file (for existing models) |
+| `--no-migration` | Skip migration (use with `--no-model` for existing schema) |
+
+Field type syntax — full reference in [Resource › Model](/reference/resource/model). Quick recap:
+
+```bash
+'name:string'              # required string
+'name:string?'             # nullable
+'company:belongs_to'       # association
+'parent:belongs_to?'       # nullable association
+'email:string:uniq'        # with unique index
+'amount:decimal{10,2}'     # decimal with precision
+'status:string{default:draft}'   # with default value
+'metadata:jsonb{default:{}}'     # JSON default
+```
+
+Quote any field containing `?` or `{}` to prevent shell expansion.
+
+### `pu:res:conn`
+
+Connect a resource to a portal. Generates portal-specific controller, policy, definition + route registration.
+
+```bash
+rails g pu:res:conn Post Comment Tag --dest=admin_portal
+rails g pu:res:conn Blogging::Post --dest=admin_portal      # namespaced
+rails g pu:res:conn Profile --dest=customer_portal --singular  # singleton
+```
+
+| Option | Description |
+|---|---|
+| `--dest=PORTAL` | Target portal (required) |
+| `--singular` | Register as singular resource (`/profile`, no `:id`, no index) |
+
+::: tip Run after migrations
+The generator reads model columns to seed the policy's `permitted_attributes_for_*`.
+:::
+
+See [Portals › Connecting resources](./portals#connecting-resources-pu-res-conn) for full details.
+
+---
+
+## Package generators
+
+### `pu:pkg:package`
+
+Feature package — models, policies, definitions, interactions.
+
+```bash
+rails g pu:pkg:package blogging
+```
+
+See [Packages › Feature packages](./packages#feature-packages).
+
+### `pu:pkg:portal`
+
+Portal package — controllers, views, routes, auth.
+
+```bash
+rails g pu:pkg:portal admin --auth=user
+rails g pu:pkg:portal admin --auth=admin --scope=Organization
+```
+
+| Option | Description |
+|---|---|
+| `--auth=NAME` | Rodauth account to authenticate with |
+| `--public` | Public access (no auth) |
+| `--byo` | Bring your own auth |
+| `--scope=CLASS` | Entity class for multi-tenancy |
+
+See [Portals › Creating a portal](./portals#creating-a-portal).
+
+---
+
+## Authentication generators
+
+### `pu:rodauth:install`
+
+Install the Rodauth base — Roda app, base plugin, controller, layout, PostgreSQL extension migration.
+
+```bash
+rails g pu:rodauth:install
+```
+
+### `pu:rodauth:account`
+
+Basic Rodauth account with configurable features.
+
+```bash
+rails g pu:rodauth:account user                  # interactive
+rails g pu:rodauth:account user --defaults       # standard features
+rails g pu:rodauth:account user --kitchen_sink   # ALL features
+rails g pu:rodauth:account api_user --api_only --jwt --jwt_refresh
+```
+
+For full option tables (features, defaults, individual feature flags) see [Auth › Accounts](/reference/auth/accounts).
+
+### `pu:rodauth:admin`
+
+Hardened admin account — pre-configured with multi-phase login, required TOTP, recovery codes, lockout, active sessions, audit logging, role-based access, invite interaction, and **no public signup**.
+
+```bash
+rails g pu:rodauth:admin admin
+rails g pu:rodauth:admin admin --roles=super_admin,admin,viewer
+rails g pu:rodauth:admin admin --extra-attributes=name:string,department:string
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--roles` | `super_admin,admin` | Comma-separated roles (positional enum, index 0 most privileged) |
+| `--extra_attributes` | | Additional model attributes |
+
+Creates a rake task for account creation:
+
+```bash
+rails rodauth_admin:create[admin@example.com,password123]
+```
+
+---
+
+## SaaS generators
+
+### `pu:saas:setup`
+
+**Meta-generator.** Creates the user + entity + membership trio AND runs:
+
+- `pu:saas:portal` → entity-scoped `{Entity}Portal`
+- `pu:profile:setup` → profile model + association
+- `pu:saas:welcome` → onboarding / select-entity flow
+- `pu:invites:install` → invitations package
+
+```bash
+rails g pu:saas:setup --user Customer --entity Organization
+rails g pu:saas:setup --user Customer --entity Organization --roles=member,admin
+rails g pu:saas:setup --user Customer --entity Organization --no-allow-signup
+rails g pu:saas:setup --user Customer --entity Organization \
+  --user-attributes=name:string --entity-attributes=slug:string
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--user=NAME` | (required) | User account model name |
+| `--entity=NAME` | (required) | Entity model name |
+| `--allow-signup` | `true` | Allow public registration |
+| `--roles` | `admin,member` | Additional roles — **`owner` always prepended as index 0** |
+| `--skip-entity` | | Skip entity model generation |
+| `--skip-membership` | | Skip membership model generation |
+| `--user-attributes` | | Additional user model attributes |
+| `--entity-attributes` | | Additional entity model attributes |
+| `--membership-attributes` | | Additional membership model attributes |
+| `--api_client=NAME` | | Also generate an API client model |
+| `--api_client_roles` | `read_only,write,admin` | API client roles |
+
+::: warning Don't re-run pieces manually
+`pu:saas:setup` chains four other generators. Don't re-run portal / profile / welcome / invites separately after this. Pass `--force` to re-run the whole thing.
+:::
+
+### Individual SaaS generators
+
+For when you don't want the full `pu:saas:setup` meta-generator:
+
+```bash
+rails g pu:saas:user Customer
+rails g pu:saas:entity Organization --extra-attributes=slug:string
+rails g pu:saas:membership --user Customer --entity Organization --roles=member,admin
+rails g pu:saas:portal customer --entity Organization
+rails g pu:saas:welcome --user Customer --entity Organization
+```
+
+### `pu:saas:api_client`
+
+API client account for machine-to-machine authentication. HTTP Basic Auth with auto-generated password.
+
+```bash
+rails g pu:saas:api_client ApiClient
+rails g pu:saas:api_client ApiClient --entity=Organization
+rails g pu:saas:api_client ApiClient --entity=Organization --roles=read_only,write,admin
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--entity=NAME` | | Entity to scope API clients to |
+| `--roles` | `read_only,write,admin` | Available roles |
+| `--extra_attributes` | | Additional model attributes |
+| `--dest` | `main_app` | Destination package |
+
+CLI creation:
+
+```bash
+rake api_clients:create LOGIN=my-service
+rake api_clients:create LOGIN=my-service ORGANIZATION=acme ROLE=write
+```
+
+::: warning Credentials shown once
+The auto-generated password is displayed once at creation and cannot be retrieved later (`SecureRandom.base64(32)`).
+:::
+
+---
+
+## Profile generators
+
+See [Auth › Profile](/reference/auth/profile) for the full profile feature.
+
+### `pu:profile:install`
+
+Generate the profile resource (model, migration, controller, policy, definition) and modify the user model to add `has_one :profile`.
+
+```bash
+rails g pu:profile:install bio:text avatar:attachment 'timezone:string?' --dest=customer
+rails g pu:profile:install AccountSettings bio:text --dest=main_app   # custom resource name
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--dest=DEST` | (prompts) | Target package or `main_app` |
+| `--user-model=NAME` | `User` | Rodauth user model |
+
+### `pu:profile:setup`
+
+Meta — runs `pu:profile:install` + `pu:profile:conn` in one shot.
+
+```bash
+rails g pu:profile:setup date_of_birth:date bio:text \
+  --dest=competition \
+  --portal=competition_portal
+```
+
+### `pu:profile:conn`
+
+Connect the profile resource to a portal as a **singular** resource (registers `/profile` and the `profile_url` helper).
+
+```bash
+rails g pu:profile:conn --dest=customer_portal
+```
+
+---
+
+## Invite generators
+
+See [Tenancy › Invites](/reference/tenancy/invites) for the full invitation system.
+
+### `pu:invites:install`
+
+```bash
+rails g pu:invites:install
+rails g pu:invites:install --entity-model=Organization --user-model=Customer --invite-model=OrganizationInvite
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--entity-model=NAME` | `Entity` | Entity model name |
+| `--user-model=NAME` | `User` | User model name |
+| `--invite-model=NAME` | `<EntityModel><UserModel>Invite` | Invite class name |
+| `--membership-model=NAME` | `EntityUser` | Membership join model |
+| `--roles` | `member,admin` | Comma-separated |
+| `--rodauth=NAME` | `user` | Rodauth configuration for signup |
+| `--enforce-domain` | `false` | Require email domain to match entity |
+
+Multiple invite flows are supported — run `pu:invites:install` once per flow.
+
+### `pu:invites:invitable`
+
+Mark an app model as invitable (gets notified when an invite is accepted via `on_invite_accepted`).
+
+```bash
+rails g pu:invites:invitable Tenant
+rails g pu:invites:invitable TeamMember --role=member
+rails g pu:invites:invitable Tenant --dest=my_package
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--role=ROLE` | `member` | Role to assign to invited users |
+| `--user-model=NAME` | `User` | User model |
+| `--membership-model=NAME` | `EntityUser` | Membership join model |
+| `--dest=PACKAGE` | `main_app` | Destination package |
+| `--[no-]email-templates` | `true` | Generate custom email templates |
+
+---
+
+## Core generators
+
+### `pu:core:install`
+
+Initial Plutonium setup. Creates base classes, config initializer, layouts. Run once per app.
+
+```bash
+rails g pu:core:install
+```
+
+### `pu:core:assets`
+
+Set up the custom Tailwind + Stimulus toolchain. Installs npm packages, creates `tailwind.config.js`, imports Plutonium CSS, registers Stimulus controllers.
+
+```bash
+rails g pu:core:assets
+```
+
+See [UI › Assets](/reference/ui/assets) for what gets configured.
+
+### `pu:core:update`
+
+Update the plutonium gem and npm package together.
+
+```bash
+rails g pu:core:update
+```
+
+---
+
+## Eject generators
+
+### `pu:eject:layout`
+
+Copy the base layout template into your portal for direct editing.
+
+```bash
+rails g pu:eject:layout
+```
+
+### `pu:eject:shell`
+
+Copy the topbar/sidebar partials into your portal for direct editing.
+
+```bash
+rails g pu:eject:shell --dest=admin_portal
+```
+
+See [UI › Layouts](/reference/ui/layouts).
+
+---
+
+## Test generators
+
+See [Testing](/reference/testing/) for the full testing toolkit.
+
+### `pu:test:install`
+
+Install the testing scaffolding (require `plutonium/testing` in `test_helper.rb`; create `test/support/plutonium_testing.rb` for overrides). Run once.
+
+```bash
+rails g pu:test:install
+```
+
+### `pu:test:scaffold`
+
+Scaffold integration tests — one file per (resource × portal) pairing.
+
+```bash
+rails g pu:test:scaffold Blogging::Post --portals=admin,org
+rails g pu:test:scaffold Blogging::Post --portals=admin --concerns=crud,policy,definition
+rails g pu:test:scaffold Blogging::Post --portals=org --parent=organization --dest=blogging
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--portals=admin,org` | (required) | Emit one file per portal |
+| `--concerns=...` | `crud,policy,definition` | Concerns to include (full list: `crud,policy,definition,nested,model,interaction,portal_access`) |
+| `--parent=organization` | | Wires the `NestedResource` parent |
+| `--dest=...` | `main_app` | Output destination |
+
+---
+
+## Skill generators
+
+### `pu:skills:sync`
+
+Sync Plutonium's Claude Code skills into the project (`.claude/skills/`). Run when upgrading the gem.
+
+```bash
+rails g pu:skills:sync
+```
+
+---
+
+## Common workflows
+
+### Full app setup
+
+```bash
+# 1. Plutonium template (greenfield) — does all initial setup
+rails new myapp -a propshaft -j esbuild -c tailwind \
+  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+
+# Or for existing app:
+rails generate pu:core:install
+rails generate pu:rodauth:install
+
+# 2. Account types
+rails generate pu:rodauth:admin admin
+# (or pu:saas:setup for multi-tenant)
+
+# 3. Resources
+rails generate pu:res:scaffold Post title:string body:text --dest=main_app
+rails generate pu:res:scaffold Comment body:text post:belongs_to --dest=main_app
+
+# 4. Portal
+rails generate pu:pkg:portal admin --auth=admin
+
+# 5. Connect resources
+rails generate pu:res:conn Post Comment --dest=admin_portal
+
+# 6. Migrate
+rails db:migrate
+
+# 7. Create the first admin
+rails rodauth_admin:create[admin@example.com,password123]
+```
+
+### Adding a new resource
+
+```bash
+rails g pu:res:scaffold Product name:string price_cents:integer --dest=main_app
+rails db:migrate
+rails g pu:res:conn Product --dest=admin_portal
+```
+
+### Adding a new portal
+
+```bash
+rails g pu:pkg:portal customer --auth=user --scope=Organization
+rails g pu:res:conn Order --dest=customer_portal
+rails db:migrate
+```
+
+## Undoing generators
+
+```bash
+rails destroy pu:res:scaffold Post
+rails destroy pu:pkg:portal admin
+```
+
+## Troubleshooting
+
+### Generator not found
+
+Ensure Plutonium is installed and bundle is up to date:
+
+```ruby
+# Gemfile
+gem "plutonium"
+```
+
+```bash
+bundle install
+```
+
+### Package not found
+
+Generators run from Rails root. Package names are case-sensitive.
+
+### Migration already exists
+
+If a migration with the same timestamp exists, wait a second and retry — Rails generates timestamps to one-second resolution.
+
+## Related
+
+- [Packages](./packages) — feature vs portal package structure
+- [Portals](./portals) — portal configuration and resource connection
+- [Resource › Model](/reference/resource/model) — field-type syntax for `pu:res:scaffold`
+- [Auth](/reference/auth/) — account type configuration
+- [Tenancy](/reference/tenancy/) — multi-tenancy and invitations
+- [Testing](/reference/testing/) — test scaffolding

data/docs/reference/app/index.md

@@ -0,0 +1,158 @@
+# App Reference
+
+How a Plutonium app is assembled: installation, the package system (feature vs portal), portal engines, route registration, and connecting resources to portals.
+
+## Sub-pages
+
+- [Packages](./packages) — feature vs portal packages, structure, namespacing, package loading
+- [Portals](./portals) — portal engines, mounting, controller concerns, `register_resource` (including singular and custom routes), connecting resources via `pu:res:conn`
+- [Generators](./generators) — full `pu:*` generator catalog
+
+## Installation
+
+### New Rails app (recommended)
+
+```bash
+rails new myapp -a propshaft -j esbuild -c tailwind \
+  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
+```
+
+Configures Rails + Propshaft + esbuild + TailwindCSS + Plutonium in one shot.
+
+### Existing Rails app
+
+::: danger Existing app → `base.rb`, not `plutonium.rb`
+The `plutonium.rb` template re-runs the full app bootstrap (dotenv, annotate, solid_*, asset config) and creates generic "initial commit" commits that clobber history. For any pre-existing app, always use `base.rb`.
+:::
+
+```bash
+# Template
+bin/rails app:template \
+  LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
+
+# Or manual — add `gem "plutonium"` to Gemfile, then:
+bundle install
+rails generate pu:core:install
+```
+
+## Full setup workflow
+
+```bash
+# 1. Core install — base controllers, policies, definitions, layouts
+rails generate pu:core:install
+
+# 2. Auth (if needed)
+rails generate pu:rodauth:install
+rails generate pu:rodauth:account user
+
+# 3. Portal
+rails generate pu:pkg:portal admin --auth=user
+
+# 4. First resource
+rails generate pu:res:scaffold Post user:belongs_to title:string 'content:text?' --dest=main_app
+rails db:migrate
+
+# 5. Connect resource to portal
+rails generate pu:res:conn Post --dest=admin_portal
+
+# 6. Mount portal in config/routes.rb
+#    mount AdminPortal::Engine, at: "/admin"
+
+# 7. Start
+bin/dev   # uses Procfile to run Rails + CSS watcher
+```
+
+Visit `http://localhost:3000/admin`.
+
+## What `pu:core:install` creates
+
+```
+app/
+├── controllers/
+│   ├── plutonium_controller.rb     # non-resource base
+│   └── resource_controller.rb      # CRUD base — see Behavior › Controllers
+├── definitions/resource_definition.rb
+├── interactions/resource_interaction.rb
+├── models/resource_record.rb       # abstract model — includes Plutonium::Resource::Record
+├── policies/resource_policy.rb
+└── views/layouts/resource.html.erb
+
+config/
+├── initializers/plutonium.rb
+└── packages.rb                     # auto-loads packages/**/lib/engine.rb
+
+packages/.keep
+```
+
+The base classes (`ResourceController`, `ResourcePolicy`, `ResourceDefinition`, `ResourceRecord`, `ResourceInteraction`) are where you put app-wide defaults; resource-specific subclasses come from `pu:res:scaffold`.
+
+## Configuration
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure do |config|
+  config.load_defaults 1.0
+
+  # Hot reloading (defaults to true in development)
+  # config.enable_hotreload = true
+
+  # Cache discovery (defaults to true in production, false in development)
+  # config.cache_discovery = false
+
+  # Page chrome. Default :modern (topbar + icon rail).
+  # :classic preserves the legacy header + sidebar (only when upgrading).
+  # config.shell = :classic
+
+  # Custom assets — see UI › Assets
+  # config.assets.stylesheet = "custom_stylesheet"
+  # config.assets.script     = "custom_script"
+  # config.assets.logo       = "custom_logo.png"
+  # config.assets.favicon    = "custom_favicon.ico"
+end
+```
+
+## Converting an existing model to a resource
+
+```ruby
+# 1. Include the module on your model
+class Post < ApplicationRecord
+  include Plutonium::Resource::Record
+end
+```
+
+```bash
+# 2. Generate supporting files (skips model + migration)
+rails g pu:res:scaffold Post --no-migration --dest=main_app
+
+# 3. Connect to portal
+rails g pu:res:conn Post --dest=admin_portal
+```
+
+## Verifying installation
+
+```bash
+rails runner "puts Plutonium::VERSION"
+```
+
+## Unattended execution
+
+Plutonium generators are interactive by default. For scripts, agents, or CI, pass:
+
+| Flag | Generators | Purpose |
+|---|---|---|
+| `--dest=main_app` / `--dest=<package>` | `pu:res:scaffold`, `pu:res:conn`, package-targeted generators | Skip "select destination" prompt |
+| `--force` | any | Overwrite conflicting files (required when re-running `pu:saas:setup` or meta-generators) |
+| `--auth=<account>` / `--public` / `--byo` | `pu:pkg:portal` | Skip auth-type prompt |
+| `--skip-bundle` | gem-installing generators | Avoid mid-run `bundle install` |
+| `--quiet` | most | Reduce output noise |
+
+Meta-generators (`pu:saas:setup`) propagate these flags to the generators they chain. Always pass `--force` when re-running a meta-generator on an app that already has some of its outputs.
+
+## Related
+
+- [Packages](./packages) — feature vs portal package structure
+- [Portals](./portals) — portal engines, routing, resource connection
+- [Generators](./generators) — full generator reference
+- [Auth](/reference/auth/) — Rodauth setup and account types
+- [UI › Assets](/reference/ui/assets) — Tailwind, Stimulus, design tokens
+- [Tutorial](/getting-started/tutorial/) — step-by-step walkthrough