@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/lib/secret-mask.js

@@ -0,0 +1,142 @@
+/**
+ * AN ERROR'S WORDS, AS MASON REPEATS THEM (issue 599: the engine's error repeated the connection string, `password='…'`
+ * included, into the log, the ledger, `mason status` and the web page).
+ *
+ * WHERE THE PASSWORD CAN STILL REACH AN ERROR decides how wide this is. The engine is given the password in ONE
+ * statement, the TEMPORARY SECRET (src/duck/sync.ts `sourceSecretSql`), whose own error is never repeated (its code
+ * alone); the ATTACH's path holds no credential (`attachPath`), so the extension's `Unable to connect to Postgres at
+ * "<path>"` cannot hold it; the sync's own Postgres client sends it only inside its auth messages (src/cdc/pg-wire.ts),
+ * never in a string. So no error the sync meets holds the password, and the one form a regression would bring back is
+ * the one the old string leaked: a libpq `password=` keyword's value. That alone is masked.
+ *
+ * NEVER A SUBSTRING OF THE PASSWORD (the reviews of PR 620): an error's words carry identifiers — a table's name, the
+ * user's, the database's, a slot's, a row's value — and a mask that cut the password out of them showed where it sat
+ * (`public.****_archive` under `orders2024`, `for user "****"` under a password equal to the user's name), while a
+ * branch matching the words flipped (a catch-up's wider numeric, a ROLLBACK's `no transaction is active`). A
+ * `password=` value is no identifier, so masking it shows nothing of the password and changes no word a branch reads;
+ * and no branch reads these words at all: a decision reads `messageOf`, the raw words, which are never shown.
+ * tests/secret-mask.test.ts holds both rules over src/duck/sync.ts and src/duck/stream.ts.
+ */
+/** What a masked value reads as. */
+export const MASKED = "****";
+/** libpq's `password=` keyword and its value: quoted (`'…'`, a `\` escaping the next character, to the closing quote
+ *  or the text's end, a `\` that ends the text included: issue 621, a text cut there was returned whole) or bare (to the
+ *  next space or quote); any case, spaces allowed around the `=` as libpq allows */
+const PASSWORD_KEYWORD = /\b(password\s*=\s*)(?:'(?:[^'\\]|\\[\s\S]?)*(?:'|$)|[^\s'"]+)/gi;
+/** `text` with every `password=` keyword's value masked, and nothing else changed: the leaked form alone, safe for any
+ *  stored free text (an error's words, the ledger read back, the scrub at open). */
+export function maskPasswordKeyword(text) {
+    return text.replace(PASSWORD_KEYWORD, (_m, key) => `${key}${MASKED}`);
+}
+/** The keyword with its value not begun at the text's end (`password`, `password =`): what follows on the next line may
+ *  be its value, as libpq allows a newline among the spaces around the `=` */
+const KEYWORD_OPEN = /\bpassword\s*(?:=\s*)?$/i;
+/** Whether a quoted value (its opening `'` first) has its closing quote, by the keyword's own escapes */
+function closed(value) {
+    let escaped = false;
+    for (let i = 1; i < value.length; i++) {
+        const c = value[i];
+        if (escaped)
+            escaped = false;
+        else if (c === "\\")
+            escaped = true;
+        else if (c === "'")
+            return true;
+    }
+    return false;
+}
+/**
+ * A TEXT READ A LINE AT A TIME, MASKED AS `maskPasswordKeyword` MASKS IT WHOLE (issue 621: a log file an older Mason
+ * wrote, read by `mason logs`, holds the leaked form in its lines): the same keyword, the same value, masked the same way,
+ * and nothing else changed — never a substring of the password (the reviews of PR 620: an identifier holding it is
+ * structure, and a mask cut into it showed where the password sat).
+ *
+ * A LINE IS ITS UNIT, AND AN ENTRY ITS BOUND. A log entry is a line at the margin and the indented lines under it
+ * (src/lib/log.ts `textEntry`), so a value can run on past its line only inside its entry: a quote open at a line's end
+ * masks the next indented lines to its closing quote (a password holding a newline), and a keyword at a line's end
+ * (`password`, `password =`) takes its value from the next indented line. A line at the margin, or a blank one, starts
+ * afresh: a quote an older Mason's line left open (a message cut off) masks its own entry, never the rest of the file.
+ * Each line's answer is decided by it and the lines before it, so a reader releases a line as soon as it has it whole,
+ * whatever its own chunks (src/lib/log-read.ts), and the answer is the same for every way the file is cut.
+ */
+export class PasswordLineMask {
+    /** what the previous line left open: a quoted value (to its closing quote), or the keyword with its value not begun */
+    open = null;
+    /** A line not ended yet, masked as it stands, the state left as it was: what a follow shows of a line still being
+     *  written (src/lib/log-read.ts `follow`), the whole line read by `line` once its newline comes. */
+    peek(raw) {
+        const open = this.open;
+        try {
+            return this.line(raw);
+        }
+        finally {
+            this.open = open;
+        }
+    }
+    /** One line (no newline), masked. */
+    line(raw) {
+        if (raw.trim() === "" || /^\S/.test(raw))
+            this.open = null; // a new entry: nothing carries into it
+        const open = this.open;
+        this.open = null;
+        if (open !== null && "quote" in open) {
+            // the value runs on from the line before: masked to its closing quote (the newline ended any escape), the rest read as any line
+            const indent = /^\s*/.exec(raw)[0];
+            let escaped = false;
+            for (let i = indent.length; i < raw.length; i++) {
+                const c = raw[i];
+                if (escaped)
+                    escaped = false;
+                else if (c === "\\")
+                    escaped = true;
+                else if (c === "'")
+                    return `${indent}${MASKED}${this.alone(raw.slice(i + 1))}`;
+            }
+            this.open = { quote: true };
+            return `${indent}${MASKED}`;
+        }
+        if (open !== null) {
+            // the keyword ended the line before: read with it, and its own text taken off again (the key is kept as written)
+            return this.alone(`${open.keyword}\n${raw}`).slice(open.keyword.length + 1);
+        }
+        return this.alone(raw);
+    }
+    /** `text` masked whole, and what it leaves open at its end noted for the next line */
+    alone(text) {
+        let atEnd = null; // the value of a match that runs to the text's end
+        const masked = text.replace(PASSWORD_KEYWORD, (match, key, index) => {
+            if (index + match.length === text.length)
+                atEnd = match.slice(key.length);
+            return `${key}${MASKED}`;
+        });
+        const value = atEnd;
+        if (value !== null) {
+            if (value.startsWith("'") && !closed(value))
+                this.open = { quote: true };
+        }
+        else {
+            const k = KEYWORD_OPEN.exec(text);
+            if (k !== null)
+                this.open = { keyword: text.slice(k.index) };
+        }
+        return masked;
+    }
+}
+/** An error's code: a Postgres SQLSTATE or a system error's (`ECONNREFUSED`), the kind the engine names its error by
+ *  (`IO Error`), else none — what is said of an error whose words are never repeated (the secret's statement). */
+export function errorCode(e) {
+    if (e !== null && typeof e === "object" && typeof e.code === "string" && e.code !== "")
+        return e.code;
+    const m = e instanceof Error ? /^([A-Z][A-Za-z]*(?: [A-Za-z]+)* Error):/.exec(e.message) : null;
+    return m?.[1] ?? null;
+}
+/** A CAUGHT ERROR'S WORDS, AS MASON REPEATS THEM (a log line, an event, a table's `error`, an answer): its message (or,
+ *  `stack`, its stack), every `password=` value masked. Never matched by a branch: that reads `messageOf`. */
+export function errorText(e, o = {}) {
+    return maskPasswordKeyword(e instanceof Error ? (o.stack === true ? e.stack ?? e.message : e.message) : String(e));
+}
+/** A CAUGHT ERROR'S RAW WORDS, FOR A DECISION ALONE (which failure it is: a wider numeric, a transaction already ended):
+ *  never shown — said, logged or stored, an error's words are `errorText`'s. */
+export function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/src/lib/table-sync.js

@@ -5,7 +5,7 @@
  * in the same words at both entrances:
  *
  *   off               nothing after the first copy until `mason sync <table>`, which polls it once, now (the default)
- *   poll <interval>   the xmin poll every <interval>: <n>s, <n>m or <n>h, a whole number, at least 1s, at most 24h
+ *   poll <interval>   the xmin poll every <interval>: <n>s, <n>m, <n>h or <n>d, a whole number, at least 1s, at most 24h
  *   replication       the database's change log, through the project's ONE slot and publication (src/duck/stream.ts):
  *                     the publication carries the replicated tables only, and the polled ones are polled beside it
  *
@@ -34,11 +34,11 @@ export const BIG_TABLE_ROWS = 1_000_000;
 export const COSTLY_POLL_ROWS = 10_000_000;
 export const COSTLY_POLL_SECONDS = 60;
 const MODES = ["off", "poll", "replication"];
-const UNIT_SECONDS = { s: 1, m: 60, h: 3600 };
+const UNIT_SECONDS = { s: 1, m: 60, h: 3600, d: 86_400 };
 /** the units a person may write for one of ours, said back as the one to write */
 const UNIT_WORDS = {
     s: "s", sec: "s", secs: "s", second: "s", seconds: "s", m: "m", min: "m", mins: "m", minute: "m", minutes: "m",
-    h: "h", hr: "h", hrs: "h", hour: "h", hours: "h",
+    h: "h", hr: "h", hrs: "h", hour: "h", hours: "h", d: "d", day: "d", days: "d",
 };
 const EXAMPLES = "poll 5s, poll 5m or poll 1h";
 /** what a sync is, said where one is wrong */
@@ -52,33 +52,80 @@ export function intervalOf(seconds) {
     const s = Math.max(MIN_POLL_SECONDS, Math.round(seconds));
     return s % 3600 === 0 ? `${s / 3600}h` : s % 60 === 0 ? `${s / 60}m` : `${s}s`;
 }
-/** an interval (`<n>s|m|h`) read, or why it is not one, with the interval to write when there is one */
-function parseInterval(v) {
+/** an interval (`<n>s|m|h|d`) read, or why it is not one, with the interval to write when there is one. ONE grammar with
+ *  two entrances, each worded as it is written: a `sync:`'s `poll <interval>` and a generated table's `target_lag:`. Its
+ *  units are a command line's duration's too (`parseDuration`), which also takes a bare number of seconds: a file writes
+ *  the unit, one spelling of each interval. */
+function parseInterval(v, write = "poll ") {
     const m = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i.exec(v);
-    const how = `an interval is <n>s, <n>m or <n>h, a whole number, at least ${MIN_POLL_SECONDS}s (${EXAMPLES})`;
+    const examples = write === "" ? "5s, 5m or 1h" : EXAMPLES;
+    const how = `an interval is <n>s, <n>m, <n>h or <n>d, a whole number, at least ${MIN_POLL_SECONDS}s (${examples})`;
+    if (/^\d+$/.test(v))
+        return { problem: `${v} has no unit: write ${write}${Number(v)}s for seconds (or m, h, d)` };
     if (m === null)
         return { problem: `${JSON.stringify(v)} is not an interval: ${how}` };
     const n = Number(m[1]), word = m[2].toLowerCase();
     if (word === "ms")
-        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s (a poll scans the table whole on your database): write poll ${MIN_POLL_SECONDS}s or longer` };
+        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s${write === "" ? "" : " (a poll scans the table whole on your database)"}: write ${write}${MIN_POLL_SECONDS}s or longer` };
     const unit = UNIT_WORDS[word];
-    if (unit === undefined) {
-        const days = /^(d|day|days)$/.test(word) ? `: write poll ${intervalOf(n * 86_400)}` : "";
-        return { problem: `${v}: ${word} is not a unit of an interval — ${days ? `days are hours${days}` : how}` };
-    }
+    if (unit === undefined)
+        return { problem: `${v}: ${word} is not a unit of an interval — ${how}` };
     const seconds = n * UNIT_SECONDS[unit];
     if (!Number.isInteger(n))
-        return { problem: `${v}: an interval is a whole number — write poll ${intervalOf(seconds)}` };
+        return { problem: `${v}: an interval is a whole number — write ${write}${intervalOf(seconds)}` };
     if (seconds < MIN_POLL_SECONDS)
-        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s: write poll ${MIN_POLL_SECONDS}s or longer` };
+        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s: write ${write}${MIN_POLL_SECONDS}s or longer` };
     if (seconds > MAX_POLL_SECONDS)
-        return { problem: `${v} is over the longest interval, ${intervalOf(MAX_POLL_SECONDS)}: write poll ${intervalOf(MAX_POLL_SECONDS)}, or off with mason sync <table> run by a scheduler` };
+        return { problem: `${v} is over the longest interval, ${intervalOf(MAX_POLL_SECONDS)}: write ${write}${intervalOf(MAX_POLL_SECONDS)}${write === "" ? "" : ", or off with mason sync <table> run by a scheduler"}` };
     // the number as a number is written (`05s` is `5s`): two spellings of one interval would read as a change of sync
     const canonical = `${n}${unit}`;
     if (canonical !== v)
-        return { problem: `${JSON.stringify(v)}: write poll ${canonical}` };
+        return { problem: `${JSON.stringify(v)}: write ${write}${canonical}` };
     return { every: canonical, seconds };
 }
