rails_ai_admin 0.1.0

data/app/controllers/rails_ai_admin/selections_controller.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Snapshot capture/view is deliberately separate from business confirmation.
+  class SelectionsController < ApplicationController
+    def create
+      @resource = RailsAiAdmin.registry.fetch(params[:resource])
+      resolve_list_navigation
+      # Nothing ticked is an ordinary mistake: return to the same list (RAA-013).
+      if Array(params[:target_ids]).compact_blank.empty?
+        Authorization::Access.new(@context, @resource).authorize_selection!
+        redirect_to list_return_path, status: :see_other, notice: t("rails_ai_admin.selections.empty")
+        return
+      end
+      selection = Selections::Builder.new.capture(context: @context, resource: @resource, target_ids: params[:target_ids])
+      redirect_to selection_path(selection_ref: selection.selection_ref, **navigation_params), status: :see_other
+    end
+
+    def show
+      records = []
+      @selection = Selections::Builder.new.revalidate(context: @context, selection_ref: params[:selection_ref]) { |record| records << record }
+      @resource = RailsAiAdmin.registry.fetch(@selection.resource_key)
+      resolve_list_navigation
+      access = Authorization::Access.new(@context, @resource)
+      # Offered when the actor may delete at least one selected record now.
+      @deletable = @resource.action_enabled?(:destroy) && records.any? do |record|
+        access.authorize!(:destroy, record)
+      rescue AccessDenied
+        false
+      end
+      @operations = RailsAiAdmin.operation_registry.custom(@resource).select do |definition|
+        next false unless definition.scope == :collection
+        access.authorize!(definition.key)
+        definition.fields(access, nil)
+        true
+      rescue AccessDenied
+        false
+      end
+    end
+
+    # Bulk delete reviews the fixed selection: records the actor may delete
+    # now, and how many will be skipped.
+    def confirm_destroy
+      load_deletable
+      raise AccessDenied if @deletable.empty?
+    end
+
+    # Each record is deleted through the native destroy operation, with its own
+    # policy check, captured version, transaction and audit event. One record
+    # that cannot be deleted does not stop the others.
+    def destroy
+      digest = params[:manifest_digest]
+      raise AccessDenied, "INVALID_QUERY" unless digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/)
+      load_deletable(manifest_digest: digest)
+      raise AccessDenied if @deletable.empty?
+      runner = Operations::Runner.new
+      @outcomes = @deletable.map do |target|
+        code = begin
+          intent = runner.prepare(context: @context, resource: @resource, operation: :destroy, target_id: target.id, expected_version: target.expected_version)
+          runner.execute(context: @context, intent_ref: intent.id, input: {}, human_confirmed: true, origin: :ui).code
+        rescue AccessDenied => error
+          error.code
+        end
+        [ target, code ]
+      end
+      @deleted = @outcomes.count { |_, code| code == "OK" }
+      failed = @outcomes.reject { |_, code| code == "OK" }
+      if failed.empty? && @skipped.zero?
+        redirect_to list_return_path, status: :see_other, notice: t("rails_ai_admin.selections.destroy.done", count: @deleted)
+      else
+        @failed = failed
+        render :destroyed
+      end
+    end
+
+    private
+
+    def load_deletable(manifest_digest: nil)
+      records = {}
+      @selection = Selections::Builder.new.revalidate(context: @context, selection_ref: params[:selection_ref], manifest_digest: manifest_digest) do |record|
+        records[record.id.to_s] = record
+      end
+      @resource = RailsAiAdmin.registry.fetch(@selection.resource_key)
+      resolve_list_navigation
+      raise AccessDenied unless @resource.action_enabled?(:destroy)
+      access = Authorization::Access.new(@context, @resource)
+      @deletable = @selection.targets.select do |target|
+        access.authorize!(:destroy, records.fetch(target.id))
+      rescue AccessDenied
+        false
+      end
+      @skipped = @selection.targets.size - @deletable.size
+    end
+  end
+end

