athar 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b0ef1986b6cadc08da710ef20abb9526c86f097bc032bf881ea9edb669884cd
-  data.tar.gz: 0cbadc431bdcc7c390f3e7e4d4e9bb8f2f80c269f770c7b855228fd1988da8b1
+  metadata.gz: f0b877c826fef22c35dbefe9df8a1d46704567f6a34041afb76f2be0c03d4ac0
+  data.tar.gz: 5d53ed66ce9dfaf3d64453ec9913c14498561cdad2e6db6593ec1899326fbd02
 SHA512:
-  metadata.gz: 05d969a0d558f38df5377489cadf8474c224838613714df374759e60a558a42de329d345b9aebe827a5b77bdf5f49aa57d96eaacc48525a56b6e3d85e3d9f596
-  data.tar.gz: 84b6440c8e7f7b2225c03c3440b469dae05aafb68aeee4ef7cd1a7972e361d10036acdc1f3b076d4824246951dfb9fa4845630ec350b2cd07cfa4b7fda3d2700
+  metadata.gz: 0b60bd4ac0cfe563946279bd7ee3e4da31e5add08fad25a5266fe9e14f9faa553cf958923770a4bb38e73981b8e876bfd2fe9dd9a831d24b0ff131d8b248c843
+  data.tar.gz: 9185f28b703880a04a6cc5a7259854eb17483d2a16a22526bce5c1ed1696363aa7c62438e3220ee7856c9064f031b643d3a35e2ccb746923ad40711071d33348

data/CHANGELOG.md

@@ -4,7 +4,11 @@ All notable changes to this project will be documented in this file.
 
 The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
 
-## [Unreleased]
+## [0.3.0] - 2026-05-10
+
+### Added
+
+- Read-only deletion-audit dashboard mounted at the engine root. Renders sidebar of tracked models, KPI strip, filter bar, paginated unified feed of `athar_deletions` and `athar_table_events`, and expandable detail. Tracked models are discovered at runtime from `pg_trigger`; no registry table. Self-contained CSS and JS under `app/assets/`, served through the host's asset pipeline (Sprockets or Propshaft) when available or by a built-in `Rack::Static` middleware otherwise; no `turbo-rails`, `stimulus-rails`, or `importmap-rails` required. Document the mount pattern and route-constraint auth in the README.
 
 ## [0.2.1] - 2026-05-06
 

data/README.md