+/** A generated table's `target_lag:` read (src/cli/generated-files.ts): an interval alone, in the grammar and the range a
+ *  poll's takes, or what is wrong with it in the words a person fixes it from. */
+export function parseLag(v) {
+    if (typeof v !== "string" || v.trim() === "")
+        return { problem: `is ${v === null || v === undefined ? "nothing" : typeof v === "number" ? `the number ${String(v)}` : "not an interval"}: write how far behind the table may be, like 30s, 5m or 1h` };
+    return parseInterval(v.trim(), "");
+}
+/** How a duration on a command line is written: said where one is wrong, and `<duration>` in each usage. */
+export const DURATION_FORMS = "a number of seconds, or <n>s, <n>m, <n>h or <n>d (90, 30s, 10m, 1h, 7d)";
+/**
+ * A DURATION ON A COMMAND LINE, ONE GRAMMAR FOR EVERY FLAG THAT TAKES ONE (`--timeout` of mason wait, share, ui --ssh,
+ * deploy and replica create; mason usage's `--step`; the age `--since` / `--until` take, src/cli/request-filter.ts
+ * `timeOf`, which refuses a bare number as a time): a bare number is seconds, as wait, share and ui read it before; `<n>s|m|h|d`, and the words a sync's
+ * interval takes (`5 min`, `2 hours`, `7 days`), as a `sync:` interval and a `target_lag:` are written. A superset of
+ * every form each flag took before, so nothing that parsed stops parsing. The range is the flag's (`min`, `max` in
+ * seconds; over 0, unless `zero`: an age of now, `--since 0s`, and `--step 0s`, every sample, as each took it before);
+ * the caller names the flag.
+ */
+export function parseDuration(v, o = {}) {
+    const t = v.trim();
+    let seconds, every;
+    if (t !== "" && Number.isFinite(Number(t))) {
+        seconds = Number(t);
+        every = `${seconds}s`;
+    }
+    else {
+        const m = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i.exec(t);
+        const unit = m === null ? undefined : UNIT_WORDS[m[2].toLowerCase()];
+        if (m === null || unit === undefined)
+            return { problem: `${JSON.stringify(v)} is not a duration: write ${DURATION_FORMS}` };
+        seconds = Number(m[1]) * UNIT_SECONDS[unit];
+        every = `${Number(m[1])}${unit}`;
+    }
+    if (o.zero === true && seconds === 0 && !Object.is(seconds, -0))
+        return { every, seconds: 0 };
+    if (!(seconds > 0))
+        return { problem: `${JSON.stringify(v)} is not a duration over 0: write ${DURATION_FORMS}` };
+    if (o.min !== undefined && seconds < o.min)
+        return { problem: `${every} is under the shortest, ${intervalOf(o.min)}` };
+    if (o.max !== undefined && seconds > o.max)
+        return { problem: `${every} is over the longest, ${intervalOf(o.max)}` };
+    return { every, seconds };
+}
 /**
  * A `sync:` VALUE READ, or what is wrong with it in the words a person fixes it from (the key is the caller's to say):
  * the line to write, a `did you mean` for a misspelt mode, the floor for a short interval. Whether a table CAN be
@@ -171,9 +218,14 @@ function saidInTheFile(what) {
  * every one given on ONE report, one coherent way out (a publication goes with replication). Null when none is given.
  * Read from the raw command line, before the options are parsed, so a removed flag is answered as removed and never
  * as an unknown option.
+ *
+ * `--port` IS NOW `--ui-port` (issue 729: it is the web page's and the commands' port, as MASON_UI_PORT is on a server,
+ * and read as the Postgres API's): answered on the same report with the line to run — `start`, built from the flags
+ * mason start takes alone, so nothing else of the line is repeated. `sync`: a sources-file flag was given.
  */
 export function removedStartFlags(argv, top) {
-    let replication = false, poll = false, publication;
+    let replication = false, poll = false, publication, port = false;
+    const kept = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--")
@@ -188,10 +240,21 @@ export function removedStartFlags(argv, top) {
             const v = argv[i + 1];
             publication = v !== undefined && !v.startsWith("-") ? v : null;
         }
+        else if (a === "--port" || a.startsWith("--port=")) {
+            const v = a === "--port" ? argv[i + 1] : a.slice("--port=".length);
+            if (a === "--port" && v !== undefined && !v.startsWith("-"))
+                i++;
+            port = true;
+            kept.push(`--ui-port ${v !== undefined && /^\d{1,5}$/.test(v) ? v : "<n>"}`);
+        }
+        else if (a === "--attach" || a === "--self-signed-tls" || a === "--json")
+            kept.push(a);
     }
     const given = [...(replication ? ["--replication"] : []), ...(poll ? ["--poll"] : []), ...(publication !== undefined ? ["--publication"] : [])];
