plutonium 0.58.1 → 0.59.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4aacffd8e85ac820827b65cc219e00cded934d37d879756ea808a8f9ba86fc26
-  data.tar.gz: bc6d63a46c46f0f01b2351590b36ee54108a29372c4f9aa1d0d3922ab014f334
+  metadata.gz: dfbb1eb8e3b796aa9ef55595aa4fc0a475f4a5f084388f0aebd4bf76eec468ae
+  data.tar.gz: 8b15084a3c2a0ef577cd7b88fe2ebc1666d274fd0effa28227c674c722a16b09
 SHA512:
-  metadata.gz: d29f628a11fdff4163c3430d225912902d07481fef1bc23bdacb23390cda5a063a604a3432929938a1c37bf7afc04aea643f1c0400d99478be62314d3ec8be89
-  data.tar.gz: 52b66cfe37dde6f57dcb2cda8d8ab9369e585d0f8847d4af0e35b78f3af4bd5bad20a6c0de2840c872bc37fe34b45343538001308bd822c5f3bbc399b44e2b1b
+  metadata.gz: e75d7e2efadc2c1ff0bb2d57d979604fff1e7ffef6c8ecbb7635f4aeafb13716852932bfd439bc444f79404f4cf106ee203dc0d525c06b5d9d13b6536c8f82fb
+  data.tar.gz: 548b3f3b61d032c540847982e31e7734aed74b47b4cdce1867207c49bba7b3981e0de367955d3eed2d74a679187238deb8226913b396d6714002ba6dc42b7757

data/.claude/skills/plutonium-behavior/SKILL.md

@@ -375,6 +375,9 @@ end
 | `new?` | `create?` | Rarely needed |
 | `edit?` | `update?` | Rarely needed |
 | `search?` | `index?` | Search-specific rules |
+| `typeahead?` | `index?` | Autocomplete-specific rules |
+
+`export_csv?` is the exception — it defaults to `false` (not derived) so CSV export is strictly opt-in. Override it to `true` (or `index?`) to enable the built-in export. The exported column set is `permitted_attributes_for_export` (defaults to `permitted_attributes_for_index`). See [[plutonium-resource]] → CSV Export.
 
 ### Custom actions
 
@@ -423,6 +426,7 @@ end
 | `permitted_attributes_for_show` | `permitted_attributes_for_read` |
 | `permitted_attributes_for_new` | `permitted_attributes_for_create` |
 | `permitted_attributes_for_edit` | `permitted_attributes_for_update` |
+| `permitted_attributes_for_export` | `permitted_attributes_for_index` (CSV export columns; primary key is always prepended) |
 
 ### Per-action override
 

data/.claude/skills/plutonium-resource/SKILL.md

@@ -1290,6 +1290,55 @@ end
 - **Immediate** — interaction has only `:resource` (or `:resources`) and no other inputs. Shows an auto-generated browser confirmation (`"#{label}?"`, e.g. `"Archive?"`) on click, then runs. Pass `confirmation: "Custom message"` to override, or `confirmation: false` to skip.
 - **Form** — interaction declares extra `attribute`/`input` beyond `:resource`/`:resources`. Renders a modal form first; no auto-confirmation (the form itself is the confirmation step).
 
+## CSV Export (built-in)
+
+Every resource has a streamed CSV export, **disabled by default**. It is not declared
+with `action :export_csv` — it's a policy-gated capability with its own split button.
+The route (`GET /<resources>/export_csv`) is auto-mounted; the button appears on the
+index page once the policy permits it. Enable it by overriding one policy method:
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def export_csv? = true          # or `index?` to mirror list access
+end
+```
+
+**Two exports** (split button in the index toolbar, after Filter):
+- **Export** (primary) — the current view: selected scope + filters + search (the
+  index's `?q`), all matching rows (not just the visible page). File: `posts_<date>.csv`.
+- **Export all** (dropdown) — the entire authorized scope, ignoring scope/filters/
+  search (`?all=1`). File: `posts_all_<date>.csv`.
+
+Both stream via `find_each` (memory-safe on large tables; primary-key order, so the
+file does not preserve the index sort).
+
+- **Columns** = `permitted_attributes_for_export` (defaults to the index columns),
+  with the **primary key always first**. Override to tailor:
+
+```ruby
+def permitted_attributes_for_export = [:title, :author, :total, :created_at]
+```
+
+- **Per-field output** — customize a cell's value and header in the definition with
+  the `export` DSL (parallels `display`/`column`):
+
+```ruby
+class PostDefinition < ResourceDefinition
+  export :author, label: "Author email", &->(post) { post.author.email }
+  export :total,                          &->(post) { post.total.format }
+end
+```
+
+- **Without** an `export` block a column is read off the record: scalars as-is,
+  associations as their `display_name_of` label (e.g. `User #5`, not `#<User:…>`). A
+  computed/virtual column with no real method **needs** an `export` block (a `label:`-only
+  `export` doesn't supply a value) — otherwise the cell renders `<<invalid column>>`.
+- **CSV/formula injection** is neutralized automatically (cells starting with `= + - @` or
+  tab/CR get a leading `'`).
+
+The button opens in a new tab (so the streamed download bypasses Turbo). Full reference:
+`docs/reference/resource/export.md`.
+
 ---
 
 ## Related Skills

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.59.0] - 2026-06-13
+
+### 🚀 Features
+
+- *(resource)* Add built-in policy-gated CSV export
+
+### 🐛 Bug Fixes
+
+- *(generators)* Configure solid_errors reading connection and env lookup
+- *(query)* Resolve association filter class via resource_class reflection
 ## [0.58.1] - 2026-06-10
 
 ### 🐛 Bug Fixes

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

