@mason-data/cli 0.7.0 → 0.8.0

package/dist/src/web/charts.js

@@ -0,0 +1,229 @@
+/**
+ * THE CHARTS OF THE WEB PAGE (docs/WEB-UI.md "Presentation"): a sparkline in a KPI card and a small time-series chart
+ * (bars or a line), drawn by uPlot (vendored whole: src/web/vendor/uplot-1.6.32/, MIT) and themed from the CSS tokens
+ * (`--chart-*`, src/web/app.css). A chart is a PROGRESSIVE ADDITION: every number it draws is also said as text in a
+ * card or a table (the tests read the text), so a page reads the same where uPlot never loads.
+ *
+ * How a page uses them:
+ *   1. its renderer writes a holder where the chart goes — `spark(key, label)` or `seriesChart(key, label)` — an empty
+ *      div that takes no room until it is drawn;
+ *   2. its `charts()` (the page module contract, src/web/app.js) returns `{ [key]: spec }`, a spec being
+ *      `{ kind: "spark" | "bars" | "line", x: seconds[], y: (number | null)[], label, format?(v) → text, unit? }`
+ *      (`format` says a hovered value exactly, as the tables do; `unit` — "bytes", "ms", else a count — the axis's
+ *      compact labels and steps: `axisFormat`, `axisIncrs`; the time axis's labels follow the span, `timeTick`)
+ *      (`seriesOf(samples, field)` makes x and y from /api/usage's samples);
+ *   3. the shell, after it writes the page, calls `mount(specs)` of ONE `createCharts`: a chart is made once per key,
+ *      moved into the holder a rewrite made, given its new data when the data changed, and destroyed when its key or
+ *      holder is gone — no instance outlives what it draws.
+ * DOM-free until `mount`, so the module loads under node; uPlot itself is imported only then.
+ */
+import { esc } from "./shared.js";
+
+/** uPlot's module, imported relative to this one (a route of PAGE_ROUTES), only in a browser and only once. */
+const UPLOT = "./vendor/uplot-1.6.32/uPlot.esm.js";
+
+const holder = (cls, key, label) => `<div class="chart ${cls}" data-chart="${esc(key)}" role="img" aria-label="${esc(label)}"></div>`;
+/** Where a KPI card's sparkline is drawn: `card(label, value, sub, spark("rows", "Rows, the last 24 hours"))`. */
+export const spark = (key, label) => holder("spark", key, label);
+/** Where a small time-series chart is drawn (above the table that says the same numbers). */
+export const seriesChart = (key, label) => holder("series", key, label);
+
+/** A series from /api/usage's samples: x each sample's time in seconds, y its `field` (null where it has none). */
+export function seriesOf(samples, field) {
+  return { x: samples.map((s) => Date.parse(s.at) / 1000), y: samples.map((s) => typeof s[field] === "number" ? s[field] : null) };
+}
+
+/** Whether a spec is worth drawing: two points with a value, at least (one point is no trend). */
+export const drawable = (spec) => spec !== undefined && spec !== null && Array.isArray(spec.x) && spec.x.length >= 2 &&
+  spec.y.filter((v) => v !== null).length >= 2;
+
+/** The colours and the font a chart is drawn in, from the page's tokens (light or dark: the stylesheet chooses). */
+function themeOf(doc, win) {
+  const cs = win.getComputedStyle(doc.documentElement);
+  const v = (k, d) => cs.getPropertyValue(k).trim() || d;
+  return { trend: v("--chart-trend", "#a8a8a8"), mark: v("--chart-mark", "#0070f3"), grid: v("--chart-grid", "#ebebeb"),
+    text: v("--chart-text", "#8f8f8f"), font: v("--font-mono", "monospace") };
+}
+
+/** The index of a series' last value: where a sparkline's one marker goes (the latest period, in the accent). */
+const lastIndex = (y) => { for (let i = y.length - 1; i >= 0; i--) if (y[i] !== null) return i; return -1; };
+
+// ------------------------------------------------------------------ the axes' words (pure: the tests hold each)
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/**
+ * A TIME TICK'S LABEL for a chart spanning `span` seconds, in UTC as the tables say it: minutes and hours (`09:05`,
+ * `14:00`) up to two days; past that a day (`Oct 27`) at midnight and the hour between (`12:00`), so a week reads by
+ * its days. Short enough that ticks 72 px apart never touch.
+ */
+export function timeTick(sec, span) {
+  const d = new Date(sec * 1000);
+  const hm = d.toISOString().slice(11, 16);
+  if (span <= 2 * 86_400) return hm;
+  return hm === "00:00" ? `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}` : hm;
+}
+
+/** The hovered time, read out under the chart: the minute alone within three hours, else its date too (`2026-10-27 09:00 UTC`). */
+export function readoutTime(sec, span) {
+  const iso = new Date(sec * 1000).toISOString();
+  return `${span <= 3 * 3600 ? iso.slice(11, 16) : `${iso.slice(0, 10)} ${iso.slice(11, 16)}`} UTC`;
+}
+
+const trim1 = (x) => (x >= 100 ? String(Math.round(x)) : x.toFixed(1).replace(/\.0$/, ""));
+
+/** A count on an axis: `0`, `950`, `1.2K`, `3.4M` (the read-out and the table have it whole). */
+export const compactCount = (v) => new Intl.NumberFormat("en-US", { notation: "compact", maximumFractionDigits: 1 }).format(v);
+
+/** Bytes on an axis, in the units the commands use (KiB, MiB, GiB) and on to TiB and PiB: `512 B`, `3.4 MiB`, `1.5 TiB`. */
+export function compactBytes(v) {
+  const units = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
+  let i = 0, x = Math.abs(v);
+  while (x >= 1024 && i < units.length - 1) { x /= 1024; i++; }
+  return `${v < 0 ? "-" : ""}${i === 0 ? Math.round(x) : trim1(x)} ${units[i]}`;
+}
+
+/** A duration in ms on an axis: `512 ms`, `1.2 s`, `2.5 min`, `1.1 h`. */
+export function compactMs(v) {
+  if (v < 1000) return `${Math.round(v)} ms`;
+  if (v < 60_000) return `${trim1(v / 1000)} s`;
+  if (v < 3_600_000) return `${trim1(v / 60_000)} min`;
+  return `${trim1(v / 3_600_000)} h`;
+}
+
+/** An axis's labeller by a spec's unit: "bytes", "ms", else a count. */
+const axisFormat = (unit) => unit === "bytes" ? compactBytes : unit === "ms" ? compactMs : compactCount;
+
+/** The steps an axis's ticks are chosen from, by unit: whole numbers for a count or ms (never 0.5 of a statement), and
+ *  powers of 1024 for bytes, so a tick is 512 MiB or 1 GiB, never 477 MiB. */
+export function axisIncrs(unit) {
+  const bases = unit === "bytes" ? [1, 1024, 1024 ** 2, 1024 ** 3, 1024 ** 4, 1024 ** 5] : [1, 10, 100, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12];
+  const mults = unit === "bytes" ? [1, 2, 4, 8, 16, 32, 64, 128, 256, 512] : [1, 2, 5];
+  return [...new Set(bases.flatMap((b) => mults.map((m) => m * b)))].sort((a, b) => a - b);
+}
+
+/** The steps a time axis's ticks are chosen from, in seconds: whole minutes at the least (a tick between two minutes would
+ *  read as the minute twice), then hours, then days. */
+const TIME_INCRS = [60, 120, 300, 600, 900, 1800, 3600, 7200, 10_800, 21_600, 43_200, 86_400, 2 * 86_400, 7 * 86_400];
+
+/** The y range from a zero baseline, a little over the highest value (1 when all are 0). A spike keeps its height: the
+ *  axis is never cut, so the bar that is ten times the others reads as ten times (the table has every value). */
+export const zeroRange = (max) => [0, max > 0 ? max * 1.08 : 1];
+
+/**
+ * UPLOT'S OPTIONS FOR A SPEC (pure): a sparkline is the trend alone — no axis, legend or cursor, a 2px line in the
+ * de-emphasis gray from a zero baseline, its latest value an 8px dot in the accent; a series chart has recessive axes
+ * (UTC hours, the value's own format), one hue, bars with a 2px gap or a 2px line, and a cursor whose live legend is
+ * the hover read-out.
+ */
+export function chartOptions(spec, theme, width, height, uPlot) {
+  const fmt = spec.format ?? ((v) => String(v));
+  const zero = (_u, _min, max) => zeroRange(max);
+  if (spec.kind === "spark") {
+    return {
+      width, height, padding: [6, 6, 6, 6], legend: { show: false }, cursor: { show: false }, select: { show: false },
+      scales: { x: { time: false }, y: { range: zero } }, axes: [{ show: false }, { show: false }],
+      series: [{}, { label: spec.label, stroke: theme.trend, width: 2, spanGaps: false,
+        points: { show: true, size: 8, width: 0, fill: theme.mark, stroke: theme.mark, filter: (u, si) => { const i = lastIndex(u.data[si]); return i < 0 ? null : [i]; } } }],
+    };
+  }
+  const bars = spec.kind === "bars" && typeof uPlot?.paths?.bars === "function";
+  const axisFont = `11px ${theme.font}`;
+  const span = spec.x.length ? spec.x[spec.x.length - 1] - spec.x[0] : 0;
+  const axis = axisFormat(spec.unit);
+  return {
+    width, height, padding: [10, 24, 0, 0], legend: { show: true, live: true }, select: { show: false },
+    cursor: { drag: { x: false, y: false }, points: { size: 8, fill: theme.mark } },
+    ...(typeof uPlot?.tzDate === "function" ? { tzDate: (ts) => uPlot.tzDate(new Date(ts * 1000), "Etc/UTC") } : {}),
+    scales: { x: { time: true }, y: { range: zero } },
+    axes: [
+      { stroke: theme.text, font: axisFont, space: 72, incrs: TIME_INCRS, grid: { show: false }, ticks: { stroke: theme.grid, width: 1, size: 4 }, values: (_u, vals) => vals.map((v) => timeTick(v, span)) },
+      { stroke: theme.text, font: axisFont, size: 64, space: 28, incrs: axisIncrs(spec.unit), grid: { stroke: theme.grid, width: 1 }, ticks: { show: false }, values: (_u, vals) => vals.map(axis) },
+    ],
+    series: [
+      // the read-out under the chart: the hovered time and its EXACT value (the axis is compact; the read-out is the table's)
+      { label: "At", value: (_u, v) => v === null ? "–" : readoutTime(v, span) },
+      { label: spec.label, stroke: theme.mark, width: bars ? 0 : 2, ...(bars ? { fill: theme.mark, paths: uPlot.paths.bars({ size: [0.7, 48], gap: 2 }) } : {}),
+        points: { show: false }, value: (_u, v) => v === null ? "–" : fmt(v) },
+    ],
+  };
+}
+
+/** A series chart's plot, in px (its live read-out is under it). */
+const SERIES_HEIGHT = 160;
+
+/** What a spec draws, as one string: a chart is given new data only when this changed. */
+const signature = (spec) => `${spec.kind}|${spec.x.join(",")}|${spec.y.join(",")}`;
+
+/**
+ * THE CHARTS OF A DOCUMENT, made, moved, updated and destroyed by key (see the top of this file). `load` gives uPlot's
+ * constructor (the vendored module by default; a test passes its own, or one that fails). When uPlot cannot load the
+ * page still reads whole — every number is text — so the failure is said once in the console and nothing is drawn.
+ */
+export function createCharts({ doc, win, load = () => import(UPLOT).then((m) => m.default) }) {
+  const live = new Map(); // key → { el, plot, sig }
+  let lib = null, loading = null, failed = false, last = {};
+  const holders = () => new Map([...doc.querySelectorAll("[data-chart]")].map((el) => [el.dataset.chart, el]));
+  // EACH CHART AS WIDE AS ITS HOLDER, whenever the holder's width changes — a window resized, a grid that reflowed, the
+  // sidebar become a rail — not only on the window's resize: a chart sized once at a wider holder stood out of its card
+  const watched = new Map(); // holder → key
+  const observer = typeof win.ResizeObserver === "function" ? new win.ResizeObserver((entries) => {
+    for (const e of entries) {
+      const key = watched.get(e.target), c = key === undefined ? undefined : live.get(key);
+      if (c !== undefined && c.width !== size(c.el, last[key]?.kind).width) fit(key, c);
+    }
+  }) : null;
+  const watch = (key, el) => { if (observer !== null && watched.get(el) !== key) { observer.observe(el); watched.set(el, key); } };
+  const unwatch = (el) => { if (observer !== null && watched.has(el)) { observer.unobserve(el); watched.delete(el); } };
+  const fit = (key, c) => { const s = size(c.el, last[key]?.kind); c.plot.setSize(s); c.width = s.width; };
+  const destroy = (key) => { const c = live.get(key); if (c !== undefined) { unwatch(c.el); c.plot.destroy(); } live.delete(key); };
+  // a holder is shown (`drawn`: app.css hides one not drawn, so it takes no room without uPlot) before it is measured;
+  // a sparkline fills its holder, a series chart is its plot's height and its read-out under it
+  const show = (el) => { el.classList?.add("drawn"); return el; };
+  const size = (el, kind) => ({ width: Math.max(40, Math.floor(el.clientWidth || 200)), height: kind === "spark" ? Math.max(24, Math.floor(el.clientHeight || 48)) : SERIES_HEIGHT });
+  function draw(specs) {
+    const at = holders();
+    // a chart whose key, data or holder is gone is destroyed: a rewrite of the part replaced its holder, and nothing else holds it
+    for (const key of [...live.keys()]) if (!drawable(specs[key]) || !at.has(key)) destroy(key);
+    const theme = themeOf(doc, win);
+    for (const [key, spec] of Object.entries(specs)) {
+      const el = at.get(key);
+      if (!drawable(spec) || el === undefined) continue;
+      const c = live.get(key);
+      if (c === undefined) {
+        const { width, height } = size(show(el), spec.kind);
+        live.set(key, { el, width, plot: new lib(chartOptions(spec, theme, width, height, lib), [spec.x, spec.y], el), sig: signature(spec) });
+        watch(key, el);
+        continue;
+      }
+      // the part was written again: the same chart, moved into the new holder
+      if (c.el !== el) { unwatch(c.el); show(el).appendChild(c.plot.root); c.el = el; fit(key, c); watch(key, el); }
+      const sig = signature(spec);
+      if (sig !== c.sig) { c.plot.setData([spec.x, spec.y]); c.sig = sig; }
+    }
+  }
+  return {
+    /** Draw these specs where their holders are (the shell calls it after each write); true once uPlot is there. */
+    async mount(specs) {
+      last = specs;
+      if (failed) return false;
+      if (lib === null) {
+        loading ??= load().then((l) => { lib = l; }, (e) => {
+          // tolerated: the charts are an addition over text the page already says; said once, then never tried again
+          failed = true;
+          win.console?.warn?.(`the page's charts are not drawn (its numbers are in its tables): ${e?.message ?? e}`);
+        });
+        await loading;
+        if (lib === null) return false;
+      }
+      draw(last);
+      return true;
+    },
+    /** The theme changed (light ↔ dark): every chart made again in the new colours. */
+    retheme() { for (const key of [...live.keys()]) destroy(key); if (lib !== null) draw(last); },
+    /** The window was resized: each chart to its holder's size. */
+    resize() { for (const [key, c] of live) fit(key, c); },
+    /** How many charts are alive (the tests: none leaks). */
+    count: () => live.size,
+  };
+}