data/app/controllers/rails_ai_admin/surfaces_controller.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Admin-owned rails_tool_views endpoints (plan §6.3.1 shared mode). They use
+  # the public present/restore/dispatch/render API with an explicit admin Scope
+  # and never the host's global resolver, parent controller or agent adapter.
+  # rails_tool_views is referenced only inside actions, so conventional hosts
+  # can eager-load this file without loading the integration.
+  class SurfacesController < ApplicationController
+    ACT_FIELDS = %w[action_name base_revision idempotency_key source_component arguments].freeze
+    FORM_FURNITURE = %w[authenticity_token commit button].freeze
+
+    before_action :require_surfaces
+    around_action :bind_admin_context
+
+    # Native confirmation page -> persistent review Surface for the same intent.
+    def create
+      resource = RailsAiAdmin.registry.fetch(params[:resource])
+      definition = RailsAiAdmin.operation_registry.fetch(resource, params[:operation])
+      access = Authorization::Access.new(@context, resource)
+      record = access.find!(params[:id], action: definition.key)
+      surface = tool_views.present(context: @context, resource: resource, definition: definition, record: record,
+        intent_ref: params[:intent_ref], input: confirmed_input)
+      redirect_to admin_surface_path(surface_id: surface.id), status: :see_other
+    rescue AccessDenied => error
+      # An authorized actor with an expired, invalidated or input-mismatched
+      # intent gets the native conflict status, not anti-enumeration 404.
+      raise unless %w[APPROVAL_EXPIRED APPROVAL_INVALIDATED].include?(error.code)
+      admin_status(:conflict)
+    rescue ::RailsToolViews::Error => error
+      # The same intent was already presented with different input.
+      error.code == "IDEMPOTENCY_CONFLICT" ? admin_status(:conflict) : reject(error)
+    end
+
+    def show
+      @surface = ::RailsToolViews.restore(params[:surface_id], scope: admin_scope)
+      @surface_scope = admin_scope
+    rescue ::RailsToolViews::Error => error
+      reject(error)
+    end
+
+    def act
+      input = request.request_parameters.except(*FORM_FURNITURE)
+      raise AccessDenied, "INVALID_QUERY" unless (input.keys - ACT_FIELDS).empty?
+      revision = input["base_revision"]
+      raise AccessDenied, "INVALID_QUERY" unless revision.is_a?(String) && revision.match?(/\A[1-9][0-9]{0,9}\z/)
+      arguments = input.fetch("arguments", {})
+      raise AccessDenied, "INVALID_QUERY" unless arguments.is_a?(Hash)
+      result = ::RailsToolViews.dispatch(params[:surface_id], scope: admin_scope, action: input["action_name"],
+        arguments: arguments, base_revision: revision.to_i, idempotency_key: input["idempotency_key"],
+        source_component: input["source_component"])
+      respond_to do |format|
+        format.turbo_stream do
+          @surface = ::RailsToolViews.restore(result[:surface_id], scope: admin_scope)
+          @surface_scope = admin_scope
+          render turbo_stream: turbo_stream.replace(@surface.dom_id, helpers.admin_surface(@surface, scope: admin_scope))
+        end
+        format.html { redirect_to surface_return_path(result[:surface_id]), status: :see_other }
+      end
+    rescue ::RailsToolViews::Error => error
+      reject(error)
+    end
+
+    private
+
+    def tool_views
+      require "rails_ai_admin/integrations/tool_views"
+      Integrations::ToolViews
+    end
+
+    def require_surfaces
+      raise AccessDenied unless RailsAiAdmin.configuration.surfaces
+      tool_views.ensure_registered!
+    end
+
+    def bind_admin_context(&block)
+      tool_views.with_context(@context, &block)
+    end
+
+    def admin_scope = @admin_scope ||= tool_views.scope_for(@context)
+
+    # A review shown in a conversation returns there, so confirming or
+    # dismissing keeps the person in the chat (RAA-019).
+    def surface_return_path(surface_id)
+      reference = ::RailsToolViews::Surface.where(id: surface_id).pick(:context_ref)
+      chat_ref = reference.is_a?(String) && reference[/\Araa:chat:([0-9a-f-]{36})\z/, 1]
+      if chat_ref && RailsAiAdmin.configuration.assistant
+        require "rails_ai_admin/assistant"
+        chat = Assistant::Chat.owned(@context, chat_ref)
+        return assistant_conversation_path(chat_ref: chat.ref) if chat
+      end
+      admin_surface_path(surface_id: surface_id)
+    end
+
+    def confirmed_input
+      value = params[:confirmed_input]
+      raise AccessDenied, "INVALID_QUERY" unless value.is_a?(String) && value.bytesize <= Integrations::ToolViews::MAX_INPUT_BYTES
+      parsed = JSON.parse(value)
+      raise AccessDenied, "INVALID_QUERY" unless parsed.is_a?(Hash)
+      parsed
+    rescue JSON::ParserError
+      raise AccessDenied, "INVALID_QUERY"
+    end
+
+    # Unknown, foreign or unauthorized Surfaces all look missing. A stale
+    # revision or business-level rejection re-renders the saved Surface.
+    def reject(error)
+      case error.code
+      when "NOT_FOUND", "NOT_ALLOWED", "INVALID_SCOPE", "SURFACE_PURGED" then admin_status(:not_found)
+      when "CONFLICT", "IDEMPOTENCY_CONFLICT", "SURFACE_CLOSED", "OPERATION_FAILED", "RATE_LIMITED"
+        @surface = ::RailsToolViews.restore(params[:surface_id], scope: admin_scope)
+        @surface_scope = admin_scope
+        @surface_error = error
+        render :show, status: error.status
+      when "INCOMPATIBLE_COMPONENT" then admin_status(:unavailable)
+      else admin_status(:invalid_request)
+      end
+    rescue ::RailsToolViews::Error
+      admin_status(:not_found)
+    end
+  end
+end

