admin_suite 0.4.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 816ba44b1d87d7cc1ca92ccfcff24dc15a3c5eaadc23679de61a1977ab007a26
-  data.tar.gz: 89690a043f1fdb3e9a175d6fa32da6ba8b1d605c46b631ac23dbac6c9b04f630
+  metadata.gz: 964267328a54fb0d55bfb035fab32ba694b620b0f5cbdb45194e770a3138885f
+  data.tar.gz: eec49bd217460a272eb6ce1add0fd9ac487764a37e304bdcde105044f7eed80a
 SHA512:
-  metadata.gz: 9aec218fbb03dbb9550bd127eb38aab19709bf13a1874c186a878e3b8f32c4618b0698d879a5d685ae105146a9d4e8c446e4e2e3533c253d40f551b6f00597a9
-  data.tar.gz: 63f991346017892d5f0b2e10327cbedc5c86ba2739a5dfb9680c525d62c458a64b2341fc5a0861313391b7898946c5073152ac6ef5182ebfeb3ea2955957a604
+  metadata.gz: 5875a1f28a12afb57b1e43c38db7f4362f6ef896f2b0de7f0af2d949945ac1c60e17f0e24a5b3f967f753fdeac8960470f2076421ef31156f3fb64b03285fbd2
+  data.tar.gz: 76e74fce525a385fad34c84511f2affbfeca6df6ea147e81dfdaa393051c3b98915055f1b620040a140c6ce5e336823fc66928d2a0b01ca9017881914d530185

data/.gitignore

@@ -10,3 +10,10 @@
 /test/dummy/storage/
 admin_suite-*.gem
 /.bundle/
+
+# Agent scratch: git worktrees created per-phase, and subagent-driven-development
+# ledgers/briefs/review diffs. Never part of the gem — `spec.files` is an
+# allowlist, so these could not ship, but an `add -A` from the repo root would
+# otherwise commit an entire nested worktree.
+/.claude/
+/.superpowers/

data/CHANGELOG.md

