rails_audit_log 0.8.0 → 1.0.0

data/app/models/rails_audit_log/audit_log_entry.rb

@@ -1,37 +1,87 @@
 module RailsAuditLog
+  # Represents a single audited event (+create+, +update+, or +destroy+) for
+  # one ActiveRecord record.
+  #
+  # == Columns
+  #
+  # [event]               One of <tt>"create"</tt>, <tt>"update"</tt>, <tt>"destroy"</tt>.
+  # [item_type]           Class name of the audited record (e.g. <tt>"Article"</tt>).
+  # [item_id]             Primary key of the audited record.
+  # [object_changes]      JSON hash of attribute changes in <tt>[from, to]</tt> form.
+  #                       All three event types use the same format:
+  #                       +create+ stores <tt>[nil, new]</tt> for every column,
+  #                       +update+ stores <tt>[old, new]</tt> for changed columns only,
+  #                       +destroy+ stores <tt>[final, nil]</tt> for every column.
+  # [object]              JSON snapshot of the record's full attributes before the
+  #                       change (stored when {RailsAuditLog.store_snapshot} is +true+).
+  # [whodunnit_snapshot]  Display name of the actor at the time of the change.
+  # [actor_type / actor_id] Polymorphic reference to the actor record.
+  # [reason]              Optional free-text reason string.
+  # [metadata]            Arbitrary JSON hash (request IP, custom lambdas, etc.).
   class AuditLogEntry < ApplicationRecord
     self.table_name = "audit_log_entries"
 
-    EVENTS = %w[create update destroy].freeze
+    EVENTS       = %w[create update destroy].freeze
     BLOB_COLUMNS = %w[object_changes object metadata].freeze
+    PERIODS      = { "1h" => 1.hour, "24h" => 24.hours, "7d" => 7.days }.freeze
 
+    # @api private
     def self.configure_connection!
       return unless (opts = RailsAuditLog.connects_to)
 
       connects_to(**opts)
     end
 
-    belongs_to :item, polymorphic: true, optional: true
+    belongs_to :item,  polymorphic: true, optional: true
     belongs_to :actor, polymorphic: true, optional: true
 
-    validates :event, presence: true, inclusion: { in: EVENTS }
+    validates :event,     presence: true, inclusion: { in: EVENTS }
     validates :item_type, presence: true
-    validates :item_id, presence: true
-    validate :metadata_must_be_a_hash
+    validates :item_id,   presence: true
+    validate  :metadata_must_be_a_hash
 
-    # Event scopes
+    # @!group Event scopes
+
+    # Entries for +create+ events.
+    # @return [ActiveRecord::Relation]
     scope :created_events,  -> { where(event: "create") }
+
+    # Entries for +update+ events.
+    # @return [ActiveRecord::Relation]
     scope :updated_events,  -> { where(event: "update") }
-    scope :destroyed_events, -> { where(event: "destroy") }
 
-    # Deprecated short aliases kept for backwards compatibility
+    # Entries for +destroy+ events.
+    # @return [ActiveRecord::Relation]
+    scope :destroyed_events, -> { where(event: "destroy") }
 
+    # @deprecated Use {.created_events} instead.
     scope :creates,  -> { created_events }
+    # @deprecated Use {.updated_events} instead.
     scope :updates,  -> { updated_events }
+    # @deprecated Use {.destroyed_events} instead.
     scope :destroys, -> { destroyed_events }
 
-    # Actor / resource scopes
+    # @!endgroup
+
+    # @!group Actor / resource scopes
+
+    # Entries written by a specific actor.
+    #
+    # @param actor [ActiveRecord::Base] the actor record to filter by
+    # @return [ActiveRecord::Relation]
+    # @example
+    #   AuditLogEntry.by_actor(current_user)
     scope :by_actor, ->(actor) { where(actor_type: actor.class.name, actor_id: actor.id) }
+
+    # Entries for a specific resource class or instance.
+    # Pass a class to get all entries for that type; pass an instance for one record.
+    #
+    # @param resource [Class, ActiveRecord::Base]
+    # @return [ActiveRecord::Relation]
+    # @example All entries for Article
+    #   AuditLogEntry.for_resource(Article)
+    # @example All entries for one article
+    #   AuditLogEntry.for_resource(article)
     scope :for_resource, lambda { |resource|
       if resource.is_a?(Class)
         where(item_type: resource.name)
@@ -40,15 +90,61 @@ module RailsAuditLog
       end
     }
 