data/app/helpers/rails_ai_admin/dashboard_helper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Inline SVG bars: no script and no inline style, so the admin CSP holds.
+  # The chart is decorative for assistive technology; the caption and the data
+  # table beside it carry the numbers.
+  module DashboardHelper
+    CHART_WIDTH = 600
+    CHART_HEIGHT = 120
+
+    def admin_trend_chart(trend)
+      count = trend.days.size
+      gap = 2.0
+      bar = (CHART_WIDTH - gap * (count - 1)) / count
+      bars = trend.days.each_with_index.map do |(_day, value), index|
+        height = value.zero? ? 0 : [ (value.fdiv(trend.max) * (CHART_HEIGHT - 4)).round(1), 2 ].max
+        tag.rect(x: (index * (bar + gap)).round(2), y: (CHART_HEIGHT - height).round(2), width: bar.round(2), height: height, rx: 1, class: "raa-bar")
+      end
+      baseline = tag.line(x1: 0, y1: CHART_HEIGHT - 0.5, x2: CHART_WIDTH, y2: CHART_HEIGHT - 0.5, class: "raa-axis")
+      content_tag(:svg, safe_join(bars + [ baseline ]), viewBox: "0 0 #{CHART_WIDTH} #{CHART_HEIGHT}", class: "raa-chart",
+        preserveAspectRatio: "none", focusable: "false", aria: { hidden: true })
+    end
+
+    def admin_number(value, capped)
+      capped ? t("rails_ai_admin.dashboard.more_than", number: number_with_delimiter(value)) : number_with_delimiter(value)
+    end
+  end
+end

