plutonium 0.55.0 → 0.56.1

data/config/initializers/rabl.rb

@@ -2,9 +2,25 @@ require "rabl"
 
 # https://github.com/nesquena/rabl#configuration
 
+# RABL encodes its result hash with stdlib JSON by default, which serializes
+# Time/Date/BigDecimal via #to_s — e.g. a datetime becomes
+# "2026-06-04 13:46:18 UTC" instead of the ISO 8601 "2026-06-04T13:46:18.000Z"
+# that JSON clients expect. Routing values through ActiveSupport's #as_json
+# first yields JSON-optimized values (ISO 8601 datetimes, "YYYY-MM-DD" dates,
+# numeric-safe decimals, true/false booleans), then stdlib JSON.generate
+# encodes the now-primitive hash without escaping HTML entities in strings.
+module Plutonium
+  module RablJsonEngine
+    def self.dump(object)
+      JSON.generate(object.as_json)
+    end
+  end
+end
+
 Rabl.configure do |config|
   config.cache_sources = !Rails.env.development? # Defaults to false
   config.raise_on_missing_attribute = !Rails.env.production? # Defaults to false
+  config.json_engine = Plutonium::RablJsonEngine
 
   # config.cache_all_output = false
   # config.cache_engine = Rabl::CacheEngine.new # Defaults to Rails cache

data/docs/.vitepress/config.ts