+    const start = port ? ["mason start", ...kept].join(" ") : "mason start";
+    const portSaid = { message: "--port is now --ui-port", why: "it is the port of the web page and the mason commands (MASON_UI_PORT on a server), never the Postgres API's (MASON_PG_PORT)" };
     if (given.length === 0)
-        return null;
+        return port ? { ...portSaid, fix: start, start, sync: false } : null;
     const t = top();
     const named = given.length === 1 ? `${given[0]} is gone` : `${given.slice(0, -1).join(", ")} and ${given.at(-1)} are gone`;
     const pub = publication === undefined ? null : topEdit(t, "publication", [publication ?? "<name>"]);
@@ -215,8 +278,10 @@ export function removedStartFlags(argv, top) {
         fix = `${edit} (${edit.startsWith("keep ") ? "every table is polled already; a table's entry may say its own"
             : "any interval: poll 5s, poll 1h; or sync: off, the default, and mason sync <table> when you need it"})`;
     }
-    return { message: `${named}: the sources file says it now`, why: saidInTheFile({ sync: replication || poll, publication: publication !== undefined }),
-        fix: `${fix}, then mason start` };
+    const why = saidInTheFile({ sync: replication || poll, publication: publication !== undefined });
+    if (!port)
+        return { message: `${named}: the sources file says it now`, why, fix: `${fix}, then mason start`, start, sync: true };
+    return { message: `${named}: the sources file says it now; ${portSaid.message}`, why: `${why}; ${portSaid.why}`, fix: `${fix}, then ${start}`, start, sync: true };
 }
 /**
  * `MASON_CHANGES` SET IS REFUSED, never run on a default (CLAUDE.md: a removed setting refuses the start, naming the

package/dist/src/web/app.js

@@ -1,5 +1,5 @@
 /**
- * THE WEB PAGE OF `mason start` (`mason ui`; docs/WEB-UI.md, and .claude/rules/web-ui.md for whoever builds it out):
+ * THE WEB PAGE OF A RUN (`mason ui`, and `mason ui --ssh` for a server's; docs/WEB-UI.md, and .claude/rules/web-ui.md for whoever builds it out):
  * the SHELL — a left sidebar (the project, then a nav of links with icons: Overview · Tables · Users, and the
  * Observability group: Queries · Usage · Logs; at its foot when it was updated and the version; an icon rail on a narrow
  * window, a menu on a phone) and one section per page, the one shown chosen by the URL's hash (`#overview`, the
@@ -52,7 +52,7 @@
  * A page is registered by its import and its place in PAGES below, its route in PAGE_ROUTES, and its section in
  * index.html.
  */