data/app/helpers/rails_ai_admin/fields_helper.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module FieldsHelper
+    # Only receives the already-authorized scalar projection. Host partials are
+    # trusted Rails code, not a sandbox or an authorization mechanism.
+    # record_id names the record a file field links to; pages that show one
+    # record use @record.
+    def admin_field_value(field, value, view:, record_id: @record&.id)
+      value = String.new(value) if value.is_a?(String)
+      return admin_file_value(field, value, view: view, record_id: record_id) if field.scalar_type == :file && !field.plugin?
+      return admin_files_value(field, value, view: view, record_id: record_id) if field.scalar_type == :files
+      return admin_references_value(field, value) if field.scalar_type == :references
+      if field.scalar_type == :belongs_to
+        reference = value.nil? ? nil : admin_associations.reference(field, value)
+        return render(partial: "rails_ai_admin/fields/reference", locals: { field: field, value: value, reference: reference })
+      end
+      text = field.format(value, time_zone: @context.time_zone)
+      unless field.plugin? || value.nil?
+        # The readable text stays visible; the exact value is machine-readable,
+        # and long text keeps its line breaks (RAA-015).
+        if field.scalar_type == :datetime
+          text = tag.time(text, datetime: value.in_time_zone(@context.time_zone).iso8601)
+        elsif field.scalar_type == :date
+          text = tag.time(text, datetime: value.iso8601)
+        elsif field.scalar_type == :textarea && view != :index
+          text = tag.span(text, class: "raa-multiline")
+        elsif field.scalar_type == :email
+          text = mail_to(value.to_s, text)
+        elsif field.scalar_type == :url && field.web_address?(value.to_s)
+          # Only an absolute http(s) address becomes a link (never javascript:).
+          text = link_to(text, value.to_s, rel: "noopener noreferrer nofollow", target: "_blank")
+        elsif field.scalar_type == :json
+          text = view == :index ? text.squish.truncate(80) : tag.pre(text, class: "raa-json")
+        elsif field.scalar_type == :rich_text
+          # The stored HTML through Rails' safe list; lists show plain text.
+          text = view == :index ? text.squish.truncate(80) : tag.div(sanitize(value.to_s), class: "raa-rich-text")
+        end
+      end
+      partial = field.display_partial(view) || "rails_ai_admin/fields/#{view == :index ? 'index' : 'show'}"
+      render(partial: partial, locals: { field: field, value: value, text: text })
+    end
+
+    # Labels through each target's own grants; unavailable targets stay keys.
+    REFERENCES_SHOWN = 50
+    def admin_references_value(field, value)
+      ids = Array(value)
+      return "—" if ids.empty?
+      admin_associations.prime(field, ids.first(REFERENCES_SHOWN))
+      items = ids.first(REFERENCES_SHOWN).map do |id|
+        reference = admin_associations.reference(field, id)
+        reference.visible ? link_to(reference.label, resource_path(resource: reference.resource_key, id: reference.id)) : reference.label
+      end
+      items << t("rails_ai_admin.references.more", count: ids.size - REFERENCES_SHOWN) if ids.size > REFERENCES_SHOWN
+      safe_join(items, ", ")
+    end
+
+    # Checkboxes for the visible targets (up to 100). With more targets, the
+    # current ones stay as checkboxes and one key input, with the search
+    # picker, adds another. The empty hidden value lets "none" be submitted.
+    def admin_references_input(form, field, value, input_options)
+      selected = Array(value)
+      id = form.field_id(field.name)
+      name = "#{form.field_name(field.name)}[]"
+      choices = admin_associations.choices(field)
+      admin_associations.prime(field, selected)
+      options = if choices.complete
+        choices.options
+      else
+        selected.filter_map { |key| (reference = admin_associations.reference(field, key)).visible ? [ reference.label, key ] : nil }
+      end
+      boxes = options.map do |label, key|
+        box_id = "#{id}--#{key}"
+        tag.div(safe_join([ check_box_tag(name, key, selected.include?(key), id: box_id), " ", label_tag(box_id, label) ]), class: "raa-check")
+      end
+      parts = [ hidden_field_tag(name, "", id: nil), *boxes ]
+      parts << tag.p(t("rails_ai_admin.fields.none"), class: "raa-field-help") if options.empty? && choices.complete
+      unless choices.complete
+        target = Fields::Association.target(field)
+        key_input = text_field_tag(name, "", id: "#{id}--add", maxlength: 100, autocomplete: "off", spellcheck: false,
+          placeholder: t("rails_ai_admin.references.key_placeholder", target: target.label.singularize))
+        parts << admin_reference_picker(target, key_input, "#{id}--add", field, nil)
+      end
+      tag.div(safe_join(parts), id: id, class: "raa-references", role: "group", aria: { labelledby: "#{id}--label", describedby: input_options.dig(:aria, :describedby), invalid: input_options.dig(:aria, :invalid) })
+    end
+
+    # A file links to the admin's own download route, which checks the record
+    # and field grants again. Raster images also show a small inline preview.
+    def admin_file_value(field, value, view:, record_id:)
+      return "—" unless value.is_a?(Fields::FileValue)
+      text = field.format(value, time_zone: @context.time_zone)
+      return text unless record_id && @resource
+      path = resource_file_path(resource: @resource.key, id: record_id, field: field.name)
+      link = link_to(text, path)
+      return link unless view != :index && value.image?
+      safe_join([ tag.img(src: resource_file_path(resource: @resource.key, id: record_id, field: field.name, disposition: "inline"),
+        alt: value.filename, class: "raa-file-preview", loading: "lazy"), link ])
+    end
+
+    # Trix, from the host's Action Text assets, edits a hidden input. The
+    # label and descriptions point at the editor; file attachments are refused.
+    def admin_rich_text_input(form, field, value, input_options)
+      id = form.field_id(field.name)
+      editor = content_tag("trix-editor", "", id: id, input: "#{id}--value", class: "raa-rich-text-editor",
+        aria: input_options[:aria].merge(required: input_options[:required], labelledby: "#{id}--label"), data: { controller: "raa-rich-text",
+        action: "trix-file-accept->raa-rich-text#refuse trix-change->raa-rich-text#change" })
+      safe_join([ stylesheet_link_tag("trix"), javascript_include_tag("trix", defer: true),
+        hidden_field_tag(form.field_name(field.name), value, id: "#{id}--value"), editor ])
+    end
+
+    # Several files: a count in lists, a gallery of previews and links on
+    # show pages. Each link names its attachment.
+    def admin_files_value(field, value, view:, record_id:)
+      files = Array(value).grep(Fields::FileValue)
+      return field.format(files, time_zone: @context.time_zone) if view == :index || files.empty? || !(record_id && @resource)
+      items = files.map do |file|
+        path = resource_file_path(resource: @resource.key, id: record_id, field: field.name, attachment: file.id)
+        text = "#{file.filename} (#{number_to_human_size(file.byte_size)})"
+        preview = file.image? ? tag.img(src: resource_file_path(resource: @resource.key, id: record_id, field: field.name, attachment: file.id, disposition: "inline"), alt: file.filename, class: "raa-file-preview", loading: "lazy") : nil
+        tag.li(safe_join([ preview, link_to(text, path) ].compact))
+      end
+      tag.ul(safe_join(items), class: "raa-file-list")
+    end
+
+    # Current files with remove boxes, then a multiple file chooser.
+    def admin_files_input(form, field, value, input_options)
+      id = form.field_id(field.name)
+      current = Array(value).grep(Fields::FileValue)
+      boxes = current.map do |file|
+        box_id = "#{id}--remove-#{file.id}"
+        tag.li(safe_join([ check_box_tag("remove_attachments[#{field.name}][]", file.id, false, id: box_id), " ",
+          label_tag(box_id, t("rails_ai_admin.files.remove_named", file: file.filename)) ]), class: "raa-check")
+      end
+      options = input_options.merge(multiple: true, required: nil)
+      options[:accept] = field.options[:accept].join(",") if field.options[:accept]
+      safe_join([ (tag.ul(safe_join(boxes), class: "raa-file-list") if boxes.any?), form.file_field(field.name, **options),
+        tag.p(t("rails_ai_admin.files.list_limit", size: number_to_human_size(field.options[:max_size]), count: field.options[:max_files]), class: "raa-field-help") ].compact)
+    end
+
+    # Current file, a file chooser and (when the field may be empty) a remove box.
+    def admin_file_input(form, field, value, input_options)
+      current = value.is_a?(Fields::FileValue) ? value : nil
+      parts = []
+      if current
+        parts << tag.p(t("rails_ai_admin.files.current", file: field.format(current, time_zone: @context.time_zone)), class: "raa-file-current")
+      end
+      options = input_options.merge(required: current ? nil : input_options[:required])
+      options[:accept] = field.options[:accept].join(",") if field.options[:accept]
+      parts << form.file_field(field.name, **options)
+      parts << tag.p(t("rails_ai_admin.files.limit", size: number_to_human_size(field.options[:max_size])), class: "raa-field-help")
+      if current && !admin_field_required?(field)
+        id = "#{form.field_id(field.name)}--remove"
+        parts << tag.p(safe_join([ check_box_tag("remove_files[]", field.name.to_s, false, id: id), " ", label_tag(id, t("rails_ai_admin.files.remove")) ]), class: "raa-file-remove")
+      end
+      safe_join(parts)
+    end
+
+    # A bounded picker of currently visible targets. A stored key the actor
+    # cannot see stays selected so saving other fields never clears it; past
+    # MAX_CHOICES (or without a target list grant) the form takes a typed key.
+    def admin_reference_input(form, field, value, input_options)
+      value = value.nil? ? nil : String.new(value.to_s)
+      choices = admin_associations.choices(field)
+      unless choices.complete
+        target = Fields::Association.target(field)
+        key_input = form.text_field(field.name, value: value, maxlength: 100, autocomplete: "off", spellcheck: false,
+          placeholder: t("rails_ai_admin.references.key_placeholder", target: target.label.singularize), **input_options)
+        return admin_reference_picker(target, key_input, form.field_id(field.name), field, value)
+      end
+      options = choices.options.map(&:dup)
+      if value.present? && options.none? { |_, key| key == value }
+        options.unshift([ t("rails_ai_admin.references.not_available", label: admin_associations.reference(field, value).label), value ])
+      end
+      form.select(field.name, options, { selected: value, include_blank: field.options[:nullable] ? t("rails_ai_admin.fields.none") : t("rails_ai_admin.fields.choose_record") }, input_options)
+    end
+
+    # The typed key input, plus a search box when the actor can list the
+    # target (the search endpoint applies the same grants again).
+    def admin_reference_picker(target, key_input, key_id, field, value)
+      return key_input unless allowed_action?(target, :index)
+      current = value.present? ? admin_associations.reference(field, value) : nil
+      render(partial: "rails_ai_admin/fields/reference_picker",
+        locals: { target: target, key_input: key_input, key_id: key_id, current: current&.visible ? current : nil })
+    end
+
+    # Untranslated templates for the picker script; it fills %{count} and %{label}.
+    def admin_reference_messages
+      results = t("rails_ai_admin.references.results")
+      { searching: t("rails_ai_admin.references.searching"), none: t("rails_ai_admin.references.none"),
+        failed: t("rails_ai_admin.references.failed"), one: results[:one], other: results[:other],
+        chosen: t("rails_ai_admin.references.chosen") }
+    end
+
+    # Says how the box matches, so "Love" not finding "Ada Lovelace" under
+    # prefix search is not a surprise (RAA-021).
+    def admin_search_placeholder(fields)
+      modes = fields.map { |field| field.options[:searchable] == true ? :prefix : field.options[:searchable] }.uniq
+      case modes
+      when [ :prefix ] then t("rails_ai_admin.search.prefix")
+      when [ :contains ] then t("rails_ai_admin.search.contains")
+      when [ :exact ] then t("rails_ai_admin.search.exact")
+      else t("rails_ai_admin.search.any")
+      end
+    end
+
+    # The same rule as blank-input coercion: required or not nullable (RAA-023).
+    # An edit form's empty password box keeps the current password.
+    def admin_field_required?(field)
+      return field.options[:required] == true && @operation != :update if field.scalar_type == :password
+      field.options[:required] == true || field.options[:nullable] == false
+    end
+
+    def admin_time_input_value(field, value)
+      return value if value.nil? || value.is_a?(String) && !value.match?(Field::TIME_OF_DAY)
+      field.format_time_of_day(value)
+    end
+
+    # Submitted text comes back as typed; a stored value is indented.
+    def admin_json_input_value(value)
+      return value if value.nil? || value.is_a?(String)
+      JSON.pretty_generate(value)
+    rescue JSON::GeneratorError
+      nil
+    end
+
+    # datetime-local value in the context zone. Seconds are kept when set so
+    # an unchanged form submits the stored second back.
+    def admin_datetime_input_value(value)
+      return value unless value.respond_to?(:in_time_zone)
+      local = value.in_time_zone(@context.time_zone)
+      local.strftime(local.sec.zero? ? "%Y-%m-%dT%H:%M" : "%Y-%m-%dT%H:%M:%S")
+    end
+
+    def admin_field_choices(field, value)
+      choices = field.choice_options.map(&:dup)
+      if value.present? && !field.choice_values.include?(value)
+        choices.unshift([ t("rails_ai_admin.fields.unavailable_value"), String.new(value.to_s), { disabled: true } ])
+      end
+      choices
+    end
+  end
+end