@@ -5,12 +5,196 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.1] - 2026-09-12
+
+### Fixed
+- Automated gem publishing now uses RubyGems Trusted Publishing (GitHub Actions
+  OIDC) instead of a long-lived API key that required an interactive MFA code.
+- Publishing is restricted to successful CI for main-branch pushes from this
+  repository, or manual dispatch on main, using the protected `release` environment.
+
+### Upgrade notes
+- Includes the changes listed under 0.6.0 below, which was not published to
+  RubyGems. Upgrading from 0.5.0 requires the 0.6.0 host authentication,
+  authorization, and renderer migrations.
+
+## [0.6.0] - 2026-09-09
+
+### Breaking
+- `read_only` resources now reject declared member and bulk actions as well as
+  CRUD and toggle routes (404, no model mutation).
+- Authorization hooks now accept `context:` instead of `controller:`. Use
+  `context.surface` (`:web` or `:mcp`), `context.controller` (web only), and
+  `context.request`. Old signatures fail at assignment with migration guidance.
+- Removed the deprecated `exportable` no-op and the four built-in Gleania
+  renderer implementations. Hosts must remove `exportable` calls and provide
+  their own renderer classes before upgrading. Existing registered host keys work.
+- MCP requires a real actor and an explicit `config.authorize` hook. A nil hook
+  exposes no tools/data; authenticated web requests retain their existing behavior.
+- Default DSL page sizes above the configured cap are now capped on the web index too.
+
+### Added
+- Operator MCP at `<mount>/mcp`, using the official SDK's stateless HTTP transport.
+  Four read tools: `describe_resources`, `list_records`, `get_record`, `aggregate`.
+  Discovery includes portal, section, declared fields, and declared actions as
+  metadata (actions are not callable). Reads serialize declared fields only;
+  association panels require explicit columns and return bounded rows. No write
+  tools, LLM calls or chat UI in this release.
+- `:host_user` authentication strategy with a host-provided user resolver; shared
+  actor normalization across surfaces. Existing HTTP Basic and SSO still work.
+- Resource DSL `mcp false` opt-out and `config.mcp.enabled` / `max_page_size` settings.
+- `admin_suite.mcp.tool_call` notifications with tool, resource, action,
+  actor_type, actor_id, request_id, filters, q, allowed, error, result_count and
+  duration_ms. Hosts own request-log persistence.
+
+### Fixed
+- MCP index serialization evaluates column content lambdas (matching the web
+  index) and coerces times and association records to JSON primitives instead of
+  `to_s` heap addresses.
+- MCP/default pagination cannot bypass the configured cap by omitting `per_page`
+  or passing invalid/non-positive values. The response states the applied limit.
+- Anonymous MCP calls are rejected even under the development escape hatch;
+  `get_record` additionally checks record-level policy before serialization.
+- Foreign browser origins are rejected. Notifications return 202; unsupported
+  GET streams and session deletion return 405.
+
+### Changed
+- Extracted `AdminSuite::Query`; the web index and MCP share filter/search/sort,
+  eager-loading and page-size behavior, covered by parity/characterization tests.
+- Migration guide: `../_vault/products/admin_suite/docs/mcp.md`.
+
+## [0.5.0] - 2026-08-01
+
+### Added
+- **Charts.** `chart_panel` now renders a real Chart.js chart (Chart.js
+  4.5.1, vendored at `app/assets/vendor/chart.umd.min.js` — no gem
+  dependency, no CDN, works air-gapped/under a strict CSP), loaded only on
+  pages that actually render a chart with data. New `type:` option —
+  `:bar` (default), `:line`, `:area` (a Chart.js line chart with
+  `fill: true`), or `:doughnut`; an unrecognized value falls back to
+  `:bar` and logs a warning rather than raising, regardless of the input's
+  type (Symbol, String, Integer, Boolean, ...). New `height:` option (see
+  Changed below for the new default). The existing CSS bar chart remains
+  the no-JS degraded state — nothing is hidden until Chart.js has actually
+  built the real chart. See
+  `../_vault/products/admin_suite/docs/charts.md`.
+- Index rows are now clickable end to end via the already-existing (but
+  previously unwired) `ClickActionsController`: clicking anywhere on a row
+  other than an interactive element (link, button, form input) navigates to
+  the record's show page.
+- A 25/50/100 per-page selector in the index's existing filter form,
+  clamped server-side to a maximum of 100 regardless of what the
+  `per_page` query param requests, falling back to the resource's
+  `paginate(n)` value when the param is absent or invalid (non-numeric,
+  zero, negative, or array-shaped).
+- `column :name, align: :right` (also `:center`, `:left`) DSL option,
+  emitting the matching Tailwind alignment class on the `<td>`.
+- The index's `<thead>` is now `sticky top-0`, and its scroll wrapper is
+  now bounded (`max-h-[70vh] overflow-y-auto`, alongside the existing
+  `overflow-x-auto`) so the header actually pins **within that scroll
+  region** while scrolling a long page of results — not to the browser
+  viewport — instead of scrolling away with the page.
+- `index do includes :company, :line_items end` — eager-loads the named
+  associations on the index's filtered/sorted/searched scope, before
+  pagination. Skips silently on a scope that doesn't support `#includes`;
+  logs and degrades (unoptimized, still renders) if `#includes` itself
+  raises (e.g. a bad association name). See
+  `../_vault/products/admin_suite/docs/resources.md`.
+- A gem-provided JSON search endpoint, `GET <mount>/:portal/:resource/search?q=`,
+  for `searchable_select` — hosts no longer need to hand-build one. Enforces
+  authentication and `config.authorize` (`action: :read`), only searches the
+  resource's declared `searchable` fields, hard-caps at 25 results, and
+  returns `[]` (never the whole table) for a blank/missing `q`. New field
+  option `resource:` resolves a `searchable_select` field's search URL to
+  this endpoint automatically; a String `collection:` still overrides it
+  unconditionally. See `../_vault/products/admin_suite/docs/fields.md`.
+- `hide_blank: true` on show `fields:` panels (sidebar or main column) hides
+  a field's row entirely instead of rendering a label with an empty value.
+  Deliberately stricter than `.blank?`: only `nil`/`""`/`[]`/`{}` are
+  hidden — whitespace-only strings, `false`, and `0`/`0.0` are kept, since
+  none of those are "no data," and `false`/`0` are today's real rendered
+  values for a lot of fields. See
+  `../_vault/products/admin_suite/docs/resources.md`.
+
+### Changed
+- **Host-visible:** `belongs_to`-shaped values now render as links to the
+  associated record's own admin show page — in both index columns
+  (previously a raw `#<Company:0x...>` inspect string) and association
+  tables (previously plain text). Falls back to plain text (never a raw
+  inspect string, never a 500) when no resource is registered for the
+  associated class, the record is unpersisted, or its display title
+  raises.
+- **Host-visible:** the chart panel's default height changed from a 64px
+  strip to **192px**. 64px was enough for a sparkline-style bar row but not
+  a real chart with axes/labels; both the degraded bars and the live canvas
+  read the same height value, so there's no shift between the two, but
+  every existing dashboard's chart panels are now taller unless `height:`
+  is set explicitly. `chart_panel`'s markup for hosts overriding
+  `config.partials[:panel_chart]` has also changed shape (new Stimulus
+  mount + data attributes) — see the charts doc.
+- **Host-visible:** resources declaring `paginate(n)` now render that many
+  rows per page instead of Pagy's own default of 20 — see the Fixed entry
+  below. Operators may see different row counts and pagination boundaries
+  than they're used to.
+- `column.css_class` (populated by the DSL's `class:` option) is now
+  applied to the rendered `<td>`. Previously accepted but never read.
+- A column value that is `nil` now renders as `—`, matching every other
+  surface in the gem, instead of a blank cell. Applies to both plain
+  scalar columns and `belongs_to`-shaped association columns.
+- **Host-visible:** the `pagy` dependency range is now `>= 9.0, < 10`
+  (previously `>= 6.0, < 11.0`). `paginate_collection` calls `pagy(scope,
+  limit:)` (see the Fixed entry above) — `limit:` is Pagy 9.x's vars key,
+  silently ignored on Pagy 6-8, and Pagy 10 reworked the backend API
+  again. A host resolving Pagy 6-8 for another reason will now get a real
+  bundler resolution conflict at `bundle update` instead of quietly
+  reintroducing the "paginate(n) ignored, 20 rows forever" bug this
+  release fixes.
+- `turbo-rails` is now an explicit gem dependency. The engine has always
+  hard-depended on it (`turbo_frame_tag` in the resource views;
+  `format.turbo_stream`/`turbo_stream.replace` in the `toggle` action) —
+  this declares what was already true, it does not add a new
+  requirement.
+
+### Fixed
+- `paginate_collection` called `pagy(scope, items: n)`. Pagy's vars key
+  is `limit:`, not `items:` — `items:` silently did nothing, so **every
+  resource's `paginate(n)` DSL value has been ignored since the gem's
+  first commit**, with every index quietly paginating at Pagy's own
+  default of 20 regardless of what was declared. This is a long-standing
+  latent bug, not a regression introduced by this release; declared page
+  sizes now take effect.
+- A chart panel's `data:` proc raising, returning junk rows (non-Hash
+  entries mixed into the array), or returning rows with a non-numeric
+  `value` (Boolean, Hash, Array, nil, non-numeric String) all previously
+  500'd the dashboard. All three now degrade instead: a raising proc logs
+  and shows "No chart data."; junk rows are dropped; junk values render as
+  a zero-height bar/slice. String-keyed data rows (e.g. from a JSONB
+  column) are also now tolerated the same way `data_table` already
+  handles them — previously they rendered blank/zero bars silently rather
+  than the real value.
+- A chart panel's `height:` option 500'd the dashboard for any value that
+  survives `presence` but doesn't respond to `#to_i` (`true`, a Symbol, a
+  non-empty Array or Hash — e.g. `height: :tall` or `height: [200]`). Now
+  totally coerced the same way `data:` row values are, falling back to the
+  default 192px for anything that doesn't genuinely parse as a number.
+  `color:` had the same gap (pre-existing since 0.4.0): any value without
+  `#to_sym` (an Integer, Boolean, ...) 500'd the dashboard instead of
+  falling through to the existing unknown-color default (indigo).
+
+### Deprecated
+- **Unchanged, reiterated for clarity:** the four Gleania-specific renderer
+  keys (`:prompt_template_preview`, `:messages_preview`,
+  `:tool_args_preview`, `:turn_messages_preview`) and
+  `Resource.exportable(*formats)` remain deprecated (as of 0.4.0) and
+  **still work in 0.5.0**. Their removal, originally targeted at 0.5.0, is
+  now targeted at **0.6.0**, pending the Gleania and TrustGrowth host
+  migrations. The runtime deprecation warnings (and their source comments)
+  have been retargeted to say 0.6.0 as part of this release.
 
 ## [0.4.0] - 2026-08-01
 
 ### Added