package/dist/src/web/index.html

@@ -6,39 +6,103 @@
 <title>Mason</title>
 <!-- no favicon request: an empty one, inline (img-src allows data:) -->
 <link rel="icon" href="data:,">
+<!-- every file Mason's own, from its allowlist (src/cli/run-server.ts PAGE_ROUTES): the fonts are app.css's, vendored -->
 <link rel="stylesheet" href="/app.css">
+<link rel="stylesheet" href="/vendor/uplot-1.6.32/uPlot.min.css">
 <script type="module" src="/app.js"></script>
 </head>
 <body>
-<header>
-  <h1>Mason</h1>
-  <p id="where" class="where"></p>
-  <p id="updated" class="updated" aria-live="polite"></p>
-</header>
+<!-- the shell (src/web/app.js): the sidebar — the project, the nav, when it was updated and the version — and the page
+     beside it. Below 1000 px the sidebar is an icon rail; below 640 px a top bar whose menu button opens the nav as a sheet -->
+<aside id="sidebar" class="sidebar">
+  <div class="side-head">
+    <button type="button" id="menu-button" class="menu-button" data-menu aria-controls="side-body" aria-expanded="false"><span id="menu-icon"></span><span class="sr">Menu</span></button>
+    <h1 class="brand"><span class="logo" aria-hidden="true"><svg viewBox="0 0 24 24" fill="currentColor" focusable="false"><path d="M3 3h8.25v5H3zM12.75 3H21v5h-8.25zM3 9.5h3.5L8 14.5H3zM8 9.5h8l-1.5 5h-5zM17.5 9.5H21v5h-5zM3 16h6v5H3zM15 16h6v5h-6z"/></svg></span><span class="brand-name">Mason</span></h1>
+    <div class="project"><p id="where" class="where"></p><span id="badge"></span></div>
+  </div>
+  <div id="side-body" class="side-body">
+    <!-- the pages: one section each, the one shown chosen by the URL's hash; the links work before the script runs, which adds their icons -->
+    <nav id="nav" class="nav" aria-label="Pages"><ul><li><a href="#overview"><span class="label">Overview</span></a></li><li><a href="#tables"><span class="label">Tables</span></a></li><li><a href="#users"><span class="label">Users</span></a></li><li class="group"><p class="group-title" id="nav-observability">Observability</p><ul aria-labelledby="nav-observability"><li><a href="#observability/queries"><span class="label">Queries</span></a></li><li><a href="#observability/usage"><span class="label">Usage</span></a></li><li><a href="#observability/syncs"><span class="label">Sync events</span></a></li></ul></li></ul></nav>
+    <div class="side-foot"><p id="updated" class="updated" aria-live="polite"></p><p id="version" class="version"></p></div>
+  </div>
+</aside>
+<div class="scrim" aria-hidden="true"></div>
+<div class="content">
 <div id="poll"></div>
 <main>