data/app/helpers/rails_ai_admin/filters_helper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Native inputs for already-granted typed filters. Values are the normalized
+  # list hint strings; the server coerces them again before querying.
+  module FiltersHelper
+    def admin_filter_label(field, operator)
+      case operator.to_sym
+      when :gte then t("rails_ai_admin.filters.from", label: field.label)
+      when :lte then t("rails_ai_admin.filters.to", label: field.label)
+      else Field::RANGE_TYPES.include?(field.scalar_type) ? t("rails_ai_admin.filters.equals", label: field.label) : field.label
+      end
+    end
+
+    def admin_filter_input(field, operator, value, id:)
+      name = "filter[#{field.name}][#{operator}]"
+      value = value && String.new(value)
+      case field.scalar_type
+      when :belongs_to
+        choices = admin_associations.choices(field)
+        unless choices.complete
+          key_input = text_field_tag(name, value, id: id, maxlength: 100, autocomplete: "off", spellcheck: false)
+          return admin_reference_picker(Fields::Association.target(field), key_input, id, field, value)
+        end
+        options = [ [ t("rails_ai_admin.filters.any"), "" ] ] + choices.options.map(&:dup)
+        options << [ admin_associations.reference(field, value).label, value ] if value.present? && options.none? { |_, key| key == value }
+        select_tag(name, options_for_select(options, value), id: id)
+      when :enum, :select
+        select_tag(name, options_for_select([ [ t("rails_ai_admin.filters.any"), "" ] ] + field.choice_options.map(&:dup), value), id: id)
+      when :boolean
+        select_tag(name, options_for_select([ [ t("rails_ai_admin.filters.any"), "" ], [ t("rails_ai_admin.fields.yes"), "true" ], [ t("rails_ai_admin.fields.no"), "false" ] ], value), id: id)
+      when :integer then number_field_tag(name, value, id: id, step: 1)
+      when :decimal then text_field_tag(name, value, id: id, inputmode: "decimal", maxlength: 200)
+      when :date then date_field_tag(name, value, id: id)
+      when :datetime then datetime_local_field_tag(name, value, id: id)
+      else text_field_tag(name, value, id: id, maxlength: 200)
+      end
+    end
+  end
+end