-    # Time scopes
+    # @!endgroup
+
+    # @!group Time scopes
+
+    # Entries created at or after +time+.
+    #
+    # @param time [Time]
+    # @return [ActiveRecord::Relation]
     scope :since, ->(time) { where(created_at: time..) }
+
+    # Entries created at or before +time+.
+    #
+    # @param time [Time]
+    # @return [ActiveRecord::Relation]
     scope :until, ->(time) { where(created_at: ..time) }
 
-    # Projection scope — omits JSON blob columns for index/listing queries
+    # Entries within a named period. Valid keys: <tt>"1h"</tt>, <tt>"24h"</tt>, <tt>"7d"</tt>.
+    #
+    # @param period [String] one of +PERIODS.keys+
+    # @return [ActiveRecord::Relation]
+    scope :for_period, ->(period) { where(created_at: PERIODS[period].ago..) }
+
+    # @!endgroup
+
+    # Omits the three JSON blob columns (+object_changes+, +object+, +metadata+)
+    # from the +SELECT+. Use on index/listing queries where blobs are not
+    # displayed to reduce I/O and avoid deserializing large payloads.
+    #
+    # @return [ActiveRecord::Relation]
     scope :slim, -> { select(column_names - BLOB_COLUMNS) }
 
-    # Instance methods
+    # Entries where +object_changes+ contains a key matching +attribute+.
+    # Uses <tt>json_extract</tt> on SQLite/MySQL and <tt>->></tt> on PostgreSQL.
+    #
+    # @param attribute [Symbol, String] the attribute name to filter on
+    # @return [ActiveRecord::Relation]
+    # @example
+    #   AuditLogEntry.touching(:title)
+    #   post.audit_log_entries.updated_events.touching(:published_at)
+    scope :touching, ->(attribute) {
+      if connection.adapter_name =~ /PostgreSQL/i
+        # :nocov:
+        where("object_changes->>? IS NOT NULL", attribute.to_s)
+        # :nocov:
+      else
+        where("json_extract(object_changes, ?) IS NOT NULL", "$.#{attribute}")
+      end
+    }
 
+    # Reconstructs and returns the record's state *before* this entry's change.
+    # Uses the +object+ snapshot when available; falls back to deriving prior
+    # state from +object_changes+ (or the live record for +update+ entries).
+    #
+    # @return [ActiveRecord::Base, nil] an unpersisted instance; +nil+ for
+    #   +create+ entries (there is no prior state)
     def reify
       return nil if event == "create"
 
@@ -80,18 +176,37 @@ module RailsAuditLog
       instance
     end
 
+    # Returns the entry immediately before this one in the version chain for
+    # the same record (lower +id+), or +nil+ if this is the first entry.
+    #
+    # @return [AuditLogEntry, nil]
     def previous
       self.class.where(item_type: item_type, item_id: item_id).where("id < ?", id).order(id: :desc).first
     end
 
+    # Returns the entry immediately after this one in the version chain for
+    # the same record (higher +id+), or +nil+ if this is the last entry.
+    #
+    # @return [AuditLogEntry, nil]
     def next
       self.class.where(item_type: item_type, item_id: item_id).where("id > ?", id).order(id: :asc).first
     end
 
+    # Returns the list of attribute (and association) names that changed in
+    # this entry, derived from the keys of +object_changes+.
+    #
+    # @return [Array<String>]
     def changed_attributes
       object_changes&.keys || []
     end
 
+    # Returns +object_changes+ in a named-key format convenient for display.
+    #
+    # @return [Hash{String => Hash}] keys are attribute names; values are
+    #   hashes with +:from+ and +:to+ keys
+    # @example
+    #   entry.diff
+    #   # => { "title" => { from: "Old", to: "New" }, ... }
     def diff
       return {} unless object_changes
 
@@ -103,18 +218,5 @@ module RailsAuditLog
     def metadata_must_be_a_hash
       errors.add(:metadata, "must be a Hash") if metadata.present? && !metadata.is_a?(Hash)
     end
-
-    public
-
-    # Attribute scope — uses json_extract (SQLite/MySQL) or ->> (PostgreSQL)
-    scope :touching, ->(attribute) {
-      if connection.adapter_name =~ /PostgreSQL/i
-        # :nocov:
-        where("object_changes->>? IS NOT NULL", attribute.to_s)
-        # :nocov:
-      else
-        where("json_extract(object_changes, ?) IS NOT NULL", "$.#{attribute}")
-      end
-    }
   end
 end