-  <section aria-labelledby="status-h">
-    <h2 id="status-h">Status</h2>
-    <div id="status"><p class="dim">Asking Mason…</p></div>
+  <section id="page-status" aria-labelledby="status-h">
+    <div class="page-head"><h2 id="status-h">Overview</h2><p class="desc">Mason syncs the tables you add from your Postgres, keeps them current, and answers analytics SQL at a Postgres URL of its own. Here: whether the synced data is ready, how to connect, and what it answered — what <code>mason status</code> says.</p></div>
+    <div id="status"><div class="loading" aria-busy="true"><p class="dim">Asking Mason…</p><span class="skeleton block"></span></div></div>
   </section>
-  <section aria-labelledby="tables-h">
-    <h2 id="tables-h">Tables</h2>
-    <p class="lead">The database's tables, as <code>mason tables</code> lists them. Add one and Mason copies it: it is added to the sources file, as <code>mason add</code> does; Remove takes it out and drops its copy, as <code>mason remove</code> does.</p>
+  <section id="page-tables" aria-labelledby="tables-h" hidden>
+    <div class="page-head"><h2 id="tables-h">Tables</h2><p class="desc">The database's tables, as <code>mason tables</code> lists them. Add one and Mason syncs it: it is added to the sources file, as <code>mason add</code> does; Remove takes it out and drops its synced data, as <code>mason remove</code> does.</p></div>
+    <div id="tables-cards"></div>
+    <!-- each label in a field with its control, as the request filters are: on a phone a field is a row, never a label left at a line's end -->
+    <div class="toolbar">
+      <div class="field grow"><label for="tables-filter">Search the tables</label>
+        <input type="search" id="tables-filter" autocomplete="off" spellcheck="false" placeholder="orders"></div>
+      <div class="field"><label for="tables-show">Show</label>
+        <select id="tables-show"><option value="all">All</option><option value="added">Added</option><option value="failed">Failed</option><option value="not-added">Not added</option></select></div>
+    </div>
     <div id="tables"></div>
   </section>