-- `AdminSuite::Renderer` base class for show-panel renderers, with shared
+- `AdminSuite::Renderer` base class for panel renderers, with shared
   primitives (`json_block`, `code_block`, `key_value_list`, `data_table`,
   `badge`, `empty_state`). Host renderers live in `app/admin/renderers/*.rb`
   as `Admin::Renderers::<Key>Renderer` and are autoloaded from a panel's
@@ -49,12 +233,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   paper only, with no runtime signal.
 - The built-in `:prompt_template_preview`, `:messages_preview`,
   `:tool_args_preview` and `:turn_messages_preview` renderers. They warn once
-  per key per process and are **removed in 0.5.0**.
+  per key per process and are **removed in 0.5.0** (removal retargeted to
+  0.6.0 — see [0.5.0]).
 - `Resource.exportable(*formats)` — a no-op that warns once per resource
-  class, naming the class, and is **removed in 0.5.0**. It was write-only
-  in every prior release (never had a reader, never drove any export
-  behavior); calling it is now harmless instead of raising `NoMethodError`
-  at resource-definition time.
+  class, naming the class, and is **removed in 0.5.0** (removal retargeted
+  to 0.6.0 — see [0.5.0]). It was write-only in every prior release (never
+  had a reader, never drove any export behavior); calling it is now
+  harmless instead of raising `NoMethodError` at resource-definition time.
 
 ### Fixed
 - A host `Admin::Renderers::<Key>Renderer` class (or an explicit
@@ -97,6 +282,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.3.0] - 2026-07-31
 
