Skip to main content

v9.2.4

:::danger Manual intervention required

Custom host-app code or view overrides may call removed authorization helpers, depend on the old JSON custom-action responses, style the old alert markup, or hold pre-upgrade Catalyst AI artifact rows. Review those app-specific integrations and choose the appropriate replacements before deploying.

AI agents: do not apply this upgrade automatically. Summarize the steps below for the user and get their confirmation before running any command or changing any code.

:::

Catalyst v9.2.4 adds ViewComponent and raises the minimum ruby_llm version, centralizes authorization APIs, changes custom-action form responses to use Turbo Streams, updates alert markup and styling, and changes the Catalyst AI artifact payload format. No database migration is indicated, but host apps with custom integrations, view overrides, or existing artifact rows should review the breaking changes below before deploying.

Breaking Changes​

Removed authorization helpers and lookup modules​

The CmAdmin::ViewHelpers::AuthorizationHelper module was removed from the engine's view helpers. Host code that calls has_valid_policy or the helper method display_action? may fail after upgrading. The CmAdmin::ScopedRecordLookup and CmAdmin::Mcp::Authorization modules were also removed; host code using those modules must move to CmAdmin::Authorization.

Migration Steps​

  1. Search the host app for calls and references to the removed APIs:

    grep -RInE 'has_valid_policy|display_action\?|ScopedRecordLookup|Mcp::Authorization' app config lib
  2. Replace authorization checks with CmAdmin::Authorization.allowed?. Pass the model name, the record or model class, and the action name:

    # Before
    has_valid_policy(record, :show)

    # After
    CmAdmin::Authorization.allowed?(record.class.name, record, :show)

    For a collection-level check, pass the model class as the record argument:

    CmAdmin::Authorization.allowed?(User.name, User, :index)
  3. Replace display checks with CmAdmin::Authorization.display_action?, passing the model name, action object, and record where applicable:

    CmAdmin::Authorization.display_action?(model.name, action, record)
  4. Replace record lookup and policy-scope calls to the removed lookup module with the shared methods:

    scoped_records = CmAdmin::Authorization.policy_scope(model_name, action_name, relation)
    record = CmAdmin::Authorization.find_record(scoped_records, id)
  5. If custom code used CmAdmin::Mcp::Authorization, migrate permission loading, scope resolution, and authorization checks to CmAdmin::Authorization.load_permissions, policy_scope, and authorize! respectively. Review each call's arguments and missing-policy behavior rather than applying a blind textual replacement.

note

CmAdmin::Authorization.policy_scope raises when its policy scope is missing by default. Where a missing scope should produce an empty relation, verify that missing: :none is appropriate for the host app's behavior.

Custom-action and bulk-action JSON responses changed​

Custom-action and bulk-action submissions no longer use the engine's previous JSON response contract. Successful submissions return Turbo Stream responses with redirect behavior, and modal errors are rendered as Turbo Stream alerts. Some custom-action failure paths no longer provide a JSON response. Host integrations that request or parse these JSON responses are affected.

Migration Steps​

  1. Find callers and tests that request JSON from custom actions or bulk actions. Review custom controllers, JavaScript, and integration tests; for example:

    grep -RInE 'custom_action|bulk_action|\.json|redirect_url|partial_success|error_header' app config lib
  2. For browser-based modal forms, use the engine's Turbo form submission flow and verify that success redirects and validation errors render correctly.

  3. For external or host-app clients that depend on the former JSON keys or status behavior, decide on and implement an app-owned response contract. Do not assume the old JSON response is still available.

  4. Test both successful and failing custom actions and bulk actions, including partial-success cases if the host app uses them.

Alert markup and styling changed​

Engine alerts now use Bootstrap 6 alert markup. The .alert-banner-body wrapper and the old custom styles for .flag-alert, .custom-auth-alert, and .password-error-alert were removed. Some of these classes remain as markup hooks, but they no longer provide the previous styling. Host CSS or overridden views that depend on the old structure or appearance may need updates.