@@ -37,6 +37,7 @@ It does not turn deleted rows into queryable models, and it does not provide ful
 - [Configuration](#configuration)
 - [How It Works](#how-it-works)
 - [Operational Notes](#operational-notes)
+- [Dashboard](#dashboard)
 - [Troubleshooting](#troubleshooting)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -462,6 +463,61 @@ The tasks start the local `postgres:18` Docker Compose service when needed, crea
 
 Results are machine-dependent. The scripts are intentionally not part of CI; they exist so maintainers can spot large regressions. See [`bench/RESULTS.md`](bench/RESULTS.md) for the last measured baseline.
 
+## Dashboard
+
+Athar ships a read-only audit dashboard as a Rails engine. It provides a browser interface for the data that Athar's triggers write to `athar_deletions` and `athar_table_events`.
+
+![Athar dashboard](docs/screenshots/dashboard.png)
+
+### Mounting
+
+Add the engine to your host app's `config/routes.rb`:
+
+```ruby
+mount Athar::Engine => "/athar"
+```
+
+### Authentication
+
+The engine has no built-in authentication and inherits from the host's `::ApplicationController`, so any `before_action`-based auth (session checks, policy gates) carries through automatically.
+
+For Devise-protected apps, wrap the mount in a route constraint:
+
+```ruby
+authenticate :user, ->(u) { u.admin? } do
+  mount Athar::Engine => "/athar"
+end
+```
+
+Any controller-level authentication strategy that works for your host app works here.
+
+### Dependencies
+
+Athar's only runtime dependencies are `activejob`, `activerecord`, `activesupport`, `railties`, and `fx`. The dashboard ships its own CSS and JS files, so `turbo-rails`, `stimulus-rails`, and `importmap-rails` are not required. The host's asset pipeline (Sprockets or Propshaft) serves those files when one is available; otherwise they're served by a `Rack::Static`-backed middleware bundled with the gem. Hosts that already use Hotwire are unaffected: the engine has its own layout, and dashboard pages set `<meta name="turbo-visit-control" content="reload">` so any Turbo Drive in the host falls back to a full page load when entering `/athar`.
+
+### What the dashboard shows
+
+- **Sidebar** — tracked models grouped by schema, with capture mode, masks, STI flag, truncate flag, and per-model audit row count. Discovered at runtime from `pg_trigger`; no registry table.
+- **KPI strip** — filtered row count, last 24 h, last 7 d with vs-prior delta, truncate event count, distinct actor count, and a 14-day sparkline.
+- **Filter bar** — full-text search across record/actor/metadata/data; time, mode, and kind segments; actor dropdown; clear.
+- **Unified feed** — paginated list of `athar_deletions` and truncate events from `athar_table_events`. Each row expands inline to show `record_data`, metadata, identity fields, and a requery snippet in both Ruby and SQL.
+- **Permalinks** — individual deletion at `/athar/deletions/:id`; individual table event at `/athar/table_events/:id`.
+
+### What it does not do
+
+The dashboard is read-only. There is no retention or configuration UI, no manual actions, no export, and no live updates (no polling, no Turbo Streams).
+
+### Privacy
+
+`record_data` is rendered as stored. Masking happens at trigger time, not at render time. The dashboard inherits whatever masking the host configured when the trigger was installed.
+
+> [!IMPORTANT]
+> If a trigger was installed without masking, the dashboard renders the raw values. Mask at the trigger level before sensitive data is written to `athar_deletions`.
+
+### Performance
+
+The index renders approximately 8–10 queries. Sidebar model counts and the actor dropdown query scale with audit-table size. Search uses `ILIKE` scans bounded by the active time filter. For very large audit tables, prefer narrower time windows when searching.
+
 ## Troubleshooting
 
 ### "Function `athar_capture_delete` does not exist"
@@ -501,6 +557,10 @@ The test task installs missing gems for the pinned Ruby, starts PostgreSQL 18 wh
 
 The dummy app under `test/dummy` is a real Rails app. By default it uses `schema.rb` + Fx; `ATHAR_NO_FX=1` flips it to `structure.sql` and the raw-SQL generator path. Tests use real triggers against a real database in both modes.
 
+### Dashboard assets
+
+The dashboard's CSS and JS are in `app/assets/stylesheets/athar/dashboard.css` and `app/assets/javascripts/athar/dashboard.js`. There's no build step: edit the file and reload the browser. The JS is a single IIFE that handles every dashboard interaction via delegated event listeners on `document`, including the partial-fetch swaps that keep `#athar-dashboard` in sync with the URL. `Athar::Middleware::AssetServer` serves the files at `/athar-assets/<gem-version>/dashboard.{js,css}` for hosts without an asset pipeline; everyone else gets digested URLs from Sprockets or Propshaft.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/milkstrawai/athar.

data/app/assets/javascripts/athar/dashboard.js

@@ -0,0 +1,290 @@
+/* Athar dashboard JS — single self-contained IIFE, no build step.
+ *
+ * Behavior:
+ *   - Partial-link clicks (anchors with `data-athar-partial-link`) intercept
+ *     navigation and swap #athar-pre and #athar-post in place via a single
+ *     fetch, pushing a new history entry. Modifier-clicks fall through to the
+ *     browser's default open-in-new-tab.
+ *   - Partial forms (`form[data-athar-partial-form]`) submit on change/input
+ *     (input is debounced) the same way. Drops the page param on every submit.
+ *     The form itself lives outside the swap regions, so the search input's
+ *     focus / value / selection are never disturbed.
+ *   - The filter bar's visual state (active segments, selected actor) is
+ *     reconciled from the URL after every swap by updateFilterBarFromUrl —
+ *     since the bar isn't re-rendered, we keep its highlights in sync from JS.
+ *   - Back/forward (popstate) re-fetches the current URL into the regions.
+ *   - Copy buttons (`[data-athar-copy="value"]`) write to the clipboard,
+ *     flash a check, and announce via the ARIA live region.
+ *   - Theme button (`[data-athar-theme-toggle]`) flips data-theme on <html>
+ *     and PATCHes /athar/theme to persist.
+ *   - Keyboard: `/` focuses the search input; Escape collapses the open row.
+ */
+(function () {
+  "use strict";
+
+  var SWAP_REGION_IDS = ["athar-pre", "athar-post"];
+  var FILTER_DEFAULTS = { time: "30d", mode: "all", kind: "all", actor: "all" };
+
+  // ---------- CSRF ----------
+  function csrfToken() {
+    var meta = document.querySelector('meta[name="csrf-token"]');
+    return meta ? meta.content : null;
+  }
+
+  // ---------- Partial-fetch helpers (CSP-safe, DOM-method swap) ----------
+  async function fetchPartial(url, options) {
+    options = options || {};
+    var headers = Object.assign({
+      "Accept": "text/html",
+      "X-Requested-With": "XMLHttpRequest",
+      "X-Athar-Partial": "true"
+    }, options.headers || {});
+
+    var method = (options.method || "GET").toUpperCase();
+    if (method !== "GET" && method !== "HEAD") {
+      var token = csrfToken();
+      if (token) headers["X-CSRF-Token"] = token;
+    }
+
+    var response = await fetch(url, Object.assign({}, options, { method: method, headers: headers }));
+    if (!response.ok) throw new Error("fetchPartial: " + response.status + " " + response.statusText);
+    var html = await response.text();
+    return new DOMParser().parseFromString(html, "text/html");
+  }
+
+  function replaceElement(target, source) {
+    while (target.firstChild) target.removeChild(target.firstChild);
+    Array.from(source.childNodes).forEach(function (child) {
+      target.appendChild(child.cloneNode(true));
+    });
+  }
+
+  // ---------- Partial nav: swap #athar-pre + #athar-post (skip filter bar) ----------
+  async function partialNav(url, options) {
+    options = options || {};
+
+    var regions = SWAP_REGION_IDS.map(function (id) { return document.getElementById(id); });
+    if (regions.some(function (el) { return el == null; })) {
+      // Required regions missing — fall back to a full navigation.
+      window.location.href = url;
+      return;
+    }
+
+    // Suppress the dimming indicator for form-driven submits — the user is
+    // actively typing, and any opacity transition near the cursor reads as a
+    // distracting flash on every keystroke.
+    var showLoading = !options.silent;
+    if (showLoading) regions.forEach(function (r) { r.classList.add("is-loading"); });
+
+    try {
+      var doc = await fetchPartial(url, options);
+
+      regions.forEach(function (region) {
+        var fresh = doc.getElementById(region.id);
+        if (fresh) replaceElement(region, fresh);
+      });
+
+      // Filter bar isn't re-rendered — reconcile its visual state from the URL.
+      updateFilterBarFromUrl();
+
+      if (options.replaceState) {
+        history.replaceState({}, "", url);
+      } else {
+        history.pushState({}, "", url);
+      }
+    } catch (error) {
+      console.error("[athar] partial-nav failed, falling back to full navigation:", error);
+      window.location.href = url;
+    } finally {
+      if (showLoading) regions.forEach(function (r) { r.classList.remove("is-loading"); });
+    }
+  }
+
+  // ---------- Filter bar state reconciliation ----------
+  // The filter bar lives outside the swap regions so the search input survives
+  // the partial swap. The cost: we have to keep its segment highlights and
+  // actor selection in sync with the URL ourselves.
+  function updateFilterBarFromUrl() {
+    var params = new URL(window.location.href).searchParams;
+
+    ["time", "mode", "kind"].forEach(function (name) {
+      var current = params.get(name) || FILTER_DEFAULTS[name];
+      document.querySelectorAll('[data-athar-seg="' + name + '"]').forEach(function (link) {
+        var matches = link.dataset.atharSegValue === current;
+        link.classList.toggle("is-active", matches);
+        if (matches) {
+          link.setAttribute("aria-current", "page");
+        } else {
+          link.removeAttribute("aria-current");
+        }
+      });
+    });
+
+    var actorSelect = document.getElementById("athar-actor");
+    if (actorSelect) {
+      var actor = params.get("actor") || FILTER_DEFAULTS.actor;
+      if (actorSelect.value !== actor) actorSelect.value = actor;
+    }
+  }
+
+  // ---------- Form submit (build URL from current params + form data) ----------
+  function buildSubmitUrl(form) {
+    var action = form.action || window.location.href;
+    var url = new URL(action, window.location.origin);
+    // Baseline from the *current* URL, not the form's action — the form has no
+    // hidden fields preserving model/time/mode/kind, so without this the only
+    // params that would survive a search submit are q + actor.
+    var params = new URLSearchParams(window.location.search);
+    // Drop params the form is replacing or that should reset.
+    params.delete("q"); params.delete("page"); params.delete("expanded");
+
+    var data = new FormData(form);
+    var entries = data.entries ? data.entries() : [];
+    for (var entry of entries) {
+      var key = entry[0];
+      var value = entry[1];
+      if (value === "" || value == null) continue;
+      params.set(key, value);
+    }
+
+    url.search = params.toString();
+    return url.toString();
+  }
+
+  function submitForm(form) {
+    partialNav(buildSubmitUrl(form), { silent: true });
+  }
+
+  // ---------- Copy button ----------
+  var COPY_CHECK_SVG = '<svg viewBox="0 0 16 16" width="11" height="11" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 8l3 3 7-7"/></svg>';
+
+  function announce(message) {
+    var region = document.getElementById("athar-aria-live");
+    if (!region) return;
+    region.textContent = "";
+    requestAnimationFrame(function () { region.textContent = message; });
+  }
+
+  function flashCopied(button) {
+    var label = button.getAttribute("data-athar-copy-label") || "text";
+    announce("Copied " + label);
+
+    var original = button.innerHTML;
+    button.innerHTML = COPY_CHECK_SVG;
+
+    if (button._atharCopyTimeout) clearTimeout(button._atharCopyTimeout);
+    button._atharCopyTimeout = setTimeout(function () {
+      if (button.isConnected) button.innerHTML = original;
+    }, 1100);
+  }
+
+  function doCopy(button) {
+    var value = button.getAttribute("data-athar-copy");
+    if (!value) return;
+    flashCopied(button);
+    if (navigator.clipboard) {
+      navigator.clipboard.writeText(value).catch(function (error) {
+        console.warn("athar: clipboard write failed", error);
+      });
+    }
+  }
+
+  // ---------- Theme toggle (optimistic, revert on failure) ----------
+  function toggleTheme(button) {
+    var previous = document.documentElement.dataset.theme === "dark" ? "dark" : "light";
+    var next = previous === "dark" ? "light" : "dark";
+    var previousLabel = button.textContent;
+
+    document.documentElement.dataset.theme = next;
+    button.textContent = next === "dark" ? "◐" : "◑";
+
+    var meta = document.querySelector('meta[name="athar-theme-url"]');
+    var url = (meta && meta.content) || "/athar/theme";
+
+    fetch(url, {
+      method: "PATCH",
+      headers: {
+        "Content-Type": "application/json",
+        "X-CSRF-Token": csrfToken() || "",
+        "Accept": "application/json"
+      },
+      body: JSON.stringify({ theme: next })
+    }).then(function (response) {
+      if (!response.ok) throw new Error("HTTP " + response.status);
+    }).catch(function (error) {
+      // Revert optimistic UI so on-screen state stays in sync with the cookie.
+      document.documentElement.dataset.theme = previous;
+      button.textContent = previousLabel;
+      console.warn("athar: theme persistence failed", error);
+    });
+  }
+
+  // ---------- Click delegation ----------
+  document.addEventListener("click", function (event) {
+    // Partial-link anchors first — they need preventDefault.
+    var partialLink = event.target.closest("a[data-athar-partial-link]");
+    if (partialLink) {
+      if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+      if (event.button !== 0) return;
+      event.preventDefault();
+      partialNav(partialLink.href);
+      return;
+    }
+
+    var copyBtn = event.target.closest("[data-athar-copy]");
+    if (copyBtn) {
+      event.preventDefault();
+      event.stopPropagation();
+      doCopy(copyBtn);
+      return;
+    }
+
+    var themeBtn = event.target.closest("[data-athar-theme-toggle]");
+    if (themeBtn) {
+      toggleTheme(themeBtn);
+      return;
+    }
+  });
+
+  // ---------- Form change/input delegation ----------
+  var formInputDebounce;
+  document.addEventListener("change", function (event) {
+    var form = event.target.closest("form[data-athar-partial-form]");
+    if (!form) return;
+    if (formInputDebounce) { clearTimeout(formInputDebounce); formInputDebounce = null; }
+    submitForm(form);
+  });
+  document.addEventListener("input", function (event) {
+    var form = event.target.closest("form[data-athar-partial-form]");
+    if (!form) return;
+    if (formInputDebounce) clearTimeout(formInputDebounce);
+    formInputDebounce = setTimeout(function () { submitForm(form); }, 300);
+  });
+
+  // ---------- Keyboard shortcuts ----------
+  document.addEventListener("keydown", function (event) {
+    // Escape always collapses an open row, even when focus is in an input —
+    // otherwise the input's default Escape handling eats the first press.
+    if (event.key === "Escape") {
+      var collapse = document.querySelector("[data-collapse-expand]");
+      if (collapse) {
+        event.preventDefault();
+        collapse.click();
+      }
+      return;
+    }
+
+    if (event.target.matches("input, textarea, select") || event.target.isContentEditable) return;
+
+    if (event.key === "/") {
+      event.preventDefault();
+      var search = document.querySelector(".filter-search input[type=search]");
+      if (search) search.focus();
+    }
+  });
+
+  // ---------- Browser back/forward ----------
+  window.addEventListener("popstate", function () {
+    partialNav(window.location.href, { silent: true, replaceState: true });
+  });
+})();