data/app/helpers/rails_ai_admin/history_helper.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module HistoryHelper
+    def admin_history_allowed?(resource, record)
+      Authorization::Access.new(@context, resource).authorize_history!(record)
+    rescue AccessDenied
+      false
+    end
+
+    def admin_history_time(time)
+      local = time.in_time_zone(@context.time_zone)
+      tag.time(local.strftime("%-d %b %Y %H:%M:%S %Z"), datetime: local.iso8601)
+    end
+
+    # "Updated", "Created", "Deleted" or a custom operation's description,
+    # plus the outcome when the change was not saved.
+    def admin_history_change(resource, entry)
+      name = if %w[create update destroy export].include?(entry.operation)
+        t(entry.operation, scope: %i[rails_ai_admin history operations])
+      else
+        RailsAiAdmin.operation_registry.custom(resource).find { |definition| definition.key.to_s == entry.operation }&.description ||
+          entry.operation.to_s.humanize
+      end
+      return name if entry.status == "succeeded"
+      safe_join([ name, tag.br, tag.span(t("rails_ai_admin.history.not_saved"), class: "raa-danger"), " ", admin_outcome(entry.code) ])
+    end
+
+    def admin_history_fields(entry)
+      return "—" if entry.fields.empty? && entry.hidden_fields.zero?
+      parts = [ entry.fields.join(", ") ]
+      parts << t("rails_ai_admin.history.other_fields", count: entry.hidden_fields) if entry.hidden_fields.positive?
+      parts.reject(&:blank?).join("; ")
+    end
+  end
+end