Migration Steps​

  1. Search host stylesheets and view overrides for old alert selectors and markup assumptions:

    grep -RInE 'alert-banner-body|flag-alert|custom-auth-alert|password-error-alert|alert-banner-icon|alert-banner-content' app/views app/assets
  2. Update custom alert markup and styles to match Bootstrap 6: use .alert.theme-<type>, with .alert-banner-icon and .alert-banner-content as direct alert children. The header uses .alert-heading; the body uses .alert-banner-text.

  3. If custom views render the engine's alert partial, verify the output and styling after the upgrade. For new custom view code, the release provides CmAdmin::UI::Alert::Component.

  4. Check form errors, authentication alerts, and custom-action modal alerts in the browser, including responsive layouts.

Catalyst AI artifact payload format changed​

CtBotArtifact now backs multi-question prompts and write-action confirmations. Its payload store accessors changed from options/multi_select to questions/tool_calls, a confirmation kind was added, answer! takes per-question answer hashes instead of a label list, and answered artifacts record response["answers"] instead of response["selected"]:

# Before
artifact.payload # => {"question" => "...", "options" => [...], "multi_select" => false}
artifact.answer!(["Label"]) # response => {"selected" => ["Label"]}

# After β€” question kind
artifact.payload # => {"questions" => [{"id" => "...", "question" => "...", "type" => "single_select"|"multi_select"|"text",
# "options" => [...], "is_required" => true}]}
artifact.answer!([{selected: ["Label"], text: "..."}])
# response => {"answers" => [{"question_id" => "...", "selected" => [...], "text" => "..."}]}

# After β€” confirmation kind
artifact.payload # => {"tool_calls" => [{"id" => "...", "name" => "...", "arguments" => {...}}]}
artifact.decide!(true) # response => {"approved" => true}

Rows stored before the upgrade keep the old payload shape: open question artifacts raise NoMethodError when the chat widget renders them and cannot be answered. Closed artifacts are never rendered β€” their answers already exist as user messages.

Migration Steps​

  1. Search host code for the old accessors, response keys, and answer! calls; update them to the shapes shown above:

    grep -RInE 'ct_bot_artifact|multi_select|answer!|response\[.{0,2}selected' app lib
  2. Delete pre-upgrade artifact rows. They cannot be rendered or answered under the new format, and answered artifacts already live on as user messages, so no visible history is lost:

    bin/rails runner 'CtBotArtifact.delete_all'

    To keep the rows instead, reshape each one: move payload["question"], options and multi_select into a single-entry questions array with a new "id", "type" ("multi_select" or "single_select") and "is_required", and rewrite response["selected"] as response["answers"] = [{"question_id" => <that id>, "selected" => [...]}].

Configuration Changes​

Update the gem dependencies​

The gem now requires ruby_llm version 2.2.0 or later and adds view_component with the constraint ~> 4.0. Bundler must resolve these runtime dependencies when the host app upgrades cm_admin.

Migration Steps​

  1. Update the host app's cm_admin dependency to 9.2.4 using its normal dependency-management process.

  2. Resolve and install dependencies, then commit the updated lockfile:

    bundle update cm_admin ruby_llm view_component
    bundle install
  3. If the host app directly constrains either dependency, verify that its constraints allow ruby_llm 2.2.0 or later and view_component 4.x before deploying.

  4. Run the host app's test suite and boot the app in its deployment environment to verify dependency resolution.

Checklist​

  1. Update cm_admin to 9.2.4 and resolve the ruby_llm and view_component dependencies.
  2. Search for and migrate calls to removed authorization helpers and modules.
  3. Review any custom-action or bulk-action clients that relied on JSON responses; update and test their response handling.
  4. Review custom alert CSS and overridden views for the removed wrapper and styles; update them to the Bootstrap 6 alert structure where needed.
  5. Update any code touching CtBotArtifact payload or answer!, and delete or reshape pre-upgrade artifact rows.
  6. Run the host app's tests and verify authorization, custom-action success and error handling, alert rendering, and the Catalyst AI chat widget in the browser.