rails_ai_admin 0.1.0

data/lib/rails_ai_admin/presentation/csv_import.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Presentation
+    # Creates records from a CSV file, one row at a time through the native
+    # create operation: each row has its own policy check, coercion, model
+    # validation, transaction and audit event. A check run validates the
+    # values without writing anything.
+    class CsvImport
+      MAX_BYTES = 2 * 1024 * 1024
+      # Types a CSV cell can carry. Files, passwords and lists are left out.
+      TYPES = %i[text textarea integer decimal boolean date datetime time enum select email url json belongs_to rich_text].freeze
+      TRUE_WORDS = %w[true yes y 1].freeze
+      FALSE_WORDS = %w[false no n 0].freeze
+      RowResult = Data.define(:number, :code, :errors, :record_id)
+      Report = Data.define(:columns, :ignored, :rows, :checked) do
+        def created = rows.count { |row| row.code == "OK" && row.record_id }
+        def valid = rows.count { |row| row.code == "OK" }
+        def failed = rows.reject { |row| row.code == "OK" }
+      end
+
+      class Invalid < StandardError; end
+
+      def initialize(context, resource, limit: RailsAiAdmin.configuration.import_limit)
+        @context, @resource, @limit = context, resource, limit
+        @access = Authorization::Access.new(context, resource)
+      end
+
+      # Fields a file may fill: writable on create and representable as text.
+      def fields
+        @fields ||= @access.fields(:write, @access.relation.new, operation: :create).select { |field| TYPES.include?(field.scalar_type) && !field.plugin? }
+      end
+
+      def template = "#{fields.map { |field| %("#{field.label.gsub('"', '""')}") }.join(',')}\r\n"
+
+      def call(text, write:)
+        @access.authorize_import!
+        raise Invalid, I18n.t("rails_ai_admin.imports.too_large") if text.bytesize > MAX_BYTES
+        rows = parse(text.dup.force_encoding(Encoding::UTF_8).delete_prefix(""))
+        header = rows.shift
+        raise Invalid, I18n.t("rails_ai_admin.imports.empty") if header.nil? || rows.empty?
+        raise Invalid, I18n.t("rails_ai_admin.imports.too_many", limit: @limit) if rows.size > @limit
+        mapping = map_columns(header)
+        raise Invalid, I18n.t("rails_ai_admin.imports.no_columns") if mapping.empty?
+        runner = Operations::Runner.new
+        results = rows.each_with_index.map do |cells, index|
+          input = mapping.each_with_object({}) do |(position, field), values|
+            cell = cells[position].to_s
+            values[field.name.to_s] = normalize(field, cell) unless cell.strip.empty?
+          end
+          run_row(runner, index + 2, input, write)
+        end
+        ignored = header.each_with_index.reject { |_, position| mapping.key?(position) }.map(&:first).reject(&:blank?)
+        Report.new(mapping.values.map(&:label), ignored, results, !write)
+      end
+
+      private
+
+      def run_row(runner, number, input, write)
+        if write
+          intent = runner.prepare(context: @context, resource: @resource, operation: :create)
+          result = runner.execute(context: @context, intent_ref: intent.id, input: input, human_confirmed: true, origin: :ui)
+          RowResult.new(number, result.code, result.errors || {}, result.success? ? result.record_id : nil)
+        else
+          result = runner.preview(context: @context, resource: @resource, operation: :create, input: input)
+          result.is_a?(Operations::Result) ? RowResult.new(number, result.code, result.errors || {}, nil) : RowResult.new(number, "OK", {}, nil)
+        end
+      rescue AccessDenied => error
+        RowResult.new(number, error.code, {}, nil)
+      end
+
+      # Header cells match a field's label or name, ignoring case and spaces.
+      def map_columns(header)
+        names = fields.flat_map { |field| [ [ key(field.label), field ], [ key(field.name.to_s), field ] ] }.to_h
+        used = {}
+        header.each_with_index.each_with_object({}) do |(cell, position), mapping|
+          field = names[key(cell.to_s)]
+          next unless field && !used[field.name]
+          used[field.name] = true
+          mapping[position] = field
+        end
+      end
+
+      def key(text) = text.to_s.unicode_normalize(:nfkc).downcase.gsub(/[\s_]+/, " ").strip
+
+      # Export writes readable text; import reads it back where that is exact.
+      def normalize(field, cell)
+        case field.scalar_type
+        when :boolean
+          word = cell.strip.downcase
+          localized = { I18n.t("rails_ai_admin.fields.yes").downcase => "true", I18n.t("rails_ai_admin.fields.no").downcase => "false" }
+          return localized[word] if localized.key?(word)
+          TRUE_WORDS.include?(word) ? "true" : FALSE_WORDS.include?(word) ? "false" : cell
+        when :select then field.choice_options.find { |label, _| label == cell }&.last || cell
+        when :integer, :decimal, :date, :datetime, :time, :belongs_to then cell.strip
+        else cell
+        end
+      end
+
+      # RFC 4180: quoted cells may hold commas, quotes ("") and line breaks.
+      def parse(text)
+        raise Invalid, I18n.t("rails_ai_admin.imports.not_utf8") unless text.valid_encoding?
+        rows, row, cell = [], [], +""
+        quoted = false
+        index = 0
+        while index < text.length
+          char = text[index]
+          if quoted
+            if char == '"'
+              if text[index + 1] == '"'
+                cell << '"'
+                index += 1
+              else
+                quoted = false
+              end
+            else
+              cell << char
+            end
+          elsif char == '"' && cell.empty?
+            quoted = true
+          elsif char == ","
+            row << cell
+            cell = +""
+          elsif char == "\n" || char == "\r"
+            index += 1 if char == "\r" && text[index + 1] == "\n"
+            row << cell
+            rows << row unless row.all?(&:empty?)
+            row, cell = [], +""
+            raise Invalid, I18n.t("rails_ai_admin.imports.too_many", limit: @limit) if rows.size > @limit + 1
+          else
+            cell << char
+          end
+          index += 1
+        end
+        raise Invalid, I18n.t("rails_ai_admin.imports.unclosed_quote") if quoted
+        row << cell
+        rows << row unless row.all?(&:empty?)
+        rows
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/presentation/dashboard.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Presentation
+    # Declared overview widgets: counts over a granted list tab and daily
+    # trends over a readable date field. Every number comes from the
+    # resource's policy relation; nothing is cached across requests.
+    module Dashboard
+      MAX_WIDGETS = 8
+      MAX_DAYS = 90
+      # A trend reads at most this many timestamps.
+      TREND_LIMIT = 50_000
+      Metric = Data.define(:name, :scope, :label)
+      Trend = Data.define(:name, :field, :days, :label)
+      MetricValue = Data.define(:label, :count, :capped, :scope)
+      TrendValue = Data.define(:label, :days, :capped) do
+        def max = [ days.map(&:last).max.to_i, 1 ].max
+        def total = days.sum(&:last)
+      end
+      Section = Data.define(:resource, :metrics, :trends)
+
+      # Collects a resource's dashboard declarations.
+      class Builder
+        attr_reader :widgets
+
+        def initialize = @widgets = []
+
+        def metric(name, scope: nil, label: nil)
+          add(Metric.new(stable(name), scope && stable(scope), text(label)))
+        end
+
+        def trend(field, days: 30, label: nil)
+          raise ConfigurationError, "trend days must be 7..#{MAX_DAYS}" unless days.is_a?(Integer) && days.between?(7, MAX_DAYS)
+          add(Trend.new(stable(field), stable(field), days, text(label)))
+        end
+
+        private
+
+        def add(widget)
+          raise ConfigurationError, "A dashboard declares at most #{MAX_WIDGETS} widgets" if @widgets.size >= MAX_WIDGETS
+          raise ConfigurationError, "Duplicate dashboard widget #{widget.name}" if @widgets.any? { |entry| entry.class == widget.class && entry.name == widget.name }
+          @widgets << widget.freeze
+        end
+
+        def stable(name)
+          raise ConfigurationError, "Dashboard names must be stable identifiers" unless (name.is_a?(Symbol) || name.is_a?(String)) && name.to_s.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+          name.to_sym
+        end
+
+        def text(label)
+          return if label.nil?
+          raise ConfigurationError, "Dashboard labels must be short plain text" unless label.is_a?(String) && label.valid_encoding? && label.length.between?(1, 80)
+          label.dup.freeze
+        end
+      end
+
+      class << self
+        def validate!(resource)
+          resource.dashboard.each do |widget|
+            case widget
+            when Metric
+              if widget.scope && resource.scopes.none? { |definition| definition.name == widget.scope }
+                raise ConfigurationError, "dashboard metric #{widget.name} names undeclared list tab #{widget.scope}"
+              end
+            when Trend
+              field = resource.fields.find { |candidate| candidate.name == widget.field }
+              unless field && %i[date datetime].include?(field.scalar_type) && !field.virtual? && !field.plugin?
+                raise ConfigurationError, "dashboard trend #{widget.field} must name a declared date or datetime field"
+              end
+            end
+          end
+        end
+
+        # One section per menu resource with widgets the actor may see now.
+        def build(context, resources)
+          resources.filter_map do |resource|
+            next if resource.dashboard.empty?
+            access = Authorization::Access.new(context, resource)
+            access.authorize!(:index)
+            metrics = resource.dashboard.grep(Metric).filter_map { |widget| metric(access, widget) }
+            trends = resource.dashboard.grep(Trend).filter_map { |widget| trend(access, widget) }
+            Section.new(resource, metrics.freeze, trends.freeze) if metrics.any? || trends.any?
+          rescue AccessDenied
+            nil
+          end
+        end
+
+        private
+
+        def metric(access, widget)
+          relation = access.relation
+          if widget.scope
+            named = access.named_scopes.find { |definition| definition.name == widget.scope }
+            return unless named
+            relation = named.apply(relation)
+          end
+          total = relation.except(:order).limit(List::COUNT_LIMIT + 1).count
+          label = widget.label || (named ? "#{access.resource.label}: #{named.label}" : access.resource.label)
+          MetricValue.new(label, [ total, List::COUNT_LIMIT ].min, total > List::COUNT_LIMIT, named&.name&.to_s)
+        end
+
+        # Counts per day in the context's time zone for the last days.
+        def trend(access, widget)
+          field = access.fields(:read).find { |candidate| candidate.name == widget.field }
+          return unless field
+          zone = ActiveSupport::TimeZone[access.context.time_zone]
+          today = zone.today
+          first = today - (widget.days - 1)
+          start = field.scalar_type == :date ? first : zone.local(first.year, first.month, first.day)
+          column = access.resource.model_class.arel_table[field.column]
+          values = access.relation.where(column.gteq(start)).reorder(nil).limit(TREND_LIMIT + 1).pluck(field.column)
+          counts = Hash.new(0)
+          values.first(TREND_LIMIT).compact.each { |value| counts[value.respond_to?(:in_time_zone) && !value.is_a?(Date) ? value.in_time_zone(zone).to_date : value.to_date] += 1 }
+          days = (first..today).map { |day| [ day, counts[day] ] }
+          TrendValue.new(widget.label || "#{access.resource.label} by #{field.label.downcase_first}", days.freeze, values.size > TREND_LIMIT)
+        end
+      end
+
+      List = Queries::List
+    end
+  end
+end