data/lib/plutonium/resource/controllers/export_csv.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Plutonium
+  module Resource
+    module Controllers
+      # Streams the current resource collection as a CSV download.
+      #
+      # Auto-mounted on every Plutonium resource via the
+      # `interactive_resource_actions` routing concern (see
+      # Plutonium::Routing::MapperExtensions). Gated by the `export_csv?`
+      # policy method, which defaults to `false` — export is strictly
+      # opt-in (enable it by overriding `export_csv?` to return true).
+      #
+      # The exported rows are exactly the index's filtered collection
+      # (`filtered_resource_collection`) — same search, filters, scope, and
+      # tenant/parent scoping — but NOT paginated: every matching record is
+      # exported. Rows are streamed (a lazy Enumerator body + `find_each`) so
+      # memory stays flat regardless of row count.
+      #
+      # Columns come from `policy.permitted_attributes_for_export` (defaults
+      # to the index columns), with the primary key always prepended as the
+      # first column. Per-field output and headers are customizable through
+      # the definition's `export` DSL.
+      #
+      # `find_each` iterates in primary-key order, so the file does not
+      # preserve the index's current sort (filters/search/scope still apply).
+      #
+      # Streaming uses a lazy Enumerator response body rather than
+      # `send_stream` — the latter lives in ActionController::Live, which
+      # would turn *every* resource action into a threaded streaming
+      # response. The Enumerator body streams through Rack on its own.
+      module ExportCsv
+        extend ActiveSupport::Concern
+
+        # Placeholder written when a column is neither an `export` block nor a
+        # real attribute on the record, so the export degrades to a usable file
+        # instead of a mid-stream NoMethodError (which would truncate the
+        # already-committed download).
+        INVALID_COLUMN = "<<invalid column>>"
+
+        included do
+          before_action :authorize_export_csv!, only: :export_csv
+          # Row-level authorization is the scope itself
+          # (current_authorized_scope via filtered_resource_collection), so
+          # the after_action scope verifier is redundant here.
+          skip_verify_current_authorized_scope only: :export_csv
+        end
+
+        # GET /<resources>/export_csv
+        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)
+          # Defeat proxy/`Rack::ETag` buffering so rows flush as they're read.
+          response.headers["X-Accel-Buffering"] = "no"
+          response.headers["Cache-Control"] = "no-cache"
+
+          self.response_body = export_csv_lines
+        end
+
+        private
+
+        def authorize_export_csv!
+          authorize_current! resource_class, to: :export_csv?
+        end
+
+        def export_csv_filename
+          suffix = export_all_requested? ? "_all" : ""
+          "#{export_csv_basename}#{suffix}_#{Date.current}.csv"
+        end
+
+        # The human resource name, slugified for a filesystem-friendly file
+        # (Blogging::Post → "posts", not the route key "blogging_posts").
+        def export_csv_basename
+          helpers.resource_name_plural(resource_class).parameterize(separator: "_")
+        end
+
+        # Which records to export. Two modes:
+        # - default — the index's filtered collection (current scope,
+        #   filters, and search via `?q`).
+        # - `?all=1` — the entire authorized scope, bypassing the query
+        #   object entirely (no scope/filter/search/default-scope).
+        # Both still respect tenant/parent scoping (current_authorized_scope).
+        def export_csv_collection
+          export_all_requested? ? current_authorized_scope : filtered_resource_collection
+        end
+
+        def export_all_requested?
+          ActiveModel::Type::Boolean.new.cast(params[:all])
+        end
+
+        # A lazy line enumerator: the header row, then one CSV line per
+        # record streamed via `find_each` (bounded memory). Pure with
+        # respect to the response, so it's unit-testable on its own.
+        def export_csv_lines
+          columns = export_columns
+          Enumerator.new do |yielder|
+            yielder << export_csv_row(columns.map { |name| export_csv_header(name) })
+            export_csv_collection.find_each do |record|
+              yielder << export_csv_row(columns.map { |name| export_csv_value(record, name) })
+            end
+          end
+        end
+
+        # Serializes one row, neutralizing spreadsheet formula injection per cell.
+        def export_csv_row(cells)
+          CSV.generate_line(cells.map { |cell| neutralize_csv_formula(cell) })
+        end
+
+        # A cell beginning with = + - @ (or a leading tab/CR) is executed as a
+        # formula by Excel/Sheets. Prefix it with a single quote so the value
+        # imports as literal text (CSV/formula injection).
+        def neutralize_csv_formula(value)
+          string = value.to_s
+          /\A[=+\-@\t\r]/.match?(string) ? "'#{string}" : string
+        end
+
+        # The primary key is always the first column, followed by the
+        # policy's exportable attributes (de-duplicated so an explicitly
+        # listed primary key isn't repeated).
+        def export_columns
+          primary_key = resource_class.primary_key.to_sym
+          [primary_key] + (exportable_attributes.map(&:to_sym) - [primary_key])
+        end
+
+        def exportable_attributes
+          @exportable_attributes ||= current_policy.send_with_report(:permitted_attributes_for_export)
+        end
+
+        # Resolves a cell's value. An `export` block (definition DSL) takes
+        # precedence; otherwise the attribute is read off the record.
+        # Associations render as their display label — the same as the index —
+        # instead of "#<User:0x…>"; scalars pass through untouched. A name that
+        # is neither an `export` block nor a real attribute renders the
+        # INVALID_COLUMN placeholder rather than aborting the stream.
+        def export_csv_value(record, name)
+          definition = current_definition.defined_exports[name]
+          return definition[:block].call(record) if definition && definition[:block]
+
+          begin
+            value = record.public_send(name)
+          rescue NoMethodError
+            return INVALID_COLUMN
+          end
+
+          case value
+          when ActiveRecord::Base then helpers.display_name_of(value)
+          when ActiveRecord::Relation then helpers.display_name_of(value.to_a)
+          else value
+          end
+        end
+
+        def export_csv_header(name)
+          definition = current_definition.defined_exports[name]
+          definition&.dig(:options, :label) || name.to_s.humanize
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/resource/controllers/queryable.rb