data/app/views/layouts/rails_audit_log/application.html.erb

@@ -1,17 +1,23 @@
 <!DOCTYPE html>
-<html>
+<html lang="en">
 <head>
-  <title>Rails audit log</title>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Audit Log</title>
+  <link rel="icon" href="data:,">
   <%= csrf_meta_tags %>
   <%= csp_meta_tag %>
-
-  <%= yield :head %>
-
-  <%= stylesheet_link_tag    "rails_audit_log/application", media: "all" %>
+  <%= dashboard_stylesheets %>
+  <%= javascript_importmap_tags "rails_audit_log" %>
 </head>
 <body>
-
-<%= yield %>
-
+  <header class="ral-header">
+    <div class="ral-header__inner">
+      <%= link_to "Audit Log", root_path, class: "ral-header__logo" %>
+    </div>
+  </header>
+  <main class="ral-main">
+    <%= yield %>
+  </main>
 </body>
-</html>
+</html>

data/app/views/rails_audit_log/audit_log_entries/_diff.html.erb

@@ -0,0 +1,55 @@
+<% changes = entry.object_changes.presence %>
+<% if changes %>
+  <div class="ral-diff-wrap" data-controller="diff">
+    <div class="ral-diff-toggle">
+      <button class="ral-diff-btn ral-diff-btn--active"
+              data-diff-target="inlineBtn"
+              data-action="click->diff#setInline">Inline</button>
+      <button class="ral-diff-btn"
+              data-diff-target="sideBtn"
+              data-action="click->diff#setSide">Side by side</button>
+    </div>
+
+    <table class="ral-diff" data-diff-target="inline">
+      <thead>
+        <tr>
+          <th>Attribute</th>
+          <th>Before</th>
+          <th>After</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% changes.each do |attr, (before, after)| %>
+          <tr>
+            <td class="ral-diff__attr"><%= attr %></td>
+            <td class="ral-diff__before"><%= format_diff_value(before) %></td>
+            <td class="ral-diff__after"><%= format_diff_value(after) %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+
+    <div class="ral-diff-side" data-diff-target="side" hidden>
+      <div class="ral-diff-side__panel ral-diff-side__panel--before">
+        <div class="ral-diff-side__header">Before</div>
+        <% changes.each do |attr, (before, _after)| %>
+          <div class="ral-diff-side__row">
+            <span class="ral-diff-side__attr"><%= attr %></span>
+            <span class="ral-diff-side__value"><%= format_diff_value(before) %></span>
+          </div>
+        <% end %>
+      </div>
+      <div class="ral-diff-side__panel ral-diff-side__panel--after">
+        <div class="ral-diff-side__header">After</div>
+        <% changes.each do |attr, (_before, after)| %>
+          <div class="ral-diff-side__row">
+            <span class="ral-diff-side__attr"><%= attr %></span>
+            <span class="ral-diff-side__value"><%= format_diff_value(after) %></span>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+<% else %>
+  <p class="ral-muted">No changes recorded.</p>
+<% end %>

data/app/views/rails_audit_log/audit_log_entries/index.html.erb