data/lib/rails_ai_admin/presentation/history.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Presentation
+    # One record's audit trail for its history page. It reads only the
+    # current tenant's events for this resource and record, and names only
+    # fields the actor may currently read or write.
+    class History
+      PAGE_SIZE = 50
+      Entry = Data.define(:id, :at, :operation, :status, :code, :origin, :actor_ref, :fields, :hidden_fields)
+      Page = Data.define(:entries, :older)
+
+      def initialize(access, record)
+        @access, @record = access, record
+        access.authorize_history!(record)
+      end
+
+      # before: the id of the oldest entry already shown (canonical integer text).
+      def page(before: nil)
+        unless before.nil? || before.is_a?(String) && before.match?(/\A[1-9][0-9]{0,18}\z/)
+          raise AccessDenied, "INVALID_QUERY"
+        end
+        scope = AuditEvent.where(tenant_ref: @access.context.tenant_ref, resource_key: @access.resource.key.to_s, record_id: @record.id.to_s)
+        scope = scope.where(AuditEvent.arel_table[:id].lt(Integer(before, 10))) if before
+        events = scope.order(id: :desc).limit(PAGE_SIZE + 1).to_a
+        labels = visible_labels
+        entries = events.first(PAGE_SIZE).map do |event|
+          names = Array(event.changed_fields).grep(String)
+          shown = names.filter_map { |name| labels[name] }
+          Entry.new(event.id, event.created_at, event.operation, event.status, event.code, event.origin,
+            event.actor_ref, shown.freeze, names.size - shown.size)
+        end
+        Page.new(entries.freeze, events.size > PAGE_SIZE ? entries.last.id : nil)
+      end
+
+      private
+
+      def visible_labels
+        fields = @access.fields(:read, @record) | @access.fields(:write, @record, operation: :update)
+        fields.to_h { |field| [ field.name.to_s, field.label ] }
+      rescue AccessDenied
+        {}
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/presentation/index_settings.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Presentation
+    # Static index table presentation. Columns and the default sort only narrow
+    # or order what current read/sort grants already allow; nothing here grants.
+    class IndexSettings < Data.define(:columns, :default_sort, :default_direction, :page_size, :count)
+      MAX_COLUMNS = 50
+      MAX_PAGE_SIZE = 100
+      COUNT_STRATEGIES = %i[none exact].freeze
+      # Exact counts stop here so a large table never needs a full COUNT(*).
+      COUNT_LIMIT = 10_000
+      # Short machine-formatted values (IDs, numbers, ISO dates) stay on one line
+      # in index cells; hyphens in dates are otherwise legal break points.
+      COMPACT_TYPES = %i[id integer decimal date datetime boolean time].freeze
+
+      def initialize(columns: nil, default_sort: nil, default_direction: "asc", page_size: 25, count: :none)
+        unless columns.nil? || columns.is_a?(Array) && columns.size.between?(1, MAX_COLUMNS) && columns.all? { |name| name.is_a?(Symbol) } && columns.uniq.size == columns.size
+          raise ConfigurationError, "Index columns must be 1 to #{MAX_COLUMNS} distinct field-name symbols"
+        end
+        raise ConfigurationError, "Index default sort must be a field-name symbol" unless default_sort.nil? || default_sort.is_a?(Symbol)
+        raise ConfigurationError, "Index default direction must be asc or desc" unless %w[asc desc].include?(default_direction)
+        raise ConfigurationError, "Index page size must be an integer from 1 to #{MAX_PAGE_SIZE}" unless page_size.is_a?(Integer) && page_size.between?(1, MAX_PAGE_SIZE)
+        raise ConfigurationError, "Index count must be :none or :exact" unless COUNT_STRATEGIES.include?(count)
+        super(columns: columns&.dup&.freeze, default_sort: default_sort, default_direction: String.new(default_direction).freeze, page_size: page_size, count: count)
+      end
+
+      # Checks references against the resource's declarations at registration.
+      def validate!(fields)
+        by_name = fields.index_by(&:name)
+        Array(columns).each do |name|
+          field = by_name[name]
+          unless field && !field.hidden? && field.options[:index]
+            raise ConfigurationError, "Index column #{name} must be a declared field visible on index"
+          end
+        end
+        if default_sort
+          field = by_name[default_sort]
+          raise ConfigurationError, "Index default sort #{default_sort} must be a declared sortable field" unless field && !field.hidden? && !field.virtual? && field.options[:sortable]
+        end
+        self
+      end
+
+      # Orders already-authorized index fields; unlisted fields are omitted.
+      def order(fields)
+        return fields unless columns
+        by_name = fields.index_by(&:name)
+        columns.filter_map { |name| by_name[name] }
+      end
+    end
+
+    # Collects index settings without consulting the database at boot.
+    class IndexBuilder
+      attr_reader :options
+
+      def initialize
+        @options = {}
+      end
+
+      def columns(*names) = set(:columns, names.flatten)
+      def page_size(value) = set(:page_size, value)
+      def count(value) = set(:count, value)
+
+      def default_sort(name, direction = :asc)
+        set(:default_sort, name)
+        @options[:default_direction] = direction.to_s
+      end
+
+      private
+
+      def set(key, value)
+        raise ConfigurationError, "Index #{key} is declared twice" if @options.key?(key)
+        @options[key] = value
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/presentation/outcomes.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Presentation
+    # One table from stable result codes to the sentence a person reads
+    # (RAA-027). The code stays available as secondary text for support, but no
+    # page should show a bare code as its explanation.
+    module Outcomes
+      SENTENCES = {
+        "OK" => "Done.",
+        "VALIDATION_FAILED" => "Some values need attention.",
+        "CONFLICT" => "The record changed after this page was opened.",
+        "RESTRICTED" => "The record is still in use and cannot be deleted.",
+        "NOT_FOUND" => "The record is not available.",
+        "UNAUTHENTICATED" => "Sign in to continue.",
+        "INVALID_QUERY" => "The list settings are not available.",
+        "APPROVAL_REQUIRED" => "This change needs your explicit confirmation.",
+        "APPROVAL_EXPIRED" => "This form expired before it was submitted.",
+        "APPROVAL_INVALIDATED" => "Your access or the operation changed after this form was opened.",
+        "IDEMPOTENCY_CONFLICT" => "This form was already submitted with different values.",
+        "AUTHORIZATION_REVOKED" => "Your access changed before the work ran.",
+        "SELECTION_INVALIDATED" => "The selection no longer matches the records.",
+        "SELECTION_EXPIRED" => "The selection expired.",
+        "TIMEOUT" => "The operation took too long and was stopped.",
+        "OPERATION_FAILED" => "The operation failed.",
+        "POST_COMMIT_CALLBACK_FAILED" => "The change was saved, but a follow-up step failed.",
+        "OUTCOME_UNKNOWN" => "The result could not be confirmed.",
+        "ATTEMPTS_EXHAUSTED" => "The work failed after several attempts.",
+        "CANCELLED" => "The work was cancelled.",
+        "EXECUTION_EXPIRED" => "The work expired before it could run.",
+        "WORK_EXPIRED" => "The work expired before it could run.",
+        "HANDLER_CHANGED" => "The operation changed after the work was queued.",
+        "UNAVAILABLE" => "This is not available right now."
+      }.freeze
+
+      # Translatable under rails_ai_admin.outcomes; English is the fallback.
+      def self.sentence(code)
+        fallback = SENTENCES.fetch(code.to_s) { "The request could not be completed." }
+        return fallback unless code.to_s.match?(/\A[A-Z][A-Z_]{1,63}\z/)
+        I18n.t(code.to_s.downcase, scope: %i[rails_ai_admin outcomes], default: fallback)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/presentation/status.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Presentation
+    # Fixed public status text. Exceptions, params and record values are not inputs.
+    class Status < Data.define(:kind, :http_status, :code, :title, :message)
+      DEFINITIONS = {
+        "authentication_required" => [ 401, "UNAUTHENTICATED", "Authentication required", "Sign in through the host application to continue." ].freeze,
+        "forbidden" => [ 403, "FORBIDDEN", "Access unavailable", "Your current permissions do not allow this page." ].freeze,
+        "not_found" => [ 404, "NOT_FOUND", "Not found", "This page or record is not available under your current access." ].freeze,
+        "conflict" => [ 409, "CONFLICT", "The request has changed", "Review the current records and permissions before preparing a fresh request." ].freeze,
+        "invalid_query" => [ 422, "INVALID_QUERY", "Invalid query", "Open a fresh list and use the available search, sort and page settings." ].freeze,
+        "invalid_request" => [ 422, "INVALID_REQUEST", "Invalid request", "Your session or request could not be verified. Sign in and review a fresh form before submitting." ].freeze,
+        "unavailable" => [ 503, "UNAVAILABLE", "Administration unavailable", "Administration is not configured safely. Contact the host maintainer." ].freeze,
+        "error" => [ 500, "ERROR", "The request needs review", "Check current records or existing operation results before retrying. A prior write may have completed." ].freeze
+      }.freeze
+
+      def self.fetch(kind)
+        raise ConfigurationError, "Unknown status kind" unless kind.is_a?(String) || kind.is_a?(Symbol)
+        key = kind.to_s
+        http_status, code, title, message = DEFINITIONS.fetch(key) { raise ConfigurationError, "Unknown status kind" }
+        # The English text is the fallback, so a missing translation never
+        # breaks the page that reports another failure.
+        title = I18n.t(:title, scope: [ :rails_ai_admin, :statuses, key ], default: title).to_s.freeze
+        message = I18n.t(:message, scope: [ :rails_ai_admin, :statuses, key ], default: message).to_s.freeze
+        new(String.new(key).freeze, http_status, code, title, message)
+      end
+
+      def self.for_code(code)
+        kind = case code
+        when "UNAUTHENTICATED" then :authentication_required
+        when "INVALID_QUERY" then :invalid_query
+        when "CONFLICT", "SELECTION_EXPIRED", "SELECTION_INVALIDATED" then :conflict
+        else :not_found
+        end
+        fetch(kind)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/prune.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Deletes bookkeeping rows that can no longer be used (RAA-005): proposed
+  # intents and fixed selections whose expiry passed more than older_than ago.
+  # It never touches a run that started, succeeded or belongs to a collection,
+  # anything still referenced by work, batch or child rows, or audit events
+  # (their retention is the host's decision, see ADR 0005).
+  class Prune
+    DEFAULT_AGE = 7.days
+    BATCH = 1000
+    Result = Data.define(:intents, :selections)
+
+    def initialize(older_than: DEFAULT_AGE, now: Time.current)
+      unless older_than.is_a?(ActiveSupport::Duration) || older_than.is_a?(Numeric)
+        raise ConfigurationError, "older_than must be a duration"
+      end
+      raise ConfigurationError, "older_than must not be negative" if older_than.to_i.negative?
+      @cutoff = now - older_than
+    end
+
+    def call
+      Result.new(prune_intents, prune_selections)
+    end
+
+    private
+
+    def prune_intents
+      runs = OperationRun.arel_table
+      candidates = OperationRun.where(status: "proposed", parent_run_id: nil, selection_id: nil)
+        .where(runs[:expires_at].lt(@cutoff))
+        .where.not(id: WorkItem.select(:operation_run_id))
+        .where.not(id: BatchItem.select(:operation_run_id))
+        .where.not(id: BatchItem.select(:parent_run_id))
+        .where.not(id: OperationRun.where.not(parent_run_id: nil).select(:parent_run_id))
+      delete_in_batches(candidates) { |ids| OperationRun.where(id: ids).delete_all }
+    end
+
+    def prune_selections
+      candidates = Selection.where(Selection.arel_table[:expires_at].lt(@cutoff))
+        .where.not(id: OperationRun.where.not(selection_id: nil).select(:selection_id))
+      delete_in_batches(candidates) do |ids|
+        Selection.transaction do
+          SelectionItem.where(selection_id: ids).delete_all
+          Selection.where(id: ids).delete_all
+        end
+      end
+    end
+
+    def delete_in_batches(relation)
+      total = 0
+      loop do
+        ids = relation.limit(BATCH).pluck(:id)
+        break if ids.empty?
+        total += yield(ids)
+        break if ids.size < BATCH
+      end
+      total
+    end
+  end
+end