@@ -40,6 +40,7 @@ module Plutonium
                   filter_class = Plutonium::Query::Filter.lookup(with)
                   options = value[:options].except(:with)
                   options[:key] ||= key
+                  options[:resource_class] ||= resource_class
                   with = filter_class.new(**options)
                 end
                 query_object.define_filter key, with, &value[:block]

data/lib/plutonium/resource/policy.rb

@@ -186,6 +186,16 @@ module Plutonium
         index?
       end
 
+      # Checks if CSV export is permitted.
+      #
+      # Defaults to false so export is strictly opt-in. Enable it per
+      # resource by overriding to return true (or delegating to index?).
+      #
+      # @return [Boolean] false by default.
+      def export_csv?
+        false
+      end
+
       # Core attributes
 
       # Returns the permitted attributes for the create action.
@@ -228,6 +238,17 @@ module Plutonium
         permitted_attributes_for_read
       end
 
+      # Returns the attributes included in an export (e.g. CSV columns).
+      #
+      # Format-agnostic on purpose (named `_export`, not `_export_csv`) so a
+      # future export format can reuse the same column set. Defaults to the
+      # index columns; override to tailor the exported columns.
+      #
+      # @return [Array<Symbol>] Delegates to permitted_attributes_for_index.
+      def permitted_attributes_for_export
+        permitted_attributes_for_index
+      end
+
       # Returns the permitted attributes for the new action.
       #
       # @return [Array<Symbol>] Delegates to permitted_attributes_for_create.

data/lib/plutonium/routing/mapper_extensions.rb

@@ -42,6 +42,7 @@ module Plutonium
           define_member_interactive_actions
           define_collection_interactive_actions
           define_collection_typeahead_actions
+          define_collection_export_actions
         end
       end
 
@@ -181,6 +182,18 @@ module Plutonium
             as: :typeahead_filter
         end
       end