+### Added
+- Pluggable auth strategies: `AdminSuite::Auth.register`, built-in
+  `:http_basic` (ENV or `config.auth_options` credentials, constant-time
+  comparison, blank credentials deny).
+- `config.authorize` is now enforced for every resource action with the
+  contract `->(actor:, action:, resource:, record:, controller:)`,
+  action ∈ :read/:create/:update/:destroy/:execute.
+- `config.skip_host_before_actions` (default `[:require_authentication]`)
+  replaces the hardcoded host-filter skip.
+
 ### Changed (BREAKING)
 - AdminSuite now **fails closed**: with no authentication configured, every
   engine request responds 403. Configure `config.auth_strategy = :http_basic`
@@ -108,17 +303,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   dedicated bulk-action lookup. Declared member and bulk actions remain
   allowed on `read_only` resources by design.
 - `execute_action` with an unknown action name now responds 404 instead of
-  redirecting with an "Action not found." alert.
-
-### Added
-- Pluggable auth strategies: `AdminSuite::Auth.register`, built-in
-  `:http_basic` (ENV or `config.auth_options` credentials, constant-time
-  comparison, blank credentials deny).
-- `config.authorize` is now enforced for every resource action with the
-  contract `->(actor:, action:, resource:, record:, controller:)`,
-  action ∈ :read/:create/:update/:destroy/:execute.
-- `config.skip_host_before_actions` (default `[:require_authentication]`)
-  replaces the hardcoded host-filter skip.
+  redirecting with an "Action not found" alert.
 
 ### Fixed
 - `config.current_actor` is now consulted at most once per request