@@ -0,0 +1,76 @@
+<div class="ral-page-header">
+  <h1 class="ral-page-header__title">Audit Entries</h1>
+  <span class="ral-page-header__meta"><%= @pagy.count %> <%= "entry".pluralize(@pagy.count) %></span>
+</div>
+
+<%= turbo_frame_tag "ral-entries", data: { turbo_action: "advance" } do %>
+  <form class="ral-filters" action="<%= audit_log_entries_path %>" method="get"
+        data-controller="search">
+    <%= hidden_field_tag :period, @period if @period %>
+
+    <input type="search" name="q" value="<%= @q %>"
+           class="ral-filter-input" placeholder="Filter by actor…"
+           autocomplete="off" aria-label="Filter by actor"
+           data-action="input->search#filter">
+
+    <select name="event" class="ral-filter-select" aria-label="Filter by event"
+            data-action="change->search#select">
+      <option value="">All events</option>
+      <% RailsAuditLog::AuditLogEntry::EVENTS.each do |event| %>
+        <option value="<%= event %>" <%= "selected" if @event == event %>><%= event.capitalize %></option>
+      <% end %>
+    </select>
+
+    <% if @item_types.size > 1 %>
+      <select name="item_type" class="ral-filter-select" aria-label="Filter by resource"
+              data-action="change->search#select">
+        <option value="">All resources</option>
+        <% @item_types.each do |type| %>
+          <option value="<%= type %>" <%= "selected" if @item_type == type %>><%= type %></option>
+        <% end %>
+      </select>
+    <% end %>
+
+    <div class="ral-period-filter" role="group" aria-label="Time period">
+      <%= link_to "All", audit_log_entries_path(event: @event, item_type: @item_type, q: @q),
+            class: "ral-period-btn#{" ral-period-btn--active" if @period.blank?}" %>
+      <% RailsAuditLog::AuditLogEntry::PERIODS.each_key do |p| %>
+        <%= link_to p, audit_log_entries_path(event: @event, item_type: @item_type, q: @q, period: p),
+              class: "ral-period-btn#{" ral-period-btn--active" if @period == p}" %>
+      <% end %>
+    </div>
+
+    <% if @event || @item_type || @period || @q %>
+      <%= link_to "Clear", audit_log_entries_path, class: "ral-link ral-filters__clear" %>
+    <% end %>
+  </form>
+
+  <% if @entries.any? %>
+    <div class="ral-table-wrap">
+      <table class="ral-table">
+        <thead>
+          <tr>
+            <th>Event</th>
+            <th>Resource</th>
+            <th>Actor</th>
+            <th>When</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% @entries.each do |entry| %>
+            <tr>
+              <td><span class="ral-badge ral-badge--<%= entry.event %>"><%= entry.event %></span></td>
+              <td><%= link_to "#{entry.item_type} ##{entry.item_id}", resource_path(item_type: entry.item_type, item_id: entry.item_id), class: "ral-link", data: { turbo_frame: "_top" } %></td>
+              <td><%= entry.whodunnit_snapshot.presence || (entry.actor_type ? "#{entry.actor_type} \##{entry.actor_id}" : "—") %></td>
+              <td class="ral-timestamp"><%= entry.created_at.utc.strftime("%Y-%m-%d %H:%M UTC") %></td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+
+    <%== @pagy.series_nav(aria_label: "Pagination") if @pagy.pages > 1 %>
+  <% else %>
+    <p class="ral-empty">No audit entries found.</p>
+  <% end %>
+<% end %>

data/app/views/rails_audit_log/audit_log_entries/show.html.erb

@@ -0,0 +1,50 @@
+<div class="ral-page-header">
+  <div>
+    <p class="ral-breadcrumb">
+      <%= link_to "Audit Entries", audit_log_entries_path, class: "ral-link" %> /
+      <%= link_to "#{@entry.item_type} ##{@entry.item_id}", resource_path(item_type: @entry.item_type, item_id: @entry.item_id), class: "ral-link" %>
+    </p>
+    <h1 class="ral-page-header__title">Entry #<%= @entry.id %></h1>
+  </div>
+  <nav class="ral-entry-nav" aria-label="Entry navigation">
+    <% if (prev_entry = @entry.previous) %>
+      <%= link_to "← Previous", audit_log_entry_path(prev_entry), class: "ral-pagination__link" %>
+    <% end %>
+    <% if (next_entry = @entry.next) %>
+      <%= link_to "Next →", audit_log_entry_path(next_entry), class: "ral-pagination__link" %>
+    <% end %>
+  </nav>
+</div>
+
+<div class="ral-card">
+  <dl class="ral-meta">
+    <div class="ral-meta__row">
+      <dt>Event</dt>
+      <dd><span class="ral-badge ral-badge--<%= @entry.event %>"><%= @entry.event %></span></dd>
+    </div>
+    <div class="ral-meta__row">
+      <dt>Resource</dt>
+      <dd><%= link_to "#{@entry.item_type} ##{@entry.item_id}", resource_path(item_type: @entry.item_type, item_id: @entry.item_id), class: "ral-link" %></dd>
+    </div>
+    <% actor = @entry.whodunnit_snapshot.presence || (@entry.actor_type ? "#{@entry.actor_type} \##{@entry.actor_id}" : "—") %>
+    <div class="ral-meta__row">
+      <dt>Actor</dt>
+      <dd><%= actor %></dd>
+    </div>
+    <div class="ral-meta__row">
+      <dt>When</dt>
+      <dd class="ral-timestamp"><%= @entry.created_at.utc.strftime("%Y-%m-%d %H:%M:%S UTC") %></dd>
+    </div>
+    <% if @entry.reason.present? %>
+      <div class="ral-meta__row">
+        <dt>Reason</dt>
+        <dd><%= @entry.reason %></dd>
+      </div>
+    <% end %>
+  </dl>
+</div>
+
+<h2 class="ral-section-title">Changes</h2>
+<div class="ral-card">
+  <%= render "diff", entry: @entry %>
+</div>