+
+      # Defines the collection-level CSV export action. Auto-mounted on
+      # every Plutonium resource alongside typeahead and bulk actions.
+      # The action itself is gated by the `export_csv?` policy (default
+      # false), so the route is harmless until a resource opts in.
+      #
+      # @return [void]
+      def define_collection_export_actions
+        collection do
+          get "export_csv", action: :export_csv, as: :export_csv
+        end
+      end
     end
   end
 end

data/lib/plutonium/ui/export_button.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module UI
+    # Connected split "Export" control for the index toolbar (sits beside
+    # the Filter button and shares its `pu-btn-outline pu-btn-sm` styling).
+    #
+    # The primary button exports the current view (selected scope + filters
+    # + search). The caret opens a menu with "Export all", which exports the
+    # entire authorized scope.
+    #
+    # Both links carry `target="_blank"`, which opens the streamed download
+    # in a new tab and bypasses Turbo (Turbo ignores links with a `target`).
+    #
+    # The two halves are joined into one control by flattening their shared
+    # inner corners via inline styles (`rounded-*-none` utilities aren't in
+    # the packaged stylesheet), so it reads as a single button rather than
+    # two pills.
+    class ExportButton < Plutonium::UI::Component::Base
+      # Inline corner/border tweaks that join the two halves seamlessly.
+      PRIMARY_STYLE = "border-top-right-radius:0;border-bottom-right-radius:0"
+      CARET_STYLE = "border-top-left-radius:0;border-bottom-left-radius:0;border-left-width:0;padding-left:0.375rem;padding-right:0.375rem"
+
+      def initialize(scoped_url:, all_url:)
+        @scoped_url = scoped_url
+        @all_url = all_url
+      end
+
+      def view_template
+        div(class: "relative inline-flex", data: {controller: "resource-drop-down"}) do
+          render_primary
+          render_caret
+          render_menu
+        end
+      end
+
+      private
+
+      def render_primary
+        a(
+          href: @scoped_url,
+          target: "_blank",
+          rel: "noopener",
+          class: "pu-btn pu-btn-outline pu-btn-sm",
+          style: PRIMARY_STYLE
+        ) do
+          render Phlex::TablerIcons::Download.new(class: "w-4 h-4 shrink-0")
+          span { "Export" }
+        end
+      end
+
+      def render_caret
+        button(
+          type: "button",
+          class: "pu-btn pu-btn-outline pu-btn-sm",
+          style: CARET_STYLE,
+          aria: {expanded: "false", haspopup: "menu", label: "More export options"},
+          data: {resource_drop_down_target: "trigger"}
+        ) do
+          render Phlex::TablerIcons::ChevronDown.new(class: "w-4 h-4")
+        end
+      end
+
+      def render_menu
+        div(
+          class: "hidden absolute right-0 top-full z-50 mt-1 w-48 origin-top-right bg-[var(--pu-surface)] " \
+                 "border border-[var(--pu-border)] rounded-[var(--pu-radius-lg)] overflow-hidden",
+          style: "box-shadow: var(--pu-shadow-lg)",
+          data: {resource_drop_down_target: "menu"}
+        ) do
+          div(class: "py-1") do
+            a(
+              href: @all_url,
+              target: "_blank",
+              rel: "noopener",
+              class: "flex items-center gap-2 px-4 py-2 text-sm text-[var(--pu-text)] hover:bg-[var(--pu-surface-alt)] transition-colors"
+            ) do
+              render Phlex::TablerIcons::Download.new(class: "w-4 h-4")
+              span { "Export all" }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/ui/table/components/toolbar.rb

@@ -8,7 +8,7 @@ module Plutonium
         # inline search, and column config / overflow icon buttons into a single
         # tight strip rendered above the table when shell == :modern.
         class Toolbar < Plutonium::UI::Component::Base
-          def initialize(query:, search_url:, search_param: :q, search_value: nil, views: [:table], current_view: :table, view_cookie_name: nil, view_cookie_path: "/")
+          def initialize(query:, search_url:, search_param: :q, search_value: nil, views: [:table], current_view: :table, view_cookie_name: nil, view_cookie_path: "/", export: nil)
             @query = query
             @search_url = search_url
             @search_param = search_param
@@ -17,10 +17,11 @@ module Plutonium
             @current_view = current_view
             @view_cookie_name = view_cookie_name
             @view_cookie_path = view_cookie_path
+            @export = export
           end
 
           def render?
-            @views.size > 1 || has_filters? || has_search?
+            @views.size > 1 || has_filters? || has_search? || @export.present?
           end
 
           def view_template
@@ -29,11 +30,17 @@ module Plutonium
               render switcher
               render_divider if switcher.render?
               render_filter_button