data/app/helpers/rails_ai_admin/navigation_helper.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Original project-owned outline glyphs, with fixed SVG attributes and paths.
+  module NavigationHelper
+    # Page title parts, most specific first (RAA-024). The first call wins, so
+    # a page rendered inside another keeps the outer page's title.
+    def admin_title(*parts)
+      @raa_title_parts ||= parts.compact.map { |part| part.to_s.squish.truncate(80) }.reject(&:empty?)
+      nil
+    end
+
+    # A result code as a sentence, with the code kept as secondary text for
+    # support (RAA-027).
+    def admin_outcome(code)
+      return "" if code.blank?
+      safe_join([ Presentation::Outcomes.sentence(code), " ", tag.span("(#{code})", class: "raa-code") ])
+    end
+
+    # A stored run, item or work status ("succeeded") as display text.
+    def admin_state_name(status)
+      status = status.to_s
+      return status.humanize unless status.match?(/\A[a-z][a-z_]{0,63}\z/)
+      t(status, scope: %i[rails_ai_admin states], default: status.humanize)
+    end
+
+    # { "succeeded" => 2, "failed" => 1 } as "Succeeded: 2 · Failed: 1".
+    def admin_state_counts(counts)
+      counts.map { |status, count| t("rails_ai_admin.states.count", state: admin_state_name(status), count: count) }.join(" · ")
+    end
+
+    # "Edit ORD-0001 · Orders · Administration".
+    def admin_page_title
+      [ *Array(@raa_title_parts), RailsAiAdmin.configuration.title ].join(" · ")
+    end
+
+    ICON_PATHS = {
+      "users" => [ "M9 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8Z", "M2 21v-3a6 6 0 0 1 12 0v3M17 4a4 4 0 0 1 0 8M18 15a5 5 0 0 1 4 5v1" ],
+      "shopping-bag" => [ "M4 7h16l1 14H3L4 7ZM8 8V6a4 4 0 0 1 8 0v2" ],
+      "life-buoy" => [ "M22 12a10 10 0 1 1-20 0 10 10 0 0 1 20 0ZM16 12a4 4 0 1 1-8 0 4 4 0 0 1 8 0Z", "m5 5 4 4m6 6 4 4M5 19l4-4m6-6 4-4" ],
+      "document" => [ "M5 2h9l5 5v15H5V2ZM14 2v6h5M8 12h8M8 16h8" ],
+      "grid" => [ "M3 3h7v7H3V3Zm11 0h7v7h-7V3ZM3 14h7v7H3v-7Zm11 0h7v7h-7v-7Z" ]
+    }.transform_values { |paths| paths.each(&:freeze).freeze }.freeze
+
+    def navigation_icon(name)
+      return unless name
+      paths = ICON_PATHS.fetch(name) { raise ConfigurationError, "Unknown navigation icon" }
+      tag.svg(class: "raa-nav-icon", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor",
+        "stroke-width": "1.7", "stroke-linecap": "round", "stroke-linejoin": "round", "aria-hidden": "true", focusable: "false") do
+        safe_join(paths.map { |path| tag.path(d: path) })
+      end
+    end
+  end
+end