data/CONTRIBUTING.md

@@ -28,7 +28,7 @@ See `../_vault/products/admin_suite/docs/development.md` for detailed informatio
 ### CI Checks
 
 All pull requests must pass the following checks before merging:
-- **Tests**: Automated test suite runs on Ruby 3.2 and 3.3
+- **Tests**: Automated test suite runs on the latest available patch releases of Ruby 3.2, 3.3, 3.4, and 4.0
 - **Coverage**: Code coverage is automatically generated and uploaded to Codecov
 - **Code Review**: At least one maintainer approval required
 
@@ -40,10 +40,15 @@ See `../_vault/products/admin_suite/docs/releasing.md` for information on how re
 
 Releases are automated via GitHub Actions when changes are merged to `main` with a version bump.
 
-### Required Secrets for Maintainers
+### Publishing Setup for Maintainers
 
-The repository requires the following secrets to be configured:
-- **`RUBYGEMS_API_KEY`**: Required for automated gem publishing to RubyGems
+RubyGems Trusted Publishing authenticates GitHub Actions with short-lived OIDC
+credentials; no `RUBYGEMS_API_KEY` secret is needed. The gem's trusted publisher
+must match `techwright-lab/admin_suite`, workflow `publish.yml`, and environment
+`release`. Restrict the GitHub `release` environment to the `main` branch.
+See the canonical releasing guide linked above for setup and verification.
+
+Optional repository secret:
 - **`CODECOV_TOKEN`**: Optional, for uploading code coverage reports to Codecov (workflow continues without it)
 
 ## Questions?

data/README.md

@@ -11,6 +11,7 @@ across other products.
 - **Portals**: group resources by portal + section, optional per-portal dashboards
 - **Resources DSL**: index (columns/filters/stats), form fields, show panels/associations, actions
 - **Docs viewer**: renders `*.md` from your host app filesystem at `/docs`
+- **Admin MCP**: four read tools derived from resource definitions, under operator authentication and explicit authorization
 - **UI**: baseline CSS + engine Tailwind build; host overrides optional
 
 ## Documentation
@@ -43,20 +44,35 @@ bin/rails g admin_suite:install --mount-path=/internal/admin
 
 ### Secure it (recommended)
 
-Set `config.authenticate` so only authorized users can access AdminSuite:
+Resolve the host user and authorize admin access:
 
 ```ruby
 # config/initializers/admin_suite.rb
 AdminSuite.configure do |config|
-  config.authenticate = ->(controller) do
-    user = controller.respond_to?(:current_user) ? controller.current_user : nil
-    controller.head(:forbidden) unless user&.admin?
-  end
+  config.auth_strategy = :host_user
+  config.auth_options = { resolve: ->(controller) { controller.current_user } }
+  config.authorize = ->(actor:, action:, resource:, record:, context:) { actor&.admin? }
 end
 ```
 
 Read more: `../_vault/products/admin_suite/docs/configuration.md`
 
+Set `config.authorize` to decide *what* an authenticated actor may do:
+
+```ruby
+config.authorize = ->(actor:, action:, resource:, record:, context:) {
+  # action is :read, :create, :update, :destroy, or :execute
+  true
+}
+```
+
+A `false` or `nil` return is `403` (fail closed). Leaving the hook `nil`
+keeps authentication as the only web gate; MCP serves no tools or data. Resources marked `read_only` reject
+CRUD, `toggle`, and named execute/bulk actions regardless of this hook.
+
+The MCP endpoint is `<mount>/mcp`. See
+`../_vault/products/admin_suite/docs/mcp.md` for setup, tool contracts and migration.
+
 ### Add portals (navigation metadata)
 
 ```ruby