data/app/views/rails_audit_log/resources/show.html.erb

@@ -0,0 +1,35 @@
+<div class="ral-page-header">
+  <div>
+    <p class="ral-breadcrumb"><%= link_to "Audit Entries", audit_log_entries_path, class: "ral-link" %></p>
+    <h1 class="ral-page-header__title"><%= @item_type %> #<%= @item_id %></h1>
+  </div>
+  <span class="ral-page-header__meta"><%= @pagy.count %> <%= "entry".pluralize(@pagy.count) %></span>
+</div>
+
+<%= turbo_frame_tag "ral-resource-entries", data: { turbo_action: "advance" } do %>
+  <% if @entries.any? %>
+    <div class="ral-timeline">
+      <% @entries.each do |entry| %>
+        <div class="ral-timeline__entry">
+          <div class="ral-timeline__header">
+            <span class="ral-badge ral-badge--<%= entry.event %>"><%= entry.event %></span>
+            <span class="ral-timestamp"><%= entry.created_at.utc.strftime("%Y-%m-%d %H:%M UTC") %></span>
+            <% actor = entry.whodunnit_snapshot.presence || (entry.actor_type ? "#{entry.actor_type} \##{entry.actor_id}" : nil) %>
+            <% if actor %>
+              <span class="ral-muted">by <%= actor %></span>
+            <% end %>
+            <% if entry.reason.present? %>
+              <span class="ral-reason">"<%= entry.reason %>"</span>
+            <% end %>
+            <%= link_to "Details →", audit_log_entry_path(entry), class: "ral-link ral-timeline__detail-link", data: { turbo_frame: "_top" } %>
+          </div>
+          <%= render "rails_audit_log/audit_log_entries/diff", entry: entry %>
+        </div>
+      <% end %>
+    </div>
+
+    <%== @pagy.series_nav(aria_label: "Pagination") if @pagy.pages > 1 %>
+  <% else %>
+    <p class="ral-empty">No audit entries for this record.</p>
+  <% end %>
+<% end %>

data/config/importmap.rb

@@ -0,0 +1,5 @@
+pin "@hotwired/turbo", to: "https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.23/dist/turbo.es2017-esm.js"
+pin "@hotwired/stimulus", to: "https://cdn.jsdelivr.net/npm/@hotwired/stimulus@3.2.2/dist/stimulus.js"
+pin "rails_audit_log", to: "rails_audit_log/application.js"
+pin "rails_audit_log/search_controller", to: "rails_audit_log/search_controller.js"
+pin "rails_audit_log/diff_controller",   to: "rails_audit_log/diff_controller.js"

data/config/routes.rb

@@ -1,2 +1,5 @@
 RailsAuditLog::Engine.routes.draw do
+  root to: "audit_log_entries#index"
+  resources :audit_log_entries, only: [:index, :show]
+  get "resources/:item_type/:item_id", to: "resources#show", as: :resource
 end

data/lib/generators/rails_audit_log/initializer/templates/rails_audit_log.rb

@@ -28,4 +28,14 @@ RailsAuditLog.configure do |config|
 
   # Route AuditLogEntry to a dedicated database (Rails multi-DB). Default: nil
   # config.connects_to = { database: { writing: :audit_log, reading: :audit_log } }
+
+  # Number of entries per page in the web dashboard. Default: 25
+  # config.page_size = 50
+
+  # Gate web dashboard access. Block runs in controller context — controller
+  # methods like current_user are available directly, or accept the controller
+  # as an argument. Falls back to HTTP Basic auth if the block returns falsy.
+  # Leave unset to allow unauthenticated access (development default).
+  # config.authenticate { current_user&.admin? }
+  # config.authenticate { |c| c.current_user&.admin? }
 end

data/lib/generators/rails_audit_log/migrate_from_paper_trail/migrate_from_paper_trail_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RailsAuditLog
+  module Generators
+    class MigrateFromPaperTrailGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a data migration that copies PaperTrail versions to audit_log_entries."
+
+      def create_migration_file
+        migration_template(
+          "migrate_from_paper_trail.rb",
+          "db/migrate/migrate_from_paper_trail.rb"
+        )
+      end
+    end
+  end
+end

data/lib/generators/rails_audit_log/migrate_from_paper_trail/templates/migrate_from_paper_trail.rb