data/app/helpers/rails_ai_admin/tool_views_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # View helpers for admin-owned review Surfaces. rails_tool_views is touched
+  # only when a Surface is actually rendered, never when this file loads.
+  module ToolViewsHelper
+    # Renders through RailsToolViews.render with fresh authorization. The
+    # rails_tool_views view helpers are added to this view instance only.
+    def admin_surface(surface, scope:, error: nil)
+      extend ::RailsToolViews::SurfacesHelper unless is_a?(::RailsToolViews::SurfacesHelper)
+      ::RailsToolViews.render(surface, view_context: self, scope: scope, error: error)
+    end
+
+    # A Surface referenced from a conversation, restored for the current admin.
+    def admin_assistant_surface(surface_id, scope:)
+      surface = ::RailsToolViews.restore(surface_id, scope: scope)
+      admin_surface(surface, scope: scope)
+    rescue ::RailsToolViews::Error
+      tag.p(t("rails_ai_admin.surfaces.no_longer_available"), class: "raa-chat-activity")
+    end
+
+    # Like rails_tool_views_action_form, but posts to the admin endpoint so the
+    # host's global resolver never authenticates admin actions.
+    def admin_surface_action_form(surface, action, **options, &block)
+      fields = rails_tool_views_action_fields(surface, action)
+      form_with(url: admin_surface_actions_path(surface_id: surface.id), method: :post, scope: :arguments, namespace: surface.dom_id, **options) do |form|
+        safe_join([ fields, (capture(form, &block) if block) ])
+      end
+    end
+
+    # The current authorized review behind a Surface, or nil.
+    def admin_surface_review(props)
+      Integrations::ToolViews.review(Integrations::ToolViews.current_context, props)
+    end
+
+    def admin_surface_changes(review, wire)
+      Integrations::ToolViews.proposed_changes(review, wire)
+    end
+
+    def admin_surface_display_values(review, wire)
+      Integrations::ToolViews.display_values(review, wire)
+    end
+
+    def admin_surface_review_available?(resource, definition)
+      RailsAiAdmin.configuration.surfaces && resource.surface_operation?(definition.key)
+    end
+  end
+end