-import { esc, badge, icon, createAsk, renderFailure, updatedText, placePops, RANGES, DEFAULT_RANGE, rangeOf, rangeOffered, isLive, POLL_MS } from "./shared.js";
+import { esc, badge, icon, createAsk, overTunnel, renderFailure, updatedText, placePops, RANGES, DEFAULT_RANGE, rangeOf, rangeOffered, isLive, POLL_MS } from "./shared.js";
 import { createCharts } from "./charts.js";
 import { page as statusPage } from "./pages/status.js";
 import { page as tablesPage } from "./pages/tables.js";
@@ -74,7 +74,7 @@ export const PRESS_HOLD_MS = 2000;
 
 // every renderer the tests import from here, wherever it lives now
 export * from "./shared.js";
-export { copyingText, tableLine, keptAge, sourceRows, renderStatus } from "./pages/status.js";
+export { copyingText, tableLine, keptAge, keptWords, sourceRows, renderStatus, renderShare, createShare } from "./pages/status.js";
 export { tableFacts, addedLines, removedReport, pickBody, columnsPath, renderTableAdded, renderTablesRemoved, renderTables } from "./pages/tables.js";
 export { renderUsers, renderAdded, attributesText } from "./pages/users.js";
 export { renderRequests } from "./pages/queries.js";
