plutonium 0.58.0 → 0.59.0

data/docs/.vitepress/config.ts

@@ -131,6 +131,7 @@ export default defineConfig(withMermaid({
             { text: "Definition", link: "/reference/resource/definition" },
             { text: "Query", link: "/reference/resource/query" },
             { text: "Actions", link: "/reference/resource/actions" },
+            { text: "CSV Export", link: "/reference/resource/export" },
           ]
         },
         {

data/docs/reference/resource/actions.md

@@ -360,6 +360,9 @@ class PostDefinition < ResourceDefinition
 end
 ```
 
+> **CSV export is not an action.** It's a built-in, policy-gated capability with its own
+> button — see [CSV Export](./export.md). Don't declare it with `action :export_csv`.
+
 ## Interaction responses
 
 ```ruby

data/docs/reference/resource/export.md

@@ -0,0 +1,94 @@
+# CSV Export
+
+Every resource ships with a streamed CSV export, **disabled by default**. It is *not* an
+[action](./actions.md) — it streams a file and opens in a new tab — so it is enabled
+through the policy rather than declared with `action :export_csv`. The route
+(`GET /<resources>/export_csv`) is auto-mounted on every resource; a split "Export"
+button appears on the index page once the policy permits it.
+
+## Enabling
+
+Override one policy method:
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def export_csv? = true   # or `index?` to mirror list access
+end
+```
+
+`export_csv?` defaults to `false`, so export is strictly opt-in. While it returns false
+the button is hidden and the route returns `403`.
+
+## The two exports
+
+The control is a split button with two behaviours:
+
+| | Source | Filename |
+|---|---|---|
+| **Export** (primary) | The current view — selected scope + filters + search (the index's `?q`), **all** matching rows (not just the visible page) | `posts_<date>.csv` |
+| **Export all** (dropdown) | The entire authorized scope — ignores scope, filters, search, and default scope | `posts_all_<date>.csv` |
+
+"Export all" always exports everything the user is authorized to read, regardless of the
+current scope/filters.
+
+Both stream via `find_each`, so memory stays flat regardless of row count. `find_each`
+iterates in **primary-key order**, so the file does not preserve the index's current
+sort (filters/search/scope still apply to the primary export).
+
+## Columns
+
+The exported columns come from `permitted_attributes_for_export` on the policy (defaults
+to `permitted_attributes_for_index`), with the **primary key always prepended as the
+first column**.
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def export_csv? = true
+  def permitted_attributes_for_export = [:title, :author, :total, :created_at]
+end
+```
+
+The method is named `_export` (not `_export_csv`) on purpose, so a future export format
+could reuse the same column set.
+
+## Customizing a field's output
+
+The `export` definition DSL parallels `display` and `column`. The block receives the
+record and returns the cell value; `label:` overrides the header (default: the humanized
+attribute name).
+
+```ruby
+class PostDefinition < ResourceDefinition
+  export :author, label: "Author email", &->(post) { post.author.email }
+  export :total,                          &->(post) { post.total.format }
+end
+```
+
+The column *set* still comes from `permitted_attributes_for_export`; `export` only
+customizes how a listed column is rendered.
+
+## Value resolution
+
+For a column **without** an `export` block, the value is read straight off the record
+(`record.public_send(name)`):
+
+- **Scalars** (strings, numbers, booleans, dates) are written as-is.
+- **Associations** render as their display label — the same `display_name_of` the index
+  uses (e.g. `User #5`, or the record's `to_label`/`name`/`title` if defined) — never
+  `#<User:0x…>`. Add an `export` block to export a specific field instead (e.g. the email).
+- A name that is **neither** an `export` block **nor** a real method on the record renders
+  the placeholder `<<invalid column>>` rather than aborting the (already-streaming) download.
+  To export a computed or virtual column, give it an `export` block — a `label:`-only
+  `export` does **not** supply a value, so it too renders the placeholder.
+
+## Notes & limits
+
+- Exports run **synchronously** and hold the request (and a DB connection) while
+  streaming. A background job that emails a download link is intentionally out of scope
+  for now.
+- The export button opens in a new tab (`target="_blank"`), which also keeps Turbo from
+  intercepting the streamed download.
+- **CSV/formula injection** is neutralized: any cell whose value begins with `=`, `+`,
+  `-`, `@`, or a leading tab/CR is prefixed with a single quote so spreadsheet apps import
+  it as literal text instead of executing it as a formula.
+- `csv` is a runtime dependency of Plutonium (it is no longer a Ruby default gem on 3.4+).

data/docs/superpowers/specs/2026-06-12-export-csv-default-action-design.md

@@ -0,0 +1,306 @@
+# Built-in CSV Export — Design
+
+**Date:** 2026-06-12
+**Status:** Implemented
+
+> **Revision (two exports, toolbar split button).** The shipped feature is a **split
+> button** with two behaviours, not a single export:
+> - **Export** (primary) — the current view (selected scope + filters + search via
+>   `?q`). Source: `filtered_resource_collection`. Filename `…_<date>.csv`.
+> - **Export all** (dropdown) — the entire authorized scope, bypassing the query object
+>   (`?all=1`). Source: `current_authorized_scope`. Filename `…_all_<date>.csv`.
+>
+> The controller selects the source via `export_csv_collection` (keyed on `params[:all]`).
+> The split button (`Plutonium::UI::ExportButton`, reusing the `resource-drop-down`
+> Stimulus controller) is rendered in the **index table toolbar, just after the Filter
+> button** — `Plutonium::UI::Table::Components::Toolbar` receives an `export:` config
+> built by `Table::Resource#export_toolbar_config` (policy-gated; carries the current
+> `?q`). It is styled with `pu-btn-outline pu-btn-sm` to match the Filter button, with
+> the two halves joined via inline corner styles. A page-limited "export current page"
+> variant and a scope-named primary label were both considered and dropped.
+
+## Goal
+
+Ship CSV export as a **built-in, auto-mounted, policy-gated capability** on every Plutonium
+resource — disabled by default, enabled by a one-line policy override, surfaced through a
+**custom export button** on the index page (not the action DSL — exports are special: they stream
+and open in a new tab). This generalizes the `AdminPortal::Concerns::ExportCsv` pattern from the
+achieve-api app into the framework, following Plutonium's existing `typeahead` design
+(auto-mounted route + default policy method + controller concern).
+
+The achieve app wired export per-resource by hand (a definition action, a controller concern,
+manual `collection { get :export_csv }` per resource, raw `attribute_names` as columns). Here the
+route auto-mounts, the column set comes from the policy/definition, the per-field output is
+customizable via an `export` DSL, and the export **streams** so it's safe on large tables — the
+only thing a user does to turn it on is enable the policy.
+
+## How users enable it
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  def export_csv? = true            # or `index?`
+end
+```
+
+That's it. The route already exists, the button appears on the index page once permitted, the
+column set defaults to the index columns. Optionally:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # customize a single field's output + header (column set still comes from the policy)
+  export :author, label: "Author email", &->(post) { post.author.email }
+  export :total, &->(post) { post.total.format }
+end
+```
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  def export_csv? = true
+  # override the exported column set (defaults to permitted_attributes_for_index)
+  def permitted_attributes_for_export = [:title, :author, :total, :created_at]
+end
+```
+
+## Behavior
+
+- The export button is a plain `<a target="_blank">` to `GET /<resources>/export_csv`, carrying
+  the **current query string** (`?q[...]`). So it exports **all records matching the current
+  filters/search/scope** — not just the visible page (the index is paginated; export is not).
+- `target="_blank"` opens the download in a new tab **and** naturally bypasses Turbo (Turbo
+  ignores links with a `target`), so the streamed file download isn't intercepted/rendered.
+- The response **streams** (`send_stream`) — rows are written as they're read in batches, so
+  memory stays flat regardless of row count. No row cap.
+
+## Design (5 touch-points)
+
+### 1. Routing — auto-mount (parallels `define_collection_typeahead_actions`)
+
+`lib/plutonium/routing/mapper_extensions.rb`. Add `define_collection_export_actions`, invoked
+inside the `interactive_resource_actions` concern:
+
+```ruby
+def define_collection_export_actions
+  collection do
+    get "export_csv", action: :export_csv, as: :export_csv
+  end
+end
+```
+
+Every resource registered via `register_resource` gets `GET /<resources>/export_csv`. No
+per-resource route edits. Path helper: `export_csv_<resources>_path`.
+
+### 2. Controller concern (parallels `Typeahead`)
+
+`lib/plutonium/resource/controllers/export_csv.rb`, included in `controller.rb` after
+`CrudActions` (so it can reuse the private `filtered_resource_collection`).
+
+```ruby
+require "csv"
+
+module Plutonium::Resource::Controllers::ExportCsv
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :authorize_export_csv!, only: :export_csv
+    skip_verify_current_authorized_scope only: :export_csv
+  end
+
+  # GET /<resources>/export_csv
+  # Streams via a lazy Enumerator response body (NOT send_stream — that
+  # lives in ActionController::Live, which would turn every resource
+  # action into a threaded streaming response). The primary key is always
+  # the first column. Rows are the index's filtered collection.
+  def export_csv
+    response.headers["Content-Type"] = "text/csv; charset=utf-8"
+    response.headers["Content-Disposition"] =
+      ActionDispatch::Http::ContentDisposition.format(disposition: "attachment", filename: export_csv_filename)
+    response.headers["X-Accel-Buffering"] = "no"
+    response.headers["Cache-Control"] = "no-cache"
+    self.response_body = export_csv_lines
+  end
+
+  def export_csv_lines
+    columns = export_columns   # [primary_key] + (exportable_attributes - [primary_key])
+    Enumerator.new do |yielder|
+      yielder << CSV.generate_line(columns.map { |c| export_csv_header(c) })
+      filtered_resource_collection.find_each do |record|
+        yielder << CSV.generate_line(columns.map { |c| export_csv_value(record, c) })
+      end
+    end
+  end
+
+  private
+
+  def authorize_export_csv!
+    authorize_current! resource_class, to: :export_csv?
+  end
+
+  def exportable_attributes
+    @exportable_attributes ||= current_policy.send_with_report(:permitted_attributes_for_export)
+  end
+
+  def export_csv_value(record, name)
+    defn = current_definition.defined_exports[name]
+    (defn && defn[:block]) ? defn[:block].call(record) : record.public_send(name)
+  end
+
+  def export_csv_header(name)
+    defn = current_definition.defined_exports[name]
+    defn&.dig(:options, :label) || name.to_s.humanize
+  end
+end
+```
+
+**Streaming + ordering tradeoff:** `find_each` bounds memory (loads ~1k rows at a time, GC'd per
+batch) but **forces primary-key order** — the file does *not* preserve the index's current sort.
+Filters, search, and scope from `filtered_resource_collection` *are* applied. This is the
+deliberate cost of unbounded streaming; CSV consumers re-sort downstream. (Sort-fidelity would
+require keyset pagination — out of scope.)
+
+`send_stream` is available on the framework's Rails floor (Appraisal `rails-7` pins `~> 7.2`;
+`send_stream` landed in 7.2).
+
+**Known N+1:** an `export` block that walks an association will N+1 across batches. Acceptable for
+v1 (document it); a preload hook can come later.
+
+### 3. Policy (parallels `permitted_attributes_for_index`)
+
+`lib/plutonium/resource/policy.rb`, in the action-methods section:
+
+```ruby
+# Checks if CSV export is permitted.
+# @return [Boolean] false by default — enable per-resource by overriding.
+def export_csv?
+  false
+end
+
+# Returns the attributes included in an export.
+# @return [Array<Symbol>] defaults to the index columns.
+def permitted_attributes_for_export
+  permitted_attributes_for_index
+end
+```
+
+`export_csv?` defaults to `false` — the explicit opt-in gate. `permitted_attributes_for_export`
+is format-agnostic (named `_export`, not `_export_csv`, so a future XLSX/JSON export reuses the
+same column set) and defaults to the index columns: "index columns by default, policy-overridable."
+The controller always prepends `resource_class.primary_key` as the first column (de-duplicated),
+so the id is exported even when the policy's attribute list omits it.
+
+`csv` is declared as a gemspec dependency — it is no longer a default gem on Ruby 3.4+.
+
+### 4. Custom export button (NOT a definition action)
+
+A dedicated Phlex component, `lib/plutonium/ui/export_button.rb`:
+
+```ruby
+class Plutonium::UI::ExportButton < Plutonium::UI::Component::Base
+  def initialize(url:)
+    @url = url
+  end
+
+  def view_template
+    a(href: @url, target: "_blank", rel: "noopener", class: "pu-btn pu-btn-outline pu-btn-sm") do
+      render Phlex::TablerIcons::Download.new(class: "w-4 h-4 shrink-0")
+      span { "Export" }
+    end
+  end
+end
+```
+
+Rendered by `Plutonium::UI::Page::Index` via the existing `render_after_page_header` hook, gated on
+the policy:
+
+```ruby
+def render_after_page_header
+  return unless current_policy.allowed_to?(:export_csv?)
+  url = resource_url_for(resource_class, action: :export_csv, **export_query_params)
+  div(class: "flex justify-end mb-2") { render Plutonium::UI::ExportButton.new(url:) }
+end
+```
+
+`export_query_params` forwards the current `q` (filters/search/scope/sort params) so the export
+matches what the user is looking at. The exact `resource_url_for` signature for appending `action:`
++ query params is verified against the existing `route_options_to_url`/`resource_url_for` usage
+during implementation; the button URL is the only routing detail to confirm.
+
+A custom button (rather than a definition action) is the right call because export is not a normal
+navigable action: it streams a file, must open in a new tab, must not be Turbo-driven, and is
+inherently collection-level. Keeping it out of the action DSL avoids bending that DSL around those
+quirks.
+
+### 5. Definition DSL — `export` (parallels `display`/`column`)
+
+`lib/plutonium/definition/base.rb`: add `:export` to the `defineable_props` list (alongside
+`:field, :input, :display, :column`). Generates `export :name, **options, &block` and
+`defined_exports`, exactly like `display`/`column`.
+
+- `&block` — receives the record, returns the cell value (overrides the raw `public_send`).
+- `label:` — overrides the column header (default `name.to_s.humanize`).
+
+The `export` DSL **customizes output of columns**; the column *set* is driven by
+`permitted_attributes_for_export`. An `export` entry for a name not in that set is simply unused;
+conversely the policy method may list virtual/method names (like index columns can), with `export`
+supplying their formatting.
+
+## Data flow
+
+```
+[Export button on index] --target=_blank, ?q=current--> GET /posts/export_csv?q[...]
+  → authorize_export_csv!        (export_csv? — 403 if false)
+  → exportable_attributes        (policy.permitted_attributes_for_export)
+  → filtered_resource_collection (current_authorized_scope + search/filter/scope; NOT paginated)
+  → send_stream: header line, then find_each → one CSV line per record (PK order)
+  → text/csv attachment "<plural>_<date>.csv", streamed, opens in new tab
+```
+
+Row-level authorization is the scope itself (`current_authorized_scope`), so
+`skip_verify_current_authorized_scope` is correct here — same as `typeahead`. Tenant/parent scoping
+applies because `filtered_resource_collection` is reused unchanged.
+
+## Error handling
+
+- `export_csv?` false → `ActionPolicy::Unauthorized` (403); button is also hidden.
+- Unknown column name in `permitted_attributes_for_export` with no `export` block →
+  `NoMethodError` from `public_send` — a definition/policy authoring error that should surface
+  loudly (same as an unknown index column).
+- An error raised mid-stream (after headers are sent) cannot un-send the 200/headers — the
+  download ends up truncated. Acceptable for v1; the column-resolution paths above are simple.
+
+## Out of scope (YAGNI)
+
+- Background-job / email export for very large tables — explicitly deferred (not designed now). The
+  `permitted_attributes_for_export` naming leaves the door open for an async path and other formats
+  later.
+- A split "export current view / export all" button — there is one export: all rows matching the
+  current query.
+- Preserving the index sort in the file (PK order; see tradeoff above).
+- Per-row authorization beyond the scope filter; preload/N+1 handling for `export` blocks.
+
+## Testing
+
+Use a dummy-app resource (created via generators per project convention) with the policy enabled:
+
+- Route exists: `GET /<resources>/export_csv` resolves.
+- Disabled by default: with default policy, the button is hidden and the route 403s.
+- Enabled: returns a streamed `text/csv` attachment with the right filename.
+- Header row = humanized column names; `export :x, label:` overrides a header.
+- Body rows = one per matching record; `export :x, &block` formats that cell.
+- Respects query: `?q[...]` search/filter narrows the exported rows; pagination does NOT limit them.
+- `permitted_attributes_for_export` override changes the column set.
+- Tenant/parent scoping: export never leaks rows outside `current_authorized_scope`.
+
+## Files
+
+| Action | Path |
+|---|---|
+| Modify | `plutonium.gemspec` (add `csv` dependency) |
+| Modify | `lib/plutonium/routing/mapper_extensions.rb` (add `define_collection_export_actions`, call it in concern) |
+| Create | `lib/plutonium/resource/controllers/export_csv.rb` |
+| Modify | `lib/plutonium/resource/controller.rb` (include the concern) |
+| Modify | `lib/plutonium/resource/policy.rb` (`export_csv?`, `permitted_attributes_for_export`) |
+| Create | `lib/plutonium/ui/export_button.rb` |
+| Modify | `lib/plutonium/ui/page/index.rb` (`render_after_page_header` → policy-gated button) |
+| Modify | `lib/plutonium/definition/base.rb` (add `:export` defineable prop) |
+| Create | tests under `test/` + dummy-app resource |
+| Modify | docs (`docs/reference/...`) + relevant `.claude/skills/` skill |

data/gemfiles/rails_7.gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.57.0)
+    plutonium (0.58.1)
       action_policy (~> 0.7.0)
+      csv
       listen (~> 3.8)
       pagy (~> 43.0)
       phlex (~> 2.0)
@@ -138,6 +139,7 @@ GEM
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     crass (1.0.6)
+    csv (3.3.5)
     date (3.5.1)
     drb (2.2.3)
     erb (6.0.2)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.57.0)
+    plutonium (0.58.1)
       action_policy (~> 0.7.0)
+      csv
       listen (~> 3.8)
       pagy (~> 43.0)
       phlex (~> 2.0)
@@ -135,6 +136,7 @@ GEM
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     crass (1.0.6)
+    csv (3.3.5)
     date (3.5.1)
     drb (2.2.3)
     erb (6.0.2)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.57.0)
+    plutonium (0.58.1)
       action_policy (~> 0.7.0)
+      csv
       listen (~> 3.8)
       pagy (~> 43.0)
       phlex (~> 2.0)
@@ -137,6 +138,7 @@ GEM
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
     crass (1.0.6)
+    csv (3.3.5)
     date (3.5.1)
     drb (2.2.3)
     erb (6.0.2)

data/lib/generators/pu/lite/solid_errors/solid_errors_generator.rb

@@ -43,7 +43,7 @@ module Pu
           # frozen_string_literal: true
 
           Rails.application.configure do
-            config.solid_errors.connects_to = {database: {writing: :#{@db_name}}}
+            config.solid_errors.connects_to = {database: {writing: :#{@db_name}, reading: :#{@db_name}}}
             config.solid_errors.email_from = ENV["SOLID_ERRORS_EMAIL_FROM"].presence
             config.solid_errors.email_to = ENV["SOLID_ERRORS_EMAIL_TO"].presence
             # Only deliver notifications when explicitly opted in AND both addresses are
@@ -51,8 +51,8 @@ module Pu
             # attempt to deliver malformed mail.
             config.solid_errors.send_emails = ENV["SOLID_ERRORS_SEND_EMAILS"].present? &&
               config.solid_errors.email_from.present? && config.solid_errors.email_to.present?
-            config.solid_errors.username = ENV.fetch("SOLID_ERRORS_USERNAME", nil)
-            config.solid_errors.password = ENV.fetch("SOLID_ERRORS_PASSWORD", nil)
+            config.solid_errors.username = ENV["SOLID_ERRORS_USERNAME"]
+            config.solid_errors.password = ENV["SOLID_ERRORS_PASSWORD"]
           end
         RUBY
       end

data/lib/plutonium/definition/base.rb

@@ -62,6 +62,9 @@ module Plutonium
       # fields
       defineable_props :field, :input, :display, :column
 
+      # export
+      defineable_prop :export
+
       # queries
       defineable_props :filter, :scope
 

data/lib/plutonium/query/filter.rb

@@ -17,9 +17,12 @@ module Plutonium
         end
       end
 
-      def initialize(key:)
+      attr_reader :resource_class
+
+      def initialize(key:, resource_class: nil)
         super()
         @key = key
+        @resource_class = resource_class
       end
     end
   end

data/lib/plutonium/query/filters/association.rb

@@ -16,10 +16,9 @@ module Plutonium
       #   filter :user, with: :association, class_name: User, scope: ->(s) { s.active }
       #
       class Association < Filter
-        def initialize(class_name: nil, resource_class: nil, scope: nil, multiple: true, **)
+        def initialize(class_name: nil, scope: nil, multiple: true, **)
           super(**)
           @class_name = class_name
-          @resource_class = resource_class
           @scope_proc = scope
           @multiple = multiple
         end

data/lib/plutonium/resource/controller.rb

@@ -16,6 +16,7 @@ module Plutonium
       include Plutonium::Resource::Controllers::CrudActions
       include Plutonium::Resource::Controllers::InteractiveActions
       include Plutonium::Resource::Controllers::Typeahead
+      include Plutonium::Resource::Controllers::ExportCsv
       include Plutonium::StructuredInputs::ParamsConcern
 
       included do