+              render_export_button if @export
               div(class: "flex-1")
               render_search if has_search?
             end
           end
 
+          # Export split button, rendered just after the Filter button.
+          def render_export_button
+            render Plutonium::UI::ExportButton.new(**@export)
+          end
+
           private
 
           def has_filters?

data/lib/plutonium/ui/table/resource.rb

@@ -47,10 +47,27 @@ module Plutonium
             views: resource_definition.defined_index_views,
             current_view: :table,
             view_cookie_name: Plutonium::UI::Page::Index.view_cookie_name(resource_class),
-            view_cookie_path: Plutonium::UI::Page::Index.view_cookie_path(request)
+            view_cookie_path: Plutonium::UI::Page::Index.view_cookie_path(request),
+            export: export_toolbar_config
           )
         end
 
+        # Export split-button config, or nil when the policy forbids export.
+        # The primary link carries the current query (selected scope + filters
+        # + search); "Export all" carries `?all=1`.
+        def export_toolbar_config
+          return nil unless current_policy.allowed_to?(:export_csv?)
+
+          {
+            scoped_url: resource_url_for(resource_class, action: :export_csv, **export_query_params),
+            all_url: resource_url_for(resource_class, action: :export_csv, all: 1)
+          }
+        end
+
+        def export_query_params
+          params[:q].present? ? {q: params[:q].to_unsafe_h} : {}
+        end
+
         def render_filter_pills
           TableFilterPills(query: current_query_object, total_count: pagy_instance&.count)
         end

data/lib/plutonium/version.rb

@@ -1,5 +1,5 @@
 module Plutonium
-  VERSION = "0.58.1"
+  VERSION = "0.59.0"
   NEXT_MAJOR_VERSION = VERSION.split(".").tap { |v|
     v[1] = v[1].to_i + 1
     v[2] = 0

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radioactive-labs/plutonium",
-  "version": "0.58.1",
+  "version": "0.59.0",
   "description": "Build production-ready Rails apps in minutes, not days. Convention-driven, fully customizable, AI-ready.",
   "type": "module",
   "main": "src/js/core.js",

data/plutonium.gemspec

@@ -51,6 +51,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "zeitwerk"
   spec.add_dependency "rails", ">= 7.2"
+  spec.add_dependency "csv" # CSV export; no longer a default gem on Ruby 3.4+
   spec.add_dependency "listen", "~> 3.8"
   spec.add_dependency "pagy", "~> 43.0"
   spec.add_dependency "rabl", "~> 0.17.0" # TODO: what to do with RABL

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: plutonium
 version: !ruby/object:Gem::Version
-  version: 0.58.1
+  version: 0.59.0
 platform: ruby
 authors:
 - Stefan Froelich
 bindir: exe
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: listen
   requirement: !ruby/object:Gem::Requirement
@@ -641,6 +655,7 @@ files:
 - docs/reference/index.md
 - docs/reference/resource/actions.md
 - docs/reference/resource/definition.md
+- docs/reference/resource/export.md
 - docs/reference/resource/index.md
 - docs/reference/resource/model.md
 - docs/reference/resource/query.md
@@ -680,6 +695,7 @@ files:
 - docs/superpowers/specs/2026-05-29-avatar-component-design.md
 - docs/superpowers/specs/2026-06-01-structured-inputs-design.md
 - docs/superpowers/specs/2026-06-04-sqlite-tune-maintenance-generators-design.md
+- docs/superpowers/specs/2026-06-12-export-csv-default-action-design.md
 - esbuild.config.js
 - exe/pug
 - gemfiles/rails_7.gemfile
@@ -1045,6 +1061,7 @@ files:
 - lib/plutonium/resource/controllers/crud_actions.rb
 - lib/plutonium/resource/controllers/crud_actions/index_action.rb
 - lib/plutonium/resource/controllers/defineable.rb
+- lib/plutonium/resource/controllers/export_csv.rb
 - lib/plutonium/resource/controllers/interactive_actions.rb
 - lib/plutonium/resource/controllers/presentable.rb
 - lib/plutonium/resource/controllers/queryable.rb
@@ -1105,6 +1122,7 @@ files:
 - lib/plutonium/ui/dyna_frame/content.rb
 - lib/plutonium/ui/dyna_frame/host.rb
 - lib/plutonium/ui/empty_card.rb
+- lib/plutonium/ui/export_button.rb
 - lib/plutonium/ui/form/base.rb
 - lib/plutonium/ui/form/components/easymde.rb
 - lib/plutonium/ui/form/components/flatpickr.rb