@@ -176,9 +176,14 @@ function renderWhere(s) {
  * `view()` is the HTML of every part of the page, from what it knows now. Nothing here touches a document.
  */
 export function createApp(fetchFn, now = () => new Date(), shown = "status") {
-  const ask = createAsk(fetchFn);
+  const asked = createAsk(fetchFn);
   // what was read, by path: the last body, this read's failure (null when it answered), when it was asked
   const store = new Map();
+  // every answer passes here: on a server's page a failure the page words itself is the tunnel's (`overTunnel`)
+  const ask = async (path, init) => {
+    const r = await asked(path, init);
+    return "failure" in r && store.get("/api/state")?.body?.served === true ? { failure: overTunnel(r.failure) } : r;
+  };
   const first = parseHash(shown);
   const m = { shown: first.id, range: rangeOf(first.params.range), pollFailure: null, updatedAt: null, rangeReadAt: null };
   const put = (path, at, r) => {

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

@@ -20,7 +20,8 @@
 const LINKS = { tables: "#tables", failedTables: "#tables?show=failed", usage: "#observability/usage?range=24h", queries: "#observability/queries?range=24h",
   slow: "#observability/queries?slow=1&range=24h", failedQueries: "#observability/queries?status=refused-or-failed&range=24h", failedEvents: "#observability/syncs?failures=1&range=7d" };
 import { msText, bytesText, code, esc, fileSize, firstLine, n, percent, leftText, spanText, duration, entryName, streamRows, slotWarns, masonRow, sessionsRows, diskRows, restartsRows, utcText,
-  utcMinute, oneLine, clientText, eventCells, unsupportedEntry, usagePath, POLL_MS, card, cards, details, createOpenSet, skeleton, renderConnect, copyClick } from "../shared.js";
+  utcMinute, oneLine, clientText, eventCells, unsupportedEntry, usagePath, POLL_MS, card, cards, details, createOpenSet, skeleton, renderConnect, copyClick,
+  badge, button, copyable, pop, renderFailure, json } from "../shared.js";
 import { spark, seriesOf, drawable } from "../charts.js";
 
 /** How many recent errors of each kind are shown: mason status's (src/cli/commands.ts `RECENT_ERRORS`, held equal by the tests). */
@@ -62,18 +63,29 @@ export function copyingText(copied, rowsEstimate, p) {
  * current and how old its copy is (`keptAge`).
  */
 export function tableLine(t, now = Date.now()) {
-  if (t.error) return { state: "failed", fraction: 1, what: `its first sync failed: ${firstLine(t.error)}` };
+  if (t.error) return { state: "failed", fraction: 1, what: t.copy?.phase === "done" ? copiedFailedText(t, now) : `its first sync failed: ${firstLine(t.error)}` };
   if (t.copy?.phase === "copying") {
     const c = copyingText(t.copy.rowsCopied, t.rows, t.copy.progress);
     return { state: "copying", fraction: c.fraction ?? 0, what: /^\d/.test(c.text) ? `syncing ${c.text}` : c.text };
   }
   if (!t.copy) return { state: "waiting", fraction: 0, what: "waiting for its first sync to start" };
-  const age = keptAge(t, now);
+  const age = keptWords(t, now);
+  const what = `${n(t.copy.rowsCopied ?? 0)} rows · synced${t.copy.retired ? ` · ${t.copy.retired}` : ""}${age ? ` · ${age}` : ""}`;
   // a copy the poll does not keep current (it waits for its catch-up) is a warning, as mason status paints it (paintBar)
-  if ((t.kept?.by === "poll" && t.kept.pending !== undefined) || (t.kept?.by === "replication" && (t.kept.state !== "streamed" || t.kept.notRunning !== null))) {
-    return { state: "unsynced", fraction: 1, what: `${n(t.copy.rowsCopied ?? 0)} rows · synced${t.copy.retired ? ` · ${t.copy.retired}` : ""} · ${age}` };
+  // and so is one behind what its sync promises (`tables[].sync.state`, src/cli/readiness.ts behindOf), of any kind
+  if ((t.kept?.by === "poll" && t.kept.pending !== undefined) || (t.kept?.by === "replication" && (t.kept.state !== "streamed" || t.kept.notRunning !== null)) || t.sync?.state === "behind") {
+    return { state: "unsynced", fraction: 1, what };
   }
-  return { state: "done", fraction: 1, what: `${n(t.copy.rowsCopied ?? 0)} rows · synced${t.copy.retired ? ` · ${t.copy.retired}` : ""}${age ? ` · ${age}` : ""}` };
+  return { state: "done", fraction: 1, what };
+}
+
+/** What a served table's line says after `synced`, for every kind: its keeping and age, then behind (src/cli/commands.ts `keptWords`). */
+export function keptWords(t, now = Date.now()) {
+  const age = keptAge(t, now), s = t.sync;
+  if (s?.state !== "behind" || s.behindBySeconds == null) return age;
+  const why = s.behindWhy ?? "its next sync is late";
+  const by = `behind by ${duration(s.behindBySeconds)}${age !== null && age.includes(why) ? "" : `: ${why}`}`;
+  return age === null ? by : `${age} — ${by}`;
 }
 
 /** How long ago a table was synced, as `mason status` says it on its line (src/lib/table-sync.ts `agoText`, which
@@ -93,7 +105,7 @@ export function keptAge(t, now = Date.now()) {
   if (k?.by === "replication") {
     if (k.state !== "streamed") return `NOT kept current (${k.syncedAt === null ? "never synced" : `last synced ${syncedAgo(k.syncedAt, now)}`}): ${k.why ?? "it is not streamed yet"}`;
     const at = `replicated, at ${k.position}, ${k.syncedAt === null ? "not synced yet" : syncedAgo(k.syncedAt, now)}`;
-    return k.notRunning === null ? at : `${at} — NOT kept current now, the stream is not running: ${k.notRunning}`;
+    return k.notRunning === null || t.sync?.state === "behind" ? at : `${at} — NOT kept current now, the stream is not running: ${k.notRunning}`;
   }
   if (k?.by !== "poll") return null;
   const synced = k.syncedAt === null ? "never synced" : `last synced ${syncedAgo(k.syncedAt, now)}`;
@@ -102,6 +114,15 @@ export function keptAge(t, now = Date.now()) {
   return `polled every ${k.sync.every}, ${k.syncedAt === null ? "not polled yet" : `last ${syncedAgo(k.syncedAt, now)}`}`;
 }
 
+/** A served table whose sync failed, as mason status says it (src/cli/commands.ts `copiedFailedText`). */
+function copiedFailedText(t, now) {
+  const k = t.kept;
+  const reason = k?.by === "replication" ? (k.state !== "streamed" ? k.why : k.notRunning === null ? null : `the stream is not running: ${k.notRunning}`)
+    : k?.by === "poll" || k?.by === "recopy" ? k.pending ?? null : null;
+  const asOf = t.sync?.asOf ?? (k && k.by !== "generated" && k.by !== "recopy" ? k.syncedAt : null) ?? t.sync?.syncedAt ?? null;
+  return `${n(t.copy?.rowsCopied ?? 0)} rows · synced · NOT kept current, its sync failed (${asOf === null ? "never synced" : `last synced ${syncedAgo(asOf, now)}`}): ${reason ?? firstLine(t.error)}`;
+}
+
 /**
  * A COPY'S BAR, the one renderer of the Overview's "copies not finished" and the Tables page's rows: a thin rounded
  * track and a solid fill to the share drawn, its % as text at the bar's END (as `mason wait` prints it beside its bar),
@@ -162,6 +183,7 @@ export function sourceRows(s) {
           `${s.source.replication.owned ? "Mason's own, carrying them alone" : "named: read as it is, never altered"}); the others by a SELECT of their changed rows`
         : s.source.demo ? "the demo database is checked this way only"
         : "sync: replication on an entry streams that table as it happens instead")],
+    ...(s.source.textOrder ? [["Text order", s.source.textOrder]] : []),
   ];
 }
 
@@ -400,11 +422,58 @@ export function renderStatus(s, o = {}) {
   // how to connect, once a table is added: first under the cards while nothing has asked Mason anything (the last
   // day's and week's statements, read as none), else after the facts, for the next tool
   const first = isFirstConnect(o.queries);
-  const connect = added ? renderConnect(s.postgres, { first, table: s.tables.find((t) => t.added && t.copy?.phase === "done")?.table ?? null }) : "";
+  const connect = added ? renderConnect(s.postgres, { first, served: s.served === true, table: s.tables.find((t) => t.added && t.copy?.phase === "done")?.table ?? null,
+    share: renderShare(s, o.share ?? NO_SHARE, now) }) : "";
   return renderHealth(s) + renderChecklist(s, o.queries, o.users) + renderKpis(s, { ...o, now }) + (first ? connect : "") + renderProgress(s, o.open, o.shares, o.before) + renderFacts(s, now) + (first ? "" : connect) + renderStream(s, now) +
     (added ? renderQueries(o.queries) : "") + (added ? renderRecentErrors(o.events, o.requests, o.unsupported) : "");
 }
 
+// ------------------------------------------------------------------ Connect from anywhere (mason share, from the page)
+
+/** The page's share before anything was asked: what `renderShare` and the page's model start from. */
+export const NO_SHARE = Object.freeze({ phase: "none", choices: null, reads: null, role: null, opened: null, ended: null, failure: null });
+
+/** The share the page holds, as `/api/state` `share` lists it (`from: "page"`), or null. */
+export const pageShareOf = (s) => s?.share?.shares?.find((x) => x.from === "page") ?? null;
+
+/** When a free share ends, as `mason share` says it: about an hour, and the time. */
+const endsLine = (endsAt, now) => endsAt === null || endsAt === undefined ? "It ends when you Stop sharing, or when this page closes."
+  : `A free share ends within about an hour: at ${new Date(endsAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}, in about ${Math.max(0, Math.round((Date.parse(endsAt) - now) / 60_000))} minutes. Then Connect from anywhere again gives a new address and password.`;
+
+/**
+ * CONNECT FROM ANYWHERE, the Connect card's part (src/cli/page-share.ts; `mason share`'s, from the page): a pure function
+ * of the state (`s`) and the page's own model (`m`: `phase` none · asking · opening · open · ended · refused, the roles
+ * offered, the answer that opened it — the password is in it alone — and the failure). Nothing under `mason serve`.
+ */
+export function renderShare(s, m = NO_SHARE, now = Date.now()) {
+  if (s?.served === true) return "";
+  const open = pageShareOf(s);
+  const head = `<p class="connect-title share-title">Connect from anywhere</p>`;
+  const ask = button("Connect from anywhere", { shareAsk: "" }, "", { disabled: m.phase === "asking" || m.phase === "opening" });
+  const askLine = `<p class="tip" id="share-anchor">${ask} <span>For a tool in the cloud, which cannot reach this machine: a temporary public address and a password, as ${code("mason share")} opens. TLS is required of every connection.</span></p>`;
+  if (open !== null && m.phase !== "ended") {
+    const mine = m.opened !== null && m.opened.user === open.user ? m.opened : null;
+    const rows = [["Host", open.host ?? "opening…", "share-host"], ["Port", open.port === null ? "…" : String(open.port), "share-port"], ["Database", mine?.database ?? s.postgres?.database ?? "", null],
+      ["User", open.user, "share-user"], ...(mine !== null ? [["Password", mine.password, "share-password"]] : []), ["SSL mode", "require", null]];
+    return `<div class="share open" role="status">${head}<p class="headline">Shared ${badge("Public", "warn")} for <time data-tick datetime="${esc(open.openedAt)}">${esc(spanText((now - Date.parse(open.openedAt)) / 1000))}</time>` +
+      `${open.role !== null ? `, reading as the role ${esc(open.role)}` : ""}: ${esc(open.reads)}</p>` +
+      `<dl class="facts">${rows.map(([k, v, id]) => `<dt>${esc(k)}</dt><dd>${id ? copyable(id, v) : esc(v)}</dd>`).join("")}</dl>` +
+      (mine !== null ? `<p class="tip">Paste it into the tool now: the password is shown this once, is kept nowhere, and ends with the share.</p>`
+        : `<p class="tip">The password was shown once, when it opened, and is kept nowhere: Stop sharing and Connect from anywhere again for a new one.</p>`) +
+      `<p class="tip">${esc(endsLine(open.endsAt, now))} It also ends within two minutes of this page closing.</p>` +
+      `<p class="tip">${button("Stop sharing", { shareStop: open.user }, "danger")}</p></div>`;
+  }
+  if (m.phase === "opening") return `<div class="share">${head}<p class="dim" aria-busy="true">Opening a temporary public address… (up to 30 s)</p></div>`;
+  const before = m.phase === "ended" && m.ended !== null
+    ? `<p class="said">The share ended: ${esc(m.ended.why)}. Its address no longer answers, and its password no longer works.</p>`
+    : m.phase === "refused" && m.failure !== null ? renderFailure(m.failure) : "";
+  const question = m.phase !== "asking" ? "" : pop("share-anchor", m.choices === null ? `<p class="dim">Reading the roles…</p>` :
+    `<p>This opens a <strong>temporary public address</strong>: anyone with it and its password reads ${esc(m.reads ?? "what the role you choose reads")}. A free share ends within about an hour, and when this page closes.</p>` +
+    (m.choices.length > 0 ? `<label for="share-role">Read as the role</label> <select id="share-role">${m.choices.map((c) => `<option value="${esc(c.role)}"${c.role === m.role ? " selected" : ""}>${esc(`${c.role}: ${c.reads}${c.default ? " (the file's default)" : ""}`)}</option>`).join("")}</select>` : "") +
+    `<p>${button("Open the address", { shareOpen: "" }, "primary")} ${button("Cancel", { shareCancel: "", popClose: "" })}</p>`, { kind: "dialog", label: "Connect from anywhere" });
+  return `<div class="share">${head}${before}${askLine}${question}</div>`;
+}
+
 /** Nothing has asked Mason anything yet: the last day's statements were read (`/api/queries`' body), and are none. */
 export const isFirstConnect = (q) => q !== undefined && !("failure" in q) && q.queries.day.statements === 0 && q.queries.week.statements === 0;
 
@@ -427,20 +496,116 @@ export const page = {
     // the details open (a copy's whole error), by key: a poll rewrites the section, and they stay open
     const opened = createOpenSet();
     const monotone = createMonotone();
+    const share = createShare(ctx);
     return {
-      model: { open: opened.open },
+      model: { open: opened.open, share: share.m },
       reads: () => [{ path: "/api/state", everyMs: POLL_MS }, ...SLOWER.map((path) => ({ path, everyMs: 30_000 })), { path: HOURLY, everyMs: 60_000 }],
-      actions: {},
+      actions: share.actions,
+      afterRead: () => share.afterRead(ctx.read("/api/state")?.body),
+      input: (target) => share.input(target),
       view() {
         const st = ctx.read("/api/state");
         if (!st?.body) return { status: st?.failure ? "" : skeleton(4) };
         const [queries, events, requests, unsupported, users] = SLOWER.map((p) => asRequest(ctx.read(p)));
-        return { status: renderStatus(st.body, { now: ctx.now().getTime(), queries, events, requests, unsupported, users, usage: ctx.read(HOURLY)?.body, open: opened.has, shares: monotone.of(st.body), before: monotone.before }) };
+        return { status: renderStatus(st.body, { now: ctx.now().getTime(), queries, events, requests, unsupported, users, usage: ctx.read(HOURLY)?.body, open: opened.has, shares: monotone.of(st.body), before: monotone.before, share: share.m }) };
       },
       toggle: (target) => opened.toggle(target),
-      // Connect's Copy buttons
-      click: (d, button, env) => copyClick(d, button, env),
+      // Connect's Copy buttons, and Connect from anywhere's
+      click: (d, button, env) => share.click(d) ?? copyClick(d, button, env),
       charts: () => sparkSpecs(ctx.read(HOURLY)?.body),
     };
   },
 };
+
+/** What a page beats with, when the answer that opened the share does not say (src/cli/page-share.ts BEAT_MS). */
+const BEAT_MS = 15_000;
+
+/**
+ * THE PAGE'S SIDE OF CONNECT FROM ANYWHERE (src/cli/page-share.ts has why each choice): ask once, open, BEAT while the
+ * share is open — on a timer of its own, which runs while the tab is hidden (the poll does not: the person is in their
+ * tool's tab, pasting) —, Stop sharing. The password is in `m.opened` alone, the page's memory, and is dropped the moment
+ * the share is seen ended. `ctx.timers` is a test's clock; a browser's own otherwise.
+ */
+export function createShare(ctx) {
+  const m = { ...NO_SHARE };
+  const timers = ctx.timers ?? globalThis;
+  let beating = null;
+  const stopBeats = () => { if (beating !== null) { timers.clearInterval(beating.id); beating = null; } };
+  const ended = (user, why) => { stopBeats(); m.opened = null; m.phase = "ended"; m.ended = { user, why }; };
+  const beat = async () => {
+    if (beating === null) return;
+    const user = beating.user;
+    const r = await ctx.ask(`/api/share/${encodeURIComponent(user)}/beat`, json("POST"));
+    if ("failure" in r && r.failure.code === "not_found" && beating?.user === user) { ended(user, r.failure.message.replace(/^.*?; it ended: /, "")); await ctx.refresh(["/api/state"]); }
+  };
+  const startBeats = (user, everyMs = BEAT_MS) => {
+    if (beating?.user === user) return;
+    stopBeats();
+    beating = { user, id: timers.setInterval(() => { void beat(); }, everyMs) };
+  };
+  const actions = {
+    /** Connect from anywhere: what a share would read, then the question */
+    async shareAsk() {
+      Object.assign(m, NO_SHARE, { phase: "asking" });
+      const r = await ctx.ask("/api/share/choices");
+      if (m.phase !== "asking") return;
+      if ("failure" in r) { m.phase = "refused"; m.failure = r.failure; return; }
+      m.choices = r.body.choices;
+      m.reads = r.body.reads ?? null;
+      m.role = r.body.choices.find((c) => c.default)?.role ?? r.body.choices[0]?.role ?? null;
+    },
+    shareCancel() { Object.assign(m, NO_SHARE); },
+    shareRole(role) { if (m.choices?.some((c) => c.role === role)) m.role = role; },
+    /** the person said yes: the run opens the share (confirmed), and its one answer carries the password */
+    async shareOpen() {
+      if (m.phase !== "asking" || m.choices === null) return;
+      const role = m.choices.length > 0 ? m.role : null;
+      Object.assign(m, { phase: "opening", failure: null });
+      const r = await ctx.ask("/api/share", json("POST", { from: "page", confirmed: true, ...(role !== null ? { role } : {}) }));
+      if ("failure" in r) { m.phase = "refused"; m.failure = r.failure; return; }
+      Object.assign(m, { phase: "open", opened: { ...r.body, seen: false } });
+      startBeats(r.body.user, r.body.beatMs);
+      await ctx.refresh(["/api/state"]);
+    },
+    async shareStop(user) {
+      const r = await ctx.ask(`/api/share/${encodeURIComponent(user)}`, json("DELETE"));
+      if ("failure" in r && r.failure.code !== "not_found") { m.phase = "refused"; m.failure = r.failure; return; }
+      ended(user, "Stop sharing, on this page");
+      await ctx.refresh(["/api/state"]);
+    },
+    shareBeat: beat,
+  };
+  return {
+    m,
+    actions,
+    /** after each read of the state: a share of the page's open is beaten (a reload's too); the one this page opened,
+     *  once listed and now gone, ended — said with the run's why, and its password dropped */
+    afterRead(s) {
+      if (s === undefined || s === null) return;
+      const open = pageShareOf(s);
+      if (open !== null) {
+        if (m.opened?.user === open.user) m.opened.seen = true;
+        if (m.phase === "ended" && m.ended?.user === open.user) return;
+        if (m.phase === "none" || m.phase === "ended") m.phase = "open";
+        startBeats(open.user);
+        return;
+      }
+      if (m.phase === "open" && (m.opened === null || m.opened.seen)) {
+        const user = m.opened?.user ?? beating?.user ?? null;
+        ended(user, s.shareEnded !== null && s.shareEnded !== undefined && s.shareEnded.user === user ? s.shareEnded.why : "it is no longer open");
+      }
+    },
+    input(target) {
+      if (target?.id !== "share-role") return null;
+      actions.shareRole(target.value);
+      return true;
+    },
+    click(d) {
+      if (d.shareAsk !== undefined) return actions.shareAsk() ?? true;
+      if (d.shareOpen !== undefined) return actions.shareOpen();
+      if (d.shareCancel !== undefined) return actions.shareCancel() ?? true;
+      if (d.shareStop !== undefined) return actions.shareStop(d.shareStop);
+      return null;
+    },
+  };
+}

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

@@ -59,7 +59,7 @@ export function renderEvents(b, { failuresOnly = false, kind = "", table = "", n
 
 /** EVERY KIND OF SYNC EVENT, in its order (src/duck/events.ts `EVENT_KINDS`, held equal by the tests): the Kind filter
  *  offers each, whether the range has one or not. */
-export const EVENT_KINDS = ["copy_failed", "poll_failed", "catch_up_failed", "stream_failed", "source_unreachable", "restart", "copied", "recovered", "synced", "sync_changed"];
+export const EVENT_KINDS = ["copy_failed", "poll_failed", "catch_up_failed", "stream_failed", "source_unreachable", "generated_failed", "restart", "copied", "recovered", "synced", "sync_changed"];
 
 /** The kind and table filters' controls: EVERY kind (EVENT_KINDS), and EVERY added table (`/api/state` `tables`, `s`) —
  *  the sync's own "(the sync)" first — whether the range has an event of it or not, so the choices never depend on what