@@ -0,0 +1,99 @@
+require "yaml"
+require "json"
+
+# Data migration: copies PaperTrail `versions` rows to `audit_log_entries`.
+#
+# Column mapping:
+#   versions.item_type        → audit_log_entries.item_type
+#   versions.item_id          → audit_log_entries.item_id
+#   versions.event            → audit_log_entries.event  (create/update/destroy only)
+#   versions.object_changes   → audit_log_entries.object_changes  (YAML or JSON → JSON)
+#   versions.object           → audit_log_entries.object           (YAML or JSON → JSON)
+#   versions.whodunnit        → audit_log_entries.whodunnit_snapshot
+#   versions.created_at       → audit_log_entries.created_at
+#
+# actor_type / actor_id are not populated — PaperTrail stores the actor
+# only as a string (whodunnit), so polymorphic references cannot be inferred.
+#
+# This migration is irreversible.
+class MigrateFromPaperTrail < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  BATCH_SIZE    = 1_000
+  VALID_EVENTS  = %w[create update destroy].freeze
+
+  # Isolated AR classes to avoid coupling to the host app's models.
+  class Version < ActiveRecord::Base   # @api private
+    self.table_name = "versions"
+  end
+
+  class AuditEntry < ActiveRecord::Base   # @api private
+    self.table_name = "audit_log_entries"
+  end
+
+  def up
+    unless table_exists?(:versions)
+      say "  versions table not found — nothing to migrate."
+      return
+    end
+
+    total     = Version.count
+    migrated  = 0
+    skipped   = 0
+
+    say_with_time "Migrating #{total} PaperTrail versions → audit_log_entries" do
+      Version.in_batches(of: BATCH_SIZE) do |batch|
+        rows = batch.filter_map do |v|
+          next unless VALID_EVENTS.include?(v.event)
+
+          {
+            event:              v.event,
+            item_type:          v.item_type,
+            item_id:            v.item_id,
+            object_changes:     parse_serialized(v.read_attribute_before_type_cast(:object_changes)),
+            object:             parse_serialized(v.read_attribute_before_type_cast(:object)),
+            whodunnit_snapshot: v.whodunnit,
+            created_at:         v.created_at,
+            updated_at:         v.created_at
+          }
+        end
+
+        skipped  += batch.size - rows.size
+        migrated += rows.size
+        AuditEntry.insert_all(rows) if rows.any?
+      end
+    end
+
+    say "  Migrated: #{migrated}  Skipped (unsupported event): #{skipped}"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration,
+          "Cannot reverse PaperTrail migration — rows already written to audit_log_entries " \
+          "cannot be reliably distinguished from native entries."
+  end
+
+  private
+
+  # Parses a PaperTrail serialized column (YAML or JSON) and returns a Hash,
+  # or nil if the value is blank or unparseable.
+  def parse_serialized(value)
+    return nil if value.nil? || value.to_s.strip.empty?
+
+    begin
+      parsed = JSON.parse(value)
+      return parsed.is_a?(Hash) ? parsed : nil
+    rescue JSON::ParserError
+      # fall through to YAML
+    end
+
+    begin
+      parsed = YAML.safe_load(
+        value,
+        permitted_classes: [Symbol, Date, Time, DateTime, BigDecimal,
+                             ActiveSupport::TimeWithZone, ActiveSupport::Duration]
+      )
+      parsed.is_a?(Hash) ? parsed : nil
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/rails_audit_log/engine.rb

@@ -1,7 +1,36 @@
+require "turbo-rails"
+require "importmap-rails"
+require "pagy"
+require "pagy/toolbox/paginators/method"
+
 module RailsAuditLog
+  # @api private
   class Engine < ::Rails::Engine
     isolate_namespace RailsAuditLog
 
+    config.i18n.load_path += Gem.find_files("pagy/locales/en.yml")
+
+    initializer "rails_audit_log.pagy" do |app|
+      app.config.after_initialize do
+        Pagy::OPTIONS[:limit] = RailsAuditLog.page_size
+      end
+    end
+
+    initializer "rails_audit_log.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+        app.config.assets.paths << root.join("app/assets/images")
+        app.config.assets.paths << root.join("app/javascript")
+      end
+    end
+
+    initializer "rails_audit_log.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << root.join("app/javascript")
+      end
+    end
+
     initializer "rails_audit_log.connect_audit_db" do
       ActiveSupport.on_load(:active_record) do
         RailsAuditLog::AuditLogEntry.configure_connection!