-  <section aria-labelledby="users-h">
-    <h2 id="users-h">Users</h2>
-    <p class="lead">A user of the Postgres API: a name and a password that does not expire, for a BI tool or an app. The same users as <code>mason user</code>.</p>
-    <div id="added"></div>
-    <form id="add-user" autocomplete="off">
+  <section id="page-queries" aria-labelledby="queries-h" hidden>
+    <!-- an Observability view's head is ONE row: its title left, the time range the three share right (src/web/app.js renderSubnav) -->
+    <div class="page-head"><div class="head-row"><h2 id="queries-h">Queries</h2><div id="range-queries" class="head-range"></div></div><p class="desc">Every statement the Postgres API answered, refused or cancelled, as <code>mason logs --requests</code> lists them, newest first, over the time range. Who is connected, what runs now and the range's numbers are on <a href="#observability/usage">Usage</a>.</p></div>
+    <p class="lead">Since, when given, is used instead: an age (30m, 2h, 7d) or an ISO 8601 date or time with its zone. A statement that reads no synced table (select 1, SET, SHOW, a BI tool's catalog queries) is answered but not listed.</p>
+    <form id="request-filters" class="toolbar" autocomplete="off">
+      <div class="field"><label for="rq-status">Status</label>
+        <select id="rq-status" name="status"><option value="">All</option><option value="completed">Completed</option><option value="refused">Refused</option><option value="failed">Failed</option><option value="refused-or-failed">Refused or failed</option><option value="cancelled">Cancelled</option></select></div>
+      <div class="field"><label for="rq-since">Since</label>
+        <input id="rq-since" name="since" placeholder="2h" spellcheck="false"></div>
+      <div class="field"><label for="rq-user">User</label>
+        <input id="rq-user" name="user" spellcheck="false"></div>
+      <div class="field"><label for="rq-client">Client</label>
+        <input id="rq-client" name="client" spellcheck="false"></div>
+      <div class="field grow"><label for="rq-search">Statement has</label>
+        <input id="rq-search" name="search" type="search" maxlength="200" spellcheck="false" placeholder="orders"></div>
+      <label class="check" for="rq-slow"><input type="checkbox" id="rq-slow" name="slow"> Slow (1 s or more)</label>
+      <div class="actions"><button type="submit" class="primary">Filter</button>
+        <button type="button" data-clear-filters>Clear</button></div>
+    </form>
+    <div id="request-log"></div>
+  </section>
+  <section id="page-users" aria-labelledby="users-h" hidden>
+    <div class="page-head"><h2 id="users-h">Users</h2><p class="desc">A user is the name and password psql, a BI tool or your app connects to Mason with; it does not expire. The same users as <code>mason user</code>.</p></div>
+    <form id="add-user" class="formcard" autocomplete="off">
       <label for="user-name">Name</label>
       <input id="user-name" name="name" required placeholder="metabase" spellcheck="false" autocapitalize="off">
-      <button type="submit">Add a user</button>
+      <button type="submit" class="primary">Add a user</button>
     </form>
     <div id="action"></div>
+    <div id="added"></div>
+    <div id="users-connect"></div>
     <div id="users"></div>
   </section>
+  <section id="page-usage" aria-labelledby="usage-h" hidden>
+    <div class="page-head"><div class="head-row"><h2 id="usage-h">Usage</h2><div id="range-usage" class="head-range"></div></div><p class="desc">What the Postgres API answered over the time range — who connected, what ran, the SQL it refused as unsupported — and each synced table's size, as <code>mason status</code>, <code>mason logs</code> and <code>mason usage</code> say them. A client or a card leads to its statements on <a href="#observability/queries">Queries</a>.</p></div>
+    <div id="usage-kpis"></div>
+    <div id="usage-charts"></div>
+    <h3 id="usage-connected-h">Connected now</h3>
+    <div id="usage-connected"></div>
+    <h3 id="usage-running-h">Running now</h3>
+    <p class="lead" id="usage-running-lead"></p>
+    <div id="usage-running"></div>
+    <h3>Unsupported SQL</h3>
+    <div id="unsupported"></div>
+    <h3>Over time</h3>
+    <div id="usage-hourly"></div>
+    <h3>Each synced table's own size</h3>
+    <div id="usage-sizes"></div>
+  </section>
+  <section id="page-syncs" aria-labelledby="syncs-h" hidden>
+    <div class="page-head"><div class="head-row"><h2 id="syncs-h">Sync events</h2><div id="range-syncs" class="head-range"></div></div><p class="desc">The sync's events — each first sync, each failure and recovery, each sync asked by hand — as <code>mason logs --events</code> lists them, and the run's own log behind a details. A scheduled poll that succeeds is not listed: the last one's result is each table's last sync (mason status, the Tables page's Last sync).</p></div>
+    <div class="toolbar"><div id="syncs-filters" class="fields"></div><label class="check" for="syncs-failures-only"><input type="checkbox" id="syncs-failures-only"> Failures only</label></div>
+    <div id="syncs-events"></div>
+    <div id="syncs-run"></div>
+  </section>
 </main>
-<noscript><p>This page needs JavaScript. <code>mason status</code>, <code>mason tables</code> and <code>mason user list</code> say the same in a terminal.</p></noscript>
+</div>
+<noscript><p>This page needs JavaScript. <code>mason status</code>, <code>mason tables</code>, <code>mason user list</code>, <code>mason logs</code> and <code>mason usage</code> say the same in a terminal.</p></noscript>
 </body>
 </html>

package/dist/src/web/pages/queries.js

@@ -0,0 +1,192 @@
+/**
+ * THE QUERIES VIEW (#observability/queries, a view of the Observability group; `#queries`, its old address, lands here):
+ * the request log (`mason logs --requests`, GET /api/requests) and nothing else — who is connected, what runs and the
+ * range's numbers are Usage's (src/web/pages/usage.js). A table (a status dot and word, each row expanding in place and
+ * staying open across polls), newest first, filtered by status, slow (SLOW_MS or more), a piece of the statement's text,
+ * since, user and client — since is the shared time range unless the filter names its own — and paged back by Older;
+ * Started, Duration and Rows sort the page shown (the pages follow the log's order by start: a sort of the whole log
+ * would need a cursor per order). Read every 5 s while the range is Now, once when another is chosen. A statement is one
+ * or two lines in its cell, its title at most TITLE_MAX characters, and its expanded row the first STATEMENT_MAX of it.
+ * The words are the commands': a request's duration in ms, its error, the empty log's sentence — and, while the log is
+ * empty and unfiltered, how to connect (`renderConnect`), so the first statement is a paste away. Usage's rows lead here
+ * filtered (`route`: `?user=`, `?client=`, `?slow=1`, `?status=`).
+ */
+import { msText, agoText, bytesText, esc, firstLine, n, empty, renderFailure, rowsHtml, utcText, utcMsText, details, createOpenSet, status,
+  clip, capped, TITLE_MAX, sortTh, sortedBy, nextSort, RANGES, DEFAULT_RANGE, clientText, renderConnect, copyClick, UNLISTED_STATEMENTS, statementCell, rangeEvery } from "../shared.js";
+
+const STATE = "/api/state";
+const NEWEST_EVERY_MS = 5000;
+/** The newest page while a search is set: a search reads every statement's text of the range (7 days of a busy log,
+ *  ~0.6 s a read), so it is read every 30 s, not 5 — said under the log (SEARCH_NOTE). */
+const SEARCH_EVERY_MS = 30_000;
+export const SEARCH_NOTE = `Refreshed every ${SEARCH_EVERY_MS / 1000} s while searching: a search reads the text of every statement in the range.`;
+/** The most of a statement (or an error) an expanded row writes, in characters. */
+const STATEMENT_MAX = 16 * 1024;
+
+/** The status column's dot and word, by the ledger's `outcome` (src/api/request-log.ts `outcomeOf`): the word
+ *  `mason logs --requests` prints, coloured as its line is (src/cli/commands.ts `requestLine`). A refusal (a statement
+ *  Mason answers as designed, as a Postgres would refuse it) is Refused, never Failed (Mason's or the machine's fault). */
+const OUTCOME = { ok: ["ok", "Completed"], refused: ["warn", "Refused"], failed: ["bad", "Failed"], cancelled: ["warn", "Cancelled"] };
+
+/** The columns of the request log's table: its details row spans them all; the sortable ones by their sort key. */
+const REQUEST_COLUMNS = [["Status"], ["Query id"], ["Started", "started"], ["Duration", "duration", "num"], ["User"], ["Client"], ["Rows", "rows", "num"], ["Statement"]];
+/** What each sortable column sorts by. */
+const REQUEST_SORTS = { started: (r) => Date.parse(r.startedAt), duration: (r) => r.durationMs, rows: (r) => r.rows };
+/** The request log's order unless a header is clicked: newest first. */
+const NEWEST_FIRST = { key: "started", dir: "desc" };
+
+/**
+ * THE REQUEST LOG (`mason logs --requests --json`'s shape: { requests, keptDays, before }), newest first (the command
+ * prints the oldest of the page first; a table reads the other way): a dot and the status word, the id's first 8
+ * characters, when it started (how long ago; the UTC time is its title and in its details), the duration, user, client,
+ * rows, and the statement (cut to a line, at most two in the cell, at most TITLE_MAX characters its title) over its
+ * error's first line. Each row EXPANDS (its id is the toggle: a `details` keyed by the request's id, `isOpen` the page's
+ * open set, so a poll that rewrites the log keeps it open) into the whole id, when it started and ended, the bytes sent,
+ * the statement and the error — each the first STATEMENT_MAX characters, and said so when cut. `sort` ({ key, dir }:
+ * started, duration or rows) orders the page shown, said under it when it is not the newest first. **Older** when the
+ * page has an older one (`before`), **Newest** when the page shown is not the newest. `filtered`: the empty sentence
+ * names the filters, as the command's does; `span` the range's words (the empty log's). `now` is the page's clock.
+ */
+export function renderRequests(page, { paged = false, filtered = false, isOpen = () => false, now = Date.now(), sort = NEWEST_FIRST, span = "", connect = "" } = {}) {
+  const older = page.before !== null && page.before !== undefined;
+  const nav = paged || older ? `<div class="paging">${paged ? `<button type="button" data-newest>Newest</button>` : ""}${older ? `<button type="button" data-older>Older</button>` : ""}</div>` : "";
+  if (!page.requests.length) {
+    const days = `${page.keptDays} day${page.keptDays === 1 ? "" : "s"}`;
+    // nothing asked yet (no filter, the newest page): how to connect, so the first statement is a paste away
+    return empty(`No ${filtered ? "request that passes the filters" : "request"} ${span ? `in ${span} (the request log keeps ${days}: MASON_HISTORY_DAYS)` : `in the last ${days} (MASON_HISTORY_DAYS)`}.`) +
+      // a first statement looked for and not there: what the log does not list (a select 1 typed to test the connection)
+      (filtered || paged ? "" : `<p class="dim unlisted">${esc(UNLISTED_STATEMENTS)}.</p>${connect}`) + nav;
+  }
+  const newest = [...page.requests].reverse();
+  const list = sort.key === "started" && sort.dir === "desc" ? newest : sortedBy(newest, REQUEST_SORTS[sort.key] ?? REQUEST_SORTS.started, sort.dir);
+  const rows = list.map((r) => {
+    const key = `request:${r.requestId}`;
+    const open = isOpen(key);
+    const error = r.sqlstate === null && !r.message ? "" : `<div class="err"${r.sqlstate ? ` title="SQLSTATE ${esc(r.sqlstate)}"` : ""}><span title="${esc(clip(r.message ?? "", TITLE_MAX))}">${esc(clip(firstLine(r.message ?? ""), 300))}</span></div>`;
+    const [kind, word] = OUTCOME[r.outcome] ?? [undefined, String(r.outcome)];
+    const row = `<tr class="s-${esc(word.toLowerCase())}"><td>${status(kind, word)}</td>` +
+      `<td class="id">${details(key, r.requestId.slice(0, 8), "", open)}</td>` +
+      `<td class="when"><time data-tick datetime="${esc(r.startedAt)}" title="${esc(utcText(r.startedAt))} UTC">${esc(agoText(r.startedAt, now))}</time></td>` +
+      `<td class="num">${esc(msText(r.durationMs))}</td><td><span class="clip" title="${esc(r.user || r.tokenName)}">${esc(r.user || (r.tokenName ? `token ${r.tokenName}` : ""))}</span></td>` +
+      `<td><span class="clip" title="${esc(clientText(r.applicationName))}">${esc(clientText(r.applicationName))}</span></td>` +
+      `<td class="num">${r.rows === null ? "" : esc(n(r.rows))}</td><td class="stmt-cell">${statementCell(r.query)}${error}</td></tr>`;
+    // the rest of a request is its expanded row: the whole id, when it started and ended, the bytes sent, the statement and error (each capped)
+    const stmt = capped(r.query || "(no statement)", STATEMENT_MAX, "mason logs --requests --json");
+    const err = capped(r.message ?? "", STATEMENT_MAX, "mason logs --requests --json");
+    // its body is as wide as the row and no wider (`.detail-body`): a long statement scrolls in its box, never widens a column
+    const more = open ? `<tr class="detail"><td colspan="${REQUEST_COLUMNS.length}"><div class="detail-body">${rowsHtml([["Query id", r.requestId], ["Started (UTC)", utcMsText(r.startedAt)], ["Ended (UTC)", utcMsText(r.endedAt)], ["Bytes sent", r.bytesSent === null ? "" : bytesText(r.bytesSent)]])}` +
+      `<pre class="stmt">${esc(stmt.text)}</pre>${stmt.cut ? `<p class="dim cut">${esc(stmt.cut)}${r.queryTruncated ? " (as the log kept it)" : ""}</p>` : r.queryTruncated ? `<p class="dim cut">the request log kept the statement cut</p>` : ""}` +
+      `${r.message ? `<pre class="error">${esc(r.sqlstate ? `${r.sqlstate} ` : "")}${esc(err.text)}</pre>${err.cut ? `<p class="dim cut">${esc(err.cut)}</p>` : ""}` : ""}</div></td></tr>` : "";
+    return row + more;
+  }).join("");
+  const sortNote = sort.key === "started" && sort.dir === "desc" ? ""
+    : `<p class="dim sort-note">Sorted by ${esc(sort.key === "started" ? "start" : sort.key)}, ${sort.dir === "asc" ? "lowest" : "highest"} first, within the ${n(page.requests.length)} rows of this page: Older and Newest page by start time.</p>`;
+  return `<div class="scroll"><table class="requests"><thead><tr>${REQUEST_COLUMNS.map(([c, key, cls]) => key ? sortTh("requests", key, c, sort, cls) : `<th scope="col">${c}</th>`).join("")}</tr></thead>` +
+    `<tbody>${rows}</tbody></table></div>${sortNote}${nav}`;
+}
+
+/** The status filter's choices as the server's `outcome` list (src/api/request-log.ts): Completed is ok, Refused the
+ *  statement's own fault, Failed Mason's or the machine's, Cancelled a cancel or a timeout (57014); Refused or failed is
+ *  both, the count the Overview's query errors and Usage's Failed card lead here with. */
+const STATUS_OUTCOMES = { completed: "ok", refused: "refused", failed: "failed", "refused-or-failed": "refused,failed", cancelled: "cancelled" };
+
+/** The filters as they are before any is set. */
+const NO_FILTERS = { status: "", since: "", user: "", client: "", slow: false, search: "" };
+
+/** The path of one view of the request log: its filters as the server reads them (it judges since and search), since the
+ *  range's (`range`, a key of RANGES) unless the filter names its own, and the cursor of an older page. */
+export function requestsPath(filters, before, range = DEFAULT_RANGE) {
+  const p = new URLSearchParams();
+  if (STATUS_OUTCOMES[filters.status]) p.set("outcome", STATUS_OUTCOMES[filters.status]);
+  p.set("since", filters.since || (RANGES[range] ?? RANGES[DEFAULT_RANGE]).since);
+  for (const k of ["user", "client"]) if (filters[k]) p.set(k, filters[k]);
+  if (filters.slow) p.set("slow", "1");
+  if (filters.search) p.set("search", filters.search);
+  if (before) p.set("before", before);
+  return `/api/requests?${p.toString()}`;
+}
+
+export const page = {
+  id: "queries",
+  hash: "observability/queries",
+  parent: "observability",
+  title: "Queries",
+  create(ctx) {
+    // the request rows' details open, by request id (createOpenSet): they stay open across a poll
+    const opened = createOpenSet();
+    const m = { filters: { ...NO_FILTERS }, before: null, open: opened.open, sort: NEWEST_FIRST };
+    const path = () => requestsPath(m.filters, m.before, ctx.range());
+    const filtered = () => Object.values(m.filters).some((v) => v !== "" && v !== false);
+    /** The form's controls showing the filters (a route sets them, not a person). */
+    const showFilters = (doc) => {
+      const form = doc?.getElementById?.("request-filters");
+      if (!form?.elements) return;
+      for (const k of ["status", "since", "user", "client", "search"]) if (form.elements[k]) form.elements[k].value = m.filters[k];
+      if (form.elements.slow) form.elements.slow.checked = m.filters.slow;
+    };
+    const actions = {
+      /** Show the requests that pass these filters, from the newest. */
+      async filterRequests(filters) {
+        m.filters = { ...NO_FILTERS, ...filters };
+        m.before = null;
+        await ctx.refresh([path()]);
+      },
+      /** The page before this one: the cursor the page shown answered with. Not read again while shown. */
+      async olderRequests() {
+        const before = ctx.read(path())?.body?.before;
+        if (typeof before !== "string") return;
+        m.before = before;
+        await ctx.refresh([path()]);
+      },
+      async newestRequests() {
+        m.before = null;
+        await ctx.refresh([path()]);
+      },
+      /** A sortable header clicked: the page shown in that order (the same column again turns it round). */
+      sortRequests(key) { m.sort = nextSort(m.sort, key, "desc"); },
+    };
+    return {
+      model: m,
+      // the newest page of the log every 5 s while the range is Now (30 s while a search is set), once when another
+      // range is chosen; an older page only when first asked. The state (how to connect, when the log is empty) every 30 s
+      reads: () => [{ path: path(), everyMs: m.before !== null ? Infinity : rangeEvery(ctx.range(), m.filters.search ? SEARCH_EVERY_MS : NEWEST_EVERY_MS) }, { path: STATE, everyMs: 30_000 }],
+      actions,
+      view() {
+        const log = ctx.read(path());
+        const s = ctx.read(STATE)?.body;
+        return {
+          "request-log": (log?.failure ? renderFailure(log.failure) : "") + (log?.body ? renderRequests(log.body, { paged: m.before !== null, filtered: filtered(), isOpen: opened.has, now: ctx.now().getTime(), sort: m.sort,
+            span: m.filters.since ? "" : (RANGES[ctx.range()] ?? RANGES[DEFAULT_RANGE]).span, connect: renderConnect(s?.postgres, { first: true, table: s?.tables?.find((t) => t.added && t.copy?.phase === "done")?.table ?? null }) }) : "") +
+            (log?.body && m.filters.search && m.before === null ? `<p class="dim refresh-note">${esc(SEARCH_NOTE)}</p>` : ""),
+        };
+      },
+      toggle: (target) => opened.toggle(target),
+      submit(form) {
+        if (form.id !== "request-filters") return null;
+        const value = (k) => form.elements[k]?.value?.trim() ?? "";
+        return actions.filterRequests({ status: value("status"), since: value("since"), user: value("user"), client: value("client"), slow: form.elements.slow?.checked === true, search: value("search") });
+      },
+      /** `#observability/queries?slow=1`, `?status=refused-or-failed`,`?user=metabase&client=Metabase` (where the Overview's cards
+       *  and Usage's rows lead): those filters, from the newest, and the form's controls showing them. Nothing to do for a
+       *  hash without them (a change of range keeps the filters). */
+      route(params, { doc } = {}) {
+        if (!["slow", "status", "user", "client"].some((k) => params[k] !== undefined)) return null;
+        m.filters = { ...NO_FILTERS, slow: params.slow === "1", status: Object.hasOwn(STATUS_OUTCOMES, params.status ?? "") ? params.status : "",
+          user: params.user ?? "", client: params.client ?? "" };
+        m.before = null;
+        showFilters(doc);
+        return true;
+      },
+      click(d, button, env) {
+        const { doc } = env;
+        // Connect's Copy buttons, in the request log's empty state
+        if (d.copy !== undefined) return copyClick(d, button, env);
+        if (d.sortTable === "requests") return actions.sortRequests(d.sortKey) ?? true;
+        if (d.older !== undefined) return actions.olderRequests();
+        if (d.newest !== undefined) return actions.newestRequests();
+        if (d.clearFilters !== undefined) { doc.getElementById("request-filters")?.reset?.(); return actions.filterRequests({}); }
+        return null;
+      },
+    };
+  },
+};