@@ -119,6 +119,7 @@ export default defineConfig(withMermaid({
             { text: "Packages", link: "/reference/app/packages" },
             { text: "Portals", link: "/reference/app/portals" },
             { text: "Generators", link: "/reference/app/generators" },
+            { text: "Lite (SQLite) Generators", link: "/reference/generators/lite" },
           ]
         },
         {

data/docs/getting-started/installation.md

@@ -15,7 +15,7 @@ After the template completes:
 
 ```bash
 cd myapp
-rails db:migrate
+rails db:prepare
 bin/dev
 ```
 
@@ -51,7 +51,7 @@ rails generate pu:core:install
 ```bash
 rails generate pu:rodauth:install
 rails generate pu:rodauth:account user
-rails db:migrate
+rails db:prepare
 ```
 
 For account options and customization, see [Reference › Auth](/reference/auth/) and [Guides › Authentication](/guides/authentication).

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

@@ -113,7 +113,7 @@ end
 ## Running the Migration
 
 ```bash
-rails db:migrate
+rails db:prepare
 ```
 
 ## Creating a Portal

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

@@ -28,7 +28,7 @@ Plutonium supports multiple account types. For admins, use the dedicated `pu:rod
 
 ```bash
 rails generate pu:rodauth:admin admin
-rails db:migrate
+rails db:prepare
 ```
 
 For self-service user accounts, the corresponding command is `rails generate pu:rodauth:account user`.
@@ -151,7 +151,7 @@ Our blog needs users (authors) who can create posts. Let's create a User account
 
 ```bash
 rails generate pu:rodauth:account user
-rails db:migrate
+rails db:prepare
 ```
 
 This creates a `User` model similar to `Admin`, but with public registration enabled.
@@ -177,7 +177,7 @@ end
 Run the migration:
 
 ```bash
-rails db:migrate
+rails db:prepare
 ```
 
 Update the Post model to include the association:

data/docs/guides/adding-resources.md

@@ -29,7 +29,7 @@ Plutonium generates a basic migration. Before running it, edit `db/migrate/<time
 ### 3. Run the migration
 
 ```bash
-rails db:migrate
+rails db:prepare
 ```
 
 ### 4. Connect to a portal

data/docs/guides/authentication.md

@@ -16,7 +16,7 @@ rails generate pu:rodauth:install
 rails generate pu:rodauth:account user
 
 # 3. Run migrations
-rails db:migrate
+rails db:prepare
 
 # 4. Wire auth into a portal
 #    (when you run `pu:pkg:portal admin --auth=user`, this happens automatically)

data/docs/guides/creating-packages.md

@@ -40,7 +40,7 @@ packages/blogging/
 
 ```bash
 rails g pu:res:scaffold Blogging::Post title:string --dest=blogging
-rails db:migrate
+rails db:prepare
 ```
 
 ### 4. Expose it via a portal

data/docs/guides/multi-tenancy.md

@@ -42,7 +42,7 @@ rails g pu:res:scaffold Organization name:string:uniq slug:string:uniq --dest=ma
 
 ```bash
 rails g pu:res:scaffold Post organization:belongs_to title:string content:text --dest=main_app
-rails db:migrate
+rails db:prepare
 ```
 
 ### 3. Scope the portal to the entity

data/docs/guides/nested-resources.md

@@ -20,7 +20,7 @@ All of this happens with no manual route wiring — Plutonium generates it from
 ```bash
 rails g pu:res:scaffold Company name:string --dest=main_app
 rails g pu:res:scaffold Property company:belongs_to name:string --dest=main_app
-rails db:migrate
+rails db:prepare
 ```
 
 ### 2. Connect both to the portal

data/docs/guides/user-invites.md

@@ -49,7 +49,7 @@ rails g pu:invites:install \
 ### 2. Migrate
 
 ```bash
-rails db:migrate
+rails db:prepare
 ```
 
 ### 3. Connect to your portal

data/docs/guides/user-profile.md

@@ -55,7 +55,7 @@ By default the model is `{UserModel}Profile` (`UserProfile`, `StaffUserProfile`,
 ### 2. Migrate
 
 ```bash
-rails db:migrate
+rails db:prepare
 ```
 
 ### 3. Connect to a portal

data/docs/public/templates/lite.rb

@@ -4,6 +4,10 @@ after_bundle do
   git add: "."
   git commit: %( -m 'setup sqlite') if `git status --porcelain`.present?
 
+  generate "pu:lite:tune"
+  git add: "."
+  git commit: %( -m 'tune sqlite pragmas') if `git status --porcelain`.present?
+
   unless ENV["SKIP_SOLID_QUEUE"]
     generate "pu:lite:solid_queue"
     git add: "."
@@ -39,4 +43,10 @@ after_bundle do
     git add: "."
     git commit: %( -m 'add rails_pulse') if `git status --porcelain`.present?
   end
+
+  unless ENV["SKIP_SQLITE_MAINTENANCE"]
+    generate "pu:lite:maintenance"
+    git add: "."
+    git commit: %( -m 'add sqlite maintenance job') if `git status --porcelain`.present?
+  end
 end

data/docs/reference/app/generators.md

@@ -455,7 +455,7 @@ rails generate pu:pkg:portal admin --auth=admin
 rails generate pu:res:conn Post Comment --dest=admin_portal
 
 # 6. Migrate
-rails db:migrate
+rails db:prepare
 
 # 7. Create the first admin
 rails rodauth_admin:create[admin@example.com,password123]
@@ -465,7 +465,7 @@ rails rodauth_admin:create[admin@example.com,password123]
 
 ```bash
 rails g pu:res:scaffold Product name:string price_cents:integer --dest=main_app
-rails db:migrate
+rails db:prepare
 rails g pu:res:conn Product --dest=admin_portal
 ```
 
@@ -474,7 +474,7 @@ rails g pu:res:conn Product --dest=admin_portal
 ```bash
 rails g pu:pkg:portal customer --auth=user --scope=Organization
 rails g pu:res:conn Order --dest=customer_portal
-rails db:migrate
+rails db:prepare
 ```
 
 ## Undoing generators

data/docs/reference/app/index.md

@@ -50,7 +50,7 @@ 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
+rails db:prepare
 
 # 5. Connect resource to portal
 rails generate pu:res:conn Post --dest=admin_portal

data/docs/reference/app/portals.md

@@ -195,7 +195,7 @@ rails g pu:res:conn Profile --dest=customer_portal --singular
 ```
 
 ::: tip Run after migrations
-The generator reads model columns to seed the policy's `permitted_attributes_for_*`. Run `rails db:migrate` first.
+The generator reads model columns to seed the policy's `permitted_attributes_for_*`. Run `rails db:prepare` first.
 :::
 
 ### What gets generated

data/docs/reference/auth/profile.md

@@ -24,7 +24,7 @@ Meta-generator: runs `pu:profile:install` + `pu:profile:conn` in one shot.
 rails generate pu:profile:install bio:text avatar:attachment 'timezone:string?' \
   --dest=customer
 
-rails db:migrate
+rails db:prepare
 
 rails generate pu:profile:conn --dest=customer_portal
 ```

data/docs/reference/generators/lite.md

@@ -0,0 +1,65 @@
+# Lite (SQLite) Generators
+
+The `pu:lite:*` generators configure a SQLite-first production stack. This page
+covers the two tuning/maintenance generators; the solid_queue / solid_cache /
+solid_cable / solid_errors / litestream / rails_pulse generators are run the
+same way (`rails g pu:lite:<name>`).
+
+## `pu:lite:tune`
+
+Adds tuned performance pragmas to the `default: &default` block of
+`config/database.yml`.
+
+```bash
+rails g pu:lite:tune
+```
+
+It writes a `pragmas:` mapping:
+
+- `cache_size: -64000` — 64 MB page cache (the ~2 MB default is too small).
+- `temp_store: 2` — MEMORY; sorts and temp indexes stay off disk.
+- `mmap_size: 536870912` — 512 MB memory-mapped I/O.
+- `wal_autocheckpoint: 10000` — checkpoint roughly every 40 MB of WAL.
+
+On Rails &lt; 8.1 it also writes the baseline pragmas (`journal_mode: WAL`,
+`synchronous: NORMAL`, `foreign_keys: true`, `journal_size_limit`) that Rails 8.1+
+already sets by default.
+
+**Why no `busy_timeout`?** Rails routes the `timeout:` key to the sqlite3 gem's
+constant-poll busy handler (`busy_handler_timeout`), which has better tail-latency
+than SQLite's internal exponential backoff. Setting a busy-timeout pragma would
+replace the better handler with the worse one, so this generator never emits it.
+
+The generator is idempotent — re-running it detects the existing pragmas and skips.
+It only ever touches the `default:` block, so a `pragmas:` mapping nested under
+another environment is left untouched.
+
+## `pu:lite:maintenance`
+
+Installs `app/jobs/sqlite_maintenance_job.rb` and (when `solid_queue` is present)
+schedules it in `config/recurring.yml`.
+
+```bash
+rails g pu:lite:maintenance
+# custom schedule:
+rails g pu:lite:maintenance --schedule="every day at 4am"
+```
+
+The job runs `PRAGMA optimize` on every configured SQLite database and `VACUUM`
+only on databases without live 24/7 writers (`primary`, `errors`, `rails_pulse`
+by default — edit `VACUUM_DBS` in the generated job to suit your app).
+
+**Why VACUUM only some databases?** SolidQueue, Solid Cache and Solid Cable write
+to their databases constantly. `VACUUM` takes a global *exclusive* lock for its
+whole duration, which stalls and errors those processes (e.g. SolidQueue process
+deregistration failing with "database is locked"). They also barely benefit: in
+WAL mode, freed pages land on the freelist and are reused, so a churning database
+stays at a steady-state size without nightly reclamation. `PRAGMA optimize`, which
+only takes a brief shared lock, still runs everywhere.
+
+Databases listed in the job that don't exist in `config/database.yml` are skipped
+at runtime, so the same job is safe regardless of which `pu:lite:*` generators you
+have run.
+
+If `solid_queue` is not installed, the job file is still created but not scheduled —
+add a `sqlite_maintenance` entry to whatever scheduler you use.

data/docs/reference/resource/actions.md

@@ -61,6 +61,9 @@ action :name,
   collection_record_action: true,
   bulk_action:              true,
 
+  # Conditional visibility — display-only proc, NOT authorization (see below)
+  condition: -> { params[:beta] == "1" },
+
   # Grouping
   category: :primary,                    # :primary, :secondary, :danger
   position: 50,                          # display order (lower = first)
@@ -84,6 +87,58 @@ def customize_actions
 end
 ```
 
+## Conditional visibility — `condition:`
+
+Like the `condition:` proc on [inputs/displays/columns](/reference/resource/definition), an action can be **defined but only rendered when a runtime proc is truthy**. It's purely a toggle on whether the **button is shown** — the action (and its route) stays fully live either way.
+
+The headline use case: **expose an action's endpoint without surfacing it in the UI** — e.g. one you call from the API, a webhook, or another service. Hide the button with an always-falsy condition; the route still works:
+
+```ruby
+# Defined and callable (API / programmatic), but no button anywhere in the UI:
+action :sync_inventory, interaction: SyncInventoryInteraction, condition: -> { false }
+```
+
+It also works as a dynamic toggle driven by the **record** or the **view/request** context:
+
+```ruby
+# object → the row/shown record (record & collection-record actions):
+action :reopen,  interaction: ReopenInteraction,  condition: -> { object.closed? }
+# view/request state — feature flag, preview/beta mode:
+action :preview, interaction: PreviewInteraction, condition: -> { params[:beta] == "1" }
+```
+
+Inside the proc, `object`/`record` is the contextual record, and every other call delegates to the **view context**:
+
+| Available | Notes |
+|---|---|
+| `object` / `record` | The row/shown record for **record** and **collection-record** actions; **`nil`** for resource and bulk actions (no single record). Guard with `object&.…` if a condition is shared across action kinds. |
+| `params`, `request` | Current request. |
+| `current_user`, `current_parent` | The signed-in user and (nested) parent. |
+| `resource_record!` | The shown record on the show page; raises on index/table — prefer `object`. |
+| `allowed_to?`, `policy_for`, other helpers | The usual view helpers. |
+
+`object` is evaluated **per row** in tables and grids, so per-record show/hide works there too.
+
+::: danger `condition:` is NOT authorization — it only hides the button
+A hidden action still has a **live route**: anyone who knows the URL can still trigger it. `condition:` decides whether the *button renders*, never whether the *request is allowed*.
+
+```ruby
+# 🚫 WRONG — this does NOT stop non-admins. The route is live; they can POST to it.
+action :wipe, interaction: WipeInteraction, condition: -> { current_user.admin? }
+
+# ✅ RIGHT — authorization belongs in the policy. The action only runs if this returns true.
+class WidgetPolicy < ResourcePolicy
+  def wipe? = current_user.admin?
+end
+```
+
+**Rule of thumb:** "who may run this" → **policy** (`def action_name?`). "is this UI relevant right now" → `condition:`. Authorization is enforced regardless of `condition:`; the two compose — an action appears only when the policy permits **and** the condition is truthy.
+:::
+
+::: tip Per-record display vs. per-record authorization
+`condition: -> { object.draft? }` is fine for **showing/hiding** a per-record button. But if the rule is about **who may run it** ("only while draft *and* nobody else has it locked"), put it in the policy — `def publish? = record.draft?` is also evaluated per record (per row), and unlike `condition:` it actually gates execution.
+:::
+
 ## Simple actions (navigation)
 
 Link to an existing route. The target route MUST exist.

data/docs/reference/resource/definition.md

@@ -102,7 +102,7 @@ end
 | Text | `:string`, `:text`, `:email`, `:url`, `:tel`, `:password` |
 | Rich text | `:markdown` (EasyMDE editor) |
 | Numeric | `:number`, `:integer`, `:decimal`, `:range` |
-| Boolean | `:boolean` |
+| Boolean | `:toggle` / `:switch` (switch — **default** for boolean columns), `:boolean` (plain checkbox) |
 | Date/Time | `:date`, `:time`, `:datetime` |
 | Selection | `:select`, `:slim_select`, `:radio_buttons`, `:check_boxes` |
 | Files | `:file`, `:uppy`, `:attachment` |
@@ -111,7 +111,23 @@ end
 
 ### Display types (show / index)
 
-`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`, `:color`
+`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:badge`, `:currency`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`, `:color`
+
+#### Auto-inferred display formatting
+
+These render automatically — declare an `as:` only to override or pass options:
+
+| Column | Renders as | Notes |
+|---|---|---|
+| `boolean` | Yes/No pill (`:boolean`) | green "Yes" / neutral "No"; override with `true_label:` / `false_label:` |
+| `enum` | status badge (`:badge`) | known statuses auto-colored; unknown values get a stable decorative color; override per-value with `colors:` |
+| `has_cents` decimal | currency (`:currency`) | delimited, 2 decimals, **no symbol** unless you pass `unit:` (a literal `"£"` or a Symbol read off the record) |
+
+```ruby
+display :status, as: :badge, colors: {archived: :neutral, vip: :accent}
+display :price,  as: :currency, unit: "£"
+display :active, as: :boolean, true_label: "Live", false_label: "Off"
+```
 
 ## Field options
 

data/docs/reference/resource/index.md

@@ -14,7 +14,7 @@ A **resource** is the unit Plutonium gives you full CRUD for — list, show, cre
 
 ```bash
 rails g pu:res:scaffold Post user:belongs_to title:string 'content:text?' --dest=main_app
-rails db:migrate
+rails db:prepare
 rails g pu:res:conn Post --dest=admin_portal
 ```
 

data/docs/reference/tenancy/invites.md

@@ -56,7 +56,7 @@ rails g pu:invites:install \
 After install:
 
 ```bash
-rails db:migrate
+rails db:prepare
 ```
 
 ## What gets created

data/docs/reference/ui/assets.md

@@ -290,8 +290,22 @@ Ready-to-use styled components in `src/css/components.css`. **Prefer these over
 .pu-label / -required
 .pu-hint / .pu-error
 .pu-checkbox
+.pu-toggle                         (switch-styled checkbox)
 ```
 
+### Badges (status pills)
+
+```
+.pu-badge                          (base)
+.pu-badge-neutral / -primary / -secondary / -success / -danger / -warning / -info / -accent
+```
+
+```erb
+<span class="pu-badge pu-badge-success">Active</span>
+```
+
+Rendered automatically by the `:badge` display (enums) and `:boolean` display (Yes/No pills). See [Displays](./displays#built-in-display-components).
+
 ### Cards, panels, tables, toolbars, empty states
 
 ```

data/docs/reference/ui/displays.md

@@ -67,6 +67,30 @@ end
 
 See [Resource › Definition › Custom rendering](/reference/resource/definition#custom-rendering) for the full per-field rendering surface.
 
+## Built-in display components
+
+Some types render with richer components automatically — you only declare an `as:` to override or pass options.
+
+| `as:` | Renders | Auto-inferred for | Options |
+|-------|---------|-------------------|---------|
+| `:boolean` | green "Yes" / neutral "No" pill | `boolean` columns | `true_label:`, `false_label:` |
+| `:badge` | colored status pill | `enum` columns | `colors:` (per-value override) |
+| `:currency` | delimited, 2-decimal money | `has_cents` decimal accessors | `unit:`, `options:` |
+| `:color` | swatch + value | — | — |
+
+```ruby
+class OrderDefinition < ResourceDefinition
+  display :status,  as: :badge, colors: {refunded: :neutral, vip: :accent}
+  display :total,   as: :currency, unit: "£"
+  display :total,   as: :currency, unit: :currency_symbol   # Symbol → read off each record
+  display :shipped, as: :boolean,  true_label: "Sent", false_label: "Pending"
+end
+```
+
+**Badge colors.** Known statuses (`active`, `pending`, `failed`, …) are auto-colored by meaning. Unknown values get a stable decorative color (same value → same color). Override per-value with `colors:`; valid variants: `:neutral`, `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:accent`.
+
+**Currency.** No symbol is shown unless you pass `unit:` — a literal string (`"£"`) or a Symbol read off the record for per-row currencies. `has_cents` decimal accessors infer `:currency` automatically (still symbol-less until you set `unit:`).
+
 ## Theming
 
 Override the theme via a nested `Theme` class:
@@ -90,7 +114,9 @@ end
 
 ### Theme keys
 
-`fields_wrapper`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`.
+`fields_wrapper`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`, `boolean`, `badge`, `currency`, `color`.
+
+(`boolean` and `badge` apply their pill variant in the component, so their theme value stays empty — restyle the pills via the `.pu-badge*` classes instead.)
 
 ## Metadata panel
 

data/docs/reference/ui/forms.md

@@ -122,6 +122,7 @@ render field(:title).wrapped(class: "col-span-full") { |f| f.input_tag }
 | `input_tag` | text (auto-detected type) |
 | `string_tag`, `text_tag`, `number_tag`, `email_tag`, `password_tag`, `url_tag`, `tel_tag`, `hidden_tag` | standard HTML inputs |
 | `checkbox_tag`, `select_tag`, `radio_button_tag` | standard |
+| `toggle_tag` / `switch_tag` | switch-styled boolean (`as: :toggle` / `:switch`) — the **default** for boolean columns; same behavior as a checkbox. Use `checkbox_tag` (`as: :boolean`) for a plain checkbox. |
 
 ### Plutonium-enhanced tags
 
@@ -239,7 +240,7 @@ Don't replace the theme wholesale — Plutonium's defaults handle invalid states
 
 ### Theme keys
 
-`base`, `fields_wrapper`, `actions_wrapper`, `wrapper`, `inner_wrapper`, `label`, `invalid_label`, `valid_label`, `neutral_label`, `input`, `invalid_input`, `valid_input`, `neutral_input`, `hint`, `error`, `button`, `checkbox`, `select`.
+`base`, `fields_wrapper`, `actions_wrapper`, `wrapper`, `inner_wrapper`, `label`, `invalid_label`, `valid_label`, `neutral_label`, `input`, `invalid_input`, `valid_input`, `neutral_input`, `hint`, `error`, `button`, `checkbox`, `toggle`, `select`.
 
 See [Assets › Phlexi component themes](./assets#phlexi-component-themes) for the underlying theme system.
 

data/docs/reference/ui/layouts.md

@@ -26,6 +26,39 @@ rails generate pu:eject:layout
 
 `pu:eject:layout` copies `layouts/resource.html.erb` for layout-level edits.
 
+## Navigation menu
+
+The sidebar/icon-rail navigation is built with `Phlexi::Menu::Builder` in the ejected `_resource_sidebar.html.erb`. Each `item` takes a `label`, plus `url:`, `icon:`, and optional `leading_badge:` / `trailing_badge:`:
+
+```erb
+<%= render Plutonium::UI::Layout::IconRail.new(
+      menu: Phlexi::Menu::Builder.new do |m|
+        m.item "Dashboard", url: root_path, icon: Phlex::TablerIcons::Home
+
+        m.item "Resources", icon: Phlex::TablerIcons::GridDots do |n|
+          registered_resources.each do |resource|
+            n.item resource_label(resource), url: resource_url_for(resource, parent: nil)
+          end
+        end
+      end
+    ) %>
+```
+
+### Per-item link attributes
+
+Any extra options you pass to `item` are spread straight onto the rendered `<a>` — so a menu entry can opt into `target`, `rel`, `data-*`, `aria-*`, etc. Useful for items that open in their own tab or drive a Stimulus/Turbo behavior:
+
+```ruby
+m.item "Inbox",
+  url: inbox_path,
+  icon: Phlex::TablerIcons::Mail,
+  target: "_blank",
+  rel: "noopener",
+  data: {turbo_frame: "_top"}
+```
+
+This works across both shells — the `:modern` icon-rail (leaf items, parent flyout triggers, and flyout children) and the `:classic` sidebar. Framework attributes always win on conflict: a custom `class:` is **merged** with the component's base classes, and on a parent trigger your `data:` / `aria:` merge with the flyout's own wiring (so you can't accidentally break the toggle). The `:active` key is reserved by Phlexi for [custom active-state logic](https://github.com/radioactive-labs/phlexi-menu) and is never emitted as an attribute.
+
 ## Custom layout class
 
 For full Phlex-level control over the layout: