@mason-data/cli 0.8.0 → 0.9.0

package/dist/src/cli/commands.js

@@ -19,16 +19,17 @@ import { err as styleErr, out as styleOut, stepRenderer, wrap } from "./style.js
 import { alive, endRun, END_GRACE_MS, notAnswering, runState, theRun } from "./runs.js";
 import { version } from "./version.js";
 import { restartsFact, signalSupervisor, stopSupervisor, supervisorGone } from "./supervise.js";
-import { DEMO_DIR, DUCK_FILE, STATE_DIR, databaseMoved, isProject, projectDatabase, projectSource, readProject, theProject, writeConfig } from "./project.js";
+import { DEMO_DIR, DUCK_FILE, STATE_DIR, databaseMoved, isProject, projectDatabase, projectSource, projectWriteRefusal, readProject, theProject, writeConfig } from "./project.js";
 import { callRun, RunUnreachable } from "./control.js";
 import { withPlaceholders, postgresFacts, postgresLink } from "./pg-url.js";
 import { listenerText } from "./pg-tls.js";
-import { logEntries, logLineText } from "../lib/log-buffer.js";
+import { entriesOfLines, logLineText } from "../lib/log-buffer.js";
+import { LogReader, logPath } from "../lib/log-read.js";
 import { catalogTable, entryName, looksSecret, tableNameProblem } from "./sources.js";
 import { addEntry, Refusal, removeEntries, sourceToEdit } from "./source-edit.js";
 import { connectSource, maskedUrl, parseSource, readSourceFacts } from "./preflight.js";
 import { reach } from "./state.js";
-import { copyingText, copyProgress, duration, msText, readiness, readinessWord } from "./readiness.js";
+import { copyingText, copyProgress, duration, generatedReadiness, msText, readiness, readinessWord } from "./readiness.js";
 import { pathText } from "../duck/kept-route.js";
 import { DEFAULT_REQUEST_LIMIT, eventLimit, MAX_SEARCH, SLOW_MS, requestFilter, requestFilterParams } from "./request-filter.js";
 import { countsText } from "../duck/stream.js";
@@ -104,7 +105,8 @@ export { copyingText, copyProgress, duration, msText, readiness, readinessWord }
 /** A table line's bar in its state's colour (on a terminal): green copied, red failed, yellow served but not kept current, cyan at work
  *  (a table whose sync is off is copied as it asked: green). */
 export function paintBar(line, s) {
-    const colour = / its first sync failed: /.test(line) ? s.red : / NOT kept current /.test(line) ? s.yellow : / 100%  [\d,]+ rows · synced( · |$)/.test(line) ? s.green : s.cyan;
+    const colour = / its first sync failed: | NOT kept current, its sync failed /.test(line) ? s.red : / NOT kept current | (—|·) behind by /.test(line) ? s.yellow
+        : / 100%  [\d,]+ rows · synced( · |$)/.test(line) ? s.green : s.cyan;
     return line.replace(/(█+)(░*)|(░+)/, (_m, full, empty, none) => full !== undefined ? `${colour(full)}${s.dim(empty ?? "")}` : s.dim(none ?? ""));
 }
 /** The width of a table's progress bar, in characters. */
@@ -127,12 +129,12 @@ export function tableLines(s, now = Date.now()) {
         let fraction, what;
         if (r === 0) {
             fraction = 1;
-            const age = keptAge(t, now);
+            const age = keptWords(t, now);
             what = `${n(t.copy?.rowsCopied ?? 0)} rows · synced${t.copy?.retired ? ` · ${t.copy.retired}` : ""}${age ? ` · ${age}` : ""}`;
         }
         else if (r === 1) {
             fraction = 1;
-            what = `its first sync failed: ${firstLine(t.error)}`;
+            what = t.copy?.phase === "done" ? copiedFailedText(t, now) : `its first sync failed: ${firstLine(t.error)}`;
         }
         else if (r === 2) {
             const c = copyingText(t.copy.rowsCopied, t.rows, t.copy.progress);
@@ -163,7 +165,8 @@ export function keptAge(t, now = Date.now()) {
         if (k.state !== "streamed")
             return `NOT kept current (${k.syncedAt === null ? "never synced" : `last synced ${agoText(k.syncedAt, now)}`}): ${k.why ?? "it is not streamed yet"}`;
         const at = `replicated, at ${k.position}, ${k.syncedAt === null ? "not synced yet" : agoText(k.syncedAt, now)}`;
-        return k.notRunning === null ? at : `${at} — NOT kept current now, the stream is not running: ${k.notRunning}`;
+        // behind: `keptWords` says it, with the stream not running as its why
+        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;
@@ -175,6 +178,33 @@ export function keptAge(t, now = Date.now()) {
         return `sync: off, ${synced} — mason sync ${tableArg(t.table)} syncs it now; sync: poll 5m on its entry polls it`;
     return `polled every ${k.sync.every}, ${k.syncedAt === null ? "not polled yet" : `last ${agoText(k.syncedAt, now)}`}`;
 }
+/**
+ * WHAT A SERVED TABLE'S LINE SAYS AFTER `synced`: how it is kept and how old it is (`keptAge`, by the kind of its
+ * keeping), then — for EVERY kind, from the one word (`tables[].sync.state`, src/cli/readiness.ts behindOf), never a
+ * second reading of `kept` — behind by how much and why. A kind keptAge has no words for (recopy) still says behind;
+ * a why its words already say is not said twice. Null: nothing to say.
+ */
+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}`;
+}
+/**
+ * A SERVED TABLE WHOSE SYNC FAILED (its first sync succeeded; its poll, catch-up, stream or publication check did not:
+ * issues 100, 82): served as of its age, NOT kept current, why — how it is kept, when it says it is not kept current
+ * now (`keptAge`: a catch-up waiting out its back-off, a table the publication does not carry, with the way out), else
+ * its error's first line — never "its first sync failed".
+ */
+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 ?? (t.kept && t.kept.by !== "generated" && t.kept.by !== "recopy" ? t.kept.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 ${agoText(asOf, now)}`}): ${reason ?? firstLine(t.error)}`;
+}
 /** A span of seconds as the stream's lines say it: `0.3 s` under ten seconds, then as a wait reads (`duration`). */
 export const spanText = (seconds) => seconds < 10 ? `${Math.max(0, seconds).toFixed(1)} s` : duration(seconds);
 /**
@@ -250,18 +280,22 @@ const STATUS_USAGE = `usage: mason status [--json]
            <user>:<password> in the credentials' place), psql (its psql line), listener:
            { host (what it is bound to), tls (certificate, self-signed or null), fingerprint } }, source: { name (the
            source's: its sources file's), file (the sources file), shownFile (it from the project's root), url, database, remote, version, standby, changes,
-           replication, demo (the demo database this run hosts), sync: { default (every table's sync unless its entry
+           replication, demo (the demo database this run hosts), textOrder (what reading the database's text order left to say), sync: { default (every table's sync unless its entry
            says its own: off, poll 30s), written (the file's top sync: says it; false: the default) } }, warnings, folder, project, tables: [{ table, rows,
-           bytes, key, added, addedColumns, copy, error, kept, sync: { state (synced, syncing, failed, waiting), syncedAt (when
+           bytes, key, added, addedColumns, copy, error (why its sync failed: its first sync, or the poll, catch-up, stream or
+           publication check keeping a synced table current; null otherwise), kept, sync: { state (synced, syncing,
+           behind: served and kept but older than its sync: promises, failed, waiting), syncedAt (when
            it was last brought current), syncSeconds (how long that took), syncedBy (copy, poll, catch-up, stream),
-           ageSeconds (how long ago that was) }, … }], totals: { added, copied, failed, rows (the synced tables' rows),
+           ageSeconds (how long ago that was), asOf (the time the synced data holds the database as of: kept's syncedAt),
+           promisedSeconds (the age its sync: promises not to pass; null: sync: off promises nothing), behindBySeconds
+           (how far past it, 0 when not; null when nothing is promised), behindWhy (why, while behind; else null) }, … }], totals: { added, copied, failed, rows (the synced tables' rows),
            syncedAt (the latest sync of any) }, engine: { file, bytes, keptDays (MASON_HISTORY_DAYS), version (the run's), startedAt,
            uptimeSeconds, restarts (the times its supervisor started the run again: { count, last: { at, why, upSeconds }
            or null }, or { error }) }, disk: { path (where the synced data's file is), freeBytes, copyBytes (the file),
            projectedBytes (what the first syncs running are projected to add; null: none, or too early to say), error },
            sessions: { open (the Postgres API's sessions logged in), byClient: [{ user ('' a token's), client (its
            application_name), open, running }] }, share: (null, or what mason share has open) { port, fingerprint, sessions,
-           refusedLogins, droppedConnections, shares: [{ user, role, reads, openedAt, via, host, port, endsAt, state }] }, queries: { keptDays, day, week } (the last day's and the last 7
+           refusedLogins, droppedConnections, shares: [{ user, from (command: mason share; page: the web page), role, reads, openedAt, via, host, port, endsAt, state }] }, shareEnded: (null, or the last share that ended) { user, from, why, at }, queries: { keptDays, day, week } (the last day's and the last 7
            days' statements, each { days, covered (the days of it the request log keeps), statements, completed, refused,
            failed, cancelled, rows, bytesSent, durationMs: { avg, p50, p95 } (the completed ones') or null }; { error }
            when it could not be read), slowQueries, refusedQueries, refusedTotal (how many in all), unsupported: [{ gap
@@ -272,15 +306,21 @@ const STATUS_USAGE = `usage: mason status [--json]
            newest last: mason logs --events), error (why they could not be read, or null), queries: [{ requestId,
            startedAt, outcome, sqlstate, message, query, … }] (the latest statements refused, failed or cancelled, newest
            last, as mason logs --requests --json shows each: mason logs --requests --failed), queriesError (or null) },
-           readiness (what mason wait waits on), ui (whether this run serves the web page: mason ui), next }.
+           readiness (what mason wait waits on), ui (whether this run serves the web page: mason ui), served (this is
+           mason serve's run: mason ui --ssh opens its page), sourcesReadOnly (why the page offers no Add or Remove — the
+           project's files deployed read-only, MASON_PROJECT_READONLY, which mason add and mason remove refuse too, or a
+           server's sources file it cannot write — or null), next }.
            Each table's kept is how it is kept current now (absent for a table the sync does not hold):
            { by: poll, sync: { mode: off } or { mode: poll, every (30s), seconds } (its entry's sync:, else the file's,
            else off), syncedAt (its last whole read or poll), nextAt (when its next poll is due; null: off, or not polled
            now), pending (only when it applies: why it is not kept current now, its phase included: it waits for
            its first sync, it is being read whole, its first sync failed, it is read again whole, caught up first) }
-           or { by: recopy, copiedAt, pending (only when it applies, as the poll's) }
+           or { by: recopy, copiedAt, syncedAt, pending (only when it applies, as the poll's) }
            or { by: replication, slot, state (streamed, catching-up, waiting, left-out), why, position, lastCommit,
-           notRunning (why the stream is not running, null when it is) }; with Mason stopped: { running: false, project, source: { name,
+           notRunning (why the stream is not running, null when it is) }; each with promisedSeconds (the age of
+           its synced data past which it is behind: poll, its interval plus the larger of 60 s and twice its last poll;
+           replication, 120 s; off, null) and lateWhy (what would make it late now: the pass's or its own poll's
+           time, which Mason waits four times, the stream not running); with Mason stopped: { running: false, project, source: { name,
            file, url, error (the sources file's problem, or null) }, engine, tables: [{ table }], lastRun, lastStop:
            { at, how } or null, next }; hung: the same with hung: { pid, problem, why },
            exit 1. In replication mode stream: { slot, slotWal: { walHeldBytes (the WAL the slot holds on the
@@ -294,7 +334,11 @@ const STATUS_USAGE = `usage: mason status [--json]
            fill: { rows, bytesPerRow, seconds, basis (measured: from the last fill of its column; disk or text: modelled from
            the column's bytes a row on disk, or its text's before it is on disk), rowsPerSecond } (the fill's estimate it
            was decided on), filled: { rows, seconds } (what its own fill measured), queued (a backfill waiting for the fill
-           under way), keptAt, readyAt, why }]. roles (a run with a roles file, mason/roles.yml: what a user added
+           under way), keptAt, readyAt, why }]. generatedTables: [{ table, file, kind, method (whole: its SQL run again),
+           state (refused, waiting, building, failed, current, behind), targetLag, behindSeconds (across its chain: the
+           oldest base change below it not in it), behindSince (when that change was committed; null: none), missingTarget, serving,
+           lastRun: { at, seconds, rows }, error (the last run's, no value of a row in it), retryAt,
+           refusals: [{ key, message, why, options, text }], waitingFor, warnings }]. roles (a run with a roles file, mason/roles.yml: what a user added
            with --role may read): { file, roles: [name], problem (what is wrong with the file now, every statement of a
            user with a role refused while there is; null), default (the role of a user added without --role; null: the
            file names none, and such a user reads nothing), all (the roles of tables: all) }
@@ -318,9 +362,9 @@ export const STATUS = {
     summary: "what Mason is doing: the database, each synced table, the Postgres API, its statements and errors",
     usage: STATUS_USAGE,
     options: { json: { type: "boolean" } },
-    json: ["running", "pid", "postgres", "source", "warnings", "folder", "project", "tables", "totals", "engine", "disk", "sessions", "stream", "jsonPaths", "queries", "slowQueries", "refusedQueries",
-        "refusedTotal", "unsupported", "recentErrors", "readiness", "ui",
-        "roles", "share", "lastRun", "lastStop", "hung", "next"],
+    json: ["running", "pid", "postgres", "source", "warnings", "folder", "project", "tables", "totals", "engine", "disk", "sessions", "stream", "jsonPaths", "generatedTables", "queries", "slowQueries", "refusedQueries",
+        "refusedTotal", "unsupported", "recentErrors", "readiness", "ui", "served", "sourcesReadOnly",
+        "roles", "share", "shareEnded", "lastRun", "lastStop", "hung", "next"],
 };
 export async function status(argv) {
     const f = parseCommand(STATUS, argv);
@@ -396,7 +440,7 @@ export async function status(argv) {
             ["Listener", listenerText(run.postgresListener, postgresLink(run.postgresUrl).port)],
             ...shareRows(s.share),
             // the web page (mason ui), without its one-time token: mason ui prints the URL that carries it, and opens it
-            ...(s.ui === true ? [["Web UI", `${run.control.url}/  (mason ui opens it)`]] : []),
+            ...(s.ui === true ? [["Web UI", s.served === true ? "from your machine: mason ui --ssh <user@server>" : `${run.control.url}/  (mason ui opens it)`]] : []),
             // the roles file as the listener reads it now (mason user add --role): its roles, or what is wrong with it
             ...(s.roles && s.roles.file !== null
                 ? [["Roles", s.roles.problem !== null ? st.red(`${s.roles.problem} (every statement of a user with a role is refused until it is fixed)`)
@@ -424,6 +468,8 @@ export async function status(argv) {
             out(l);
         for (const l of jsonPathLines(s.jsonPaths ?? [], st))
             out(l);
+        for (const l of generatedLines(s.generatedTables ?? [], st))
+            out(l);
         for (const l of queryLines(queries, st))
             out(l);
         for (const l of slowLines(slowReply.status === 200 ? slow : { error: String(slowReply.body.error ?? slowReply.status) }, st))
@@ -459,6 +505,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]] : []),
     ];
 }
 /** An SQL statement on one line, cut at `max` characters (the whole of it is mason logs --requests --json's). */
@@ -487,6 +534,38 @@ export function jsonPathLines(paths, st) {
         lines.push(`  ${st.dim(`${dropped} dropped (mason status --json says why)`)}`);
     return lines;
 }
+/** a generated table's state in the words mason status prints: how it is kept, how far behind, its last run */
+function generatedWords(g) {
+    const how = `${g.kind ?? "?"} ${g.method}, target ${g.targetLag ?? "?"}`;
+    const last = g.lastRun === null ? "" : `; last re-run ${duration(g.lastRun.seconds)}, ${n(g.lastRun.rows)} row${g.lastRun.rows === 1 ? "" : "s"}`;
+    if (g.state === "waiting")
+        return `${how}, waiting for ${g.waitingFor ?? "a table"} to sync`;
+    if (g.state === "building")
+        return `${how}, being built`;
+    if (g.state === "refused")
+        return g.serving ? `${how}, its file is refused; it keeps serving what it was built from${last}` : "refused";
+    const lag = g.behindSeconds === 0 ? "nothing behind" : `${duration(g.behindSeconds)} behind`;
+    const missed = g.missingTarget ? ", past its target" : "";
+    const failed = g.error === null ? "" : `; its last run failed, tried again at ${g.retryAt ?? "?"}: ${g.error}`;
+    return `${how}, ${lag}${missed}${last}${failed}`;
+}
+/** mason status's generated tables: a line each, and a refused one's reasons and ways out under it, whole */
+export function generatedLines(tables, st) {
+    if (tables.length === 0)
+        return [];
+    const width = Math.max(...tables.map((g) => entryName(g.table).length));
+    const lines = [`\n${st.bold("Generated tables")} ${st.dim("(tables declared in SQL; mason help generated)")}:`];
+    for (const g of tables) {
+        const words = generatedWords(g);
+        const paint = g.state === "refused" || g.state === "failed" || g.missingTarget ? st.red : g.state === "current" ? st.green : g.state === "behind" ? (x) => x : st.yellow;
+        lines.push(`  ${entryName(g.table).padEnd(width)}  ${paint(words)}`);
+        for (const r of g.refusals)
+            lines.push(...r.text.split("\n").map((l) => `    ${l}`));
+        for (const w of g.warnings)
+            lines.push(`    ${st.yellow(w)}`);
+    }
+    return lines;
+}
 /** The copies in all, as mason status's `Copies` row says them: `3 of 3 added synced, 1,234 rows, the last synced 5 s ago`. */
 export function totalsText(t, now = Date.now()) {
     const last = t.syncedAt === null ? "" : `, the last synced ${duration((now - Date.parse(t.syncedAt)) / 1000)} ago`;
@@ -815,9 +894,9 @@ async function readCatalog(p) {
         return src;
     const demo = p.config.demo === true;
     const fix = `change the URL where it is (${src.from}) when the database's password or host changed`;
-    const parsed = parseSource(src.resolved);
+    const parsed = parseSource(src.resolved, src.from);
     if ("problem" in parsed)
-        return { message: `the database's URL (${src.from}): ${parsed.problem}`, code: "bad_source", fix };
+        return { message: parsed.problem, code: "bad_source", fix };
     const connected = await connectSource(parsed.source, { demo });
     if ("failure" in connected) {
         // the demo database's way out is its run (src/cli/demo.ts): its hint is the fix, mason start the next command
@@ -925,7 +1004,8 @@ const ADD_USAGE = `usage: mason add <table>… [--columns <column>,…] [--inclu
   With Mason running the first sync starts at once; mason wait returns when it is done and the table is served. Before
   mason start (mason init && mason add orders && mason start) the entry is written, checked against the database as
   the run checks it, and the first sync begins at mason start. Adding a table again with other columns changes its entry,
-  and the table is synced again whole with them.
+  and the table is synced again whole with them. A project deployed as committed (MASON_PROJECT_READONLY=1 where Mason
+  runs) is refused, its files left as they are: add the table where the project is committed, then deploy.
 
   --columns <a,b,…>   only these columns (one table at a time: the list is that table's)
   --include <a,b,…>   these columns as well as every other one — a column that looks like a secret, named on purpose
@@ -1003,6 +1083,11 @@ export async function add(argv) {
     // (a state with no project never meets the need: reach said it)
     if (where === null || where.project === null)
         return 1;
+    // a project whose files are deployed read-only (src/cli/project.ts projectWriteRefusal): refused before the run or the
+    // database is asked, whether Mason is up or down — the run's own record counts, whatever this shell's environment says
+    const readOnly = projectWriteRefusal(where.project.root, process.env);
+    if (readOnly !== null)
+        return failed("add", readOnly, { json });
     if (where.state === "up") {
         // Mason up: the run adds it (the copy starts now, and the run's own re-read never races the file's write)
         const run = where.run;
@@ -1132,7 +1217,9 @@ const REMOVE_USAGE = `usage: mason remove <table>… [--json]
 
   Takes tables out of the project: each one's entry in the sources file (mason/sources/<name>.yml) is removed, the
   rest of the file as it was. With Mason running it stops syncing the table and drops its synced data at once; with Mason
-  stopped, what an earlier run synced is dropped at the next mason start.
+  stopped, what an earlier run synced is dropped at the next mason start. A project deployed as committed
+  (MASON_PROJECT_READONLY=1 where Mason runs) is refused, its files left as they are: remove it where the project is
+  committed, then deploy.
 
     mason remove customers
     mason remove customers billing.invoices     several at once
@@ -1160,6 +1247,10 @@ export async function remove(argv) {
     // (a state with no project never meets the need: reach said it)
     if (where === null || where.project === null)
         return 1;
+    // read-only, as mason add (src/cli/project.ts projectWriteRefusal): refused before the run or the database is asked
+    const readOnly = projectWriteRefusal(where.project.root, process.env);
+    if (readOnly !== null)
+        return failed("remove", readOnly, { json });
     if (where.state === "up") {
         // Mason up: the run removes it and drops the copy at once (src/cli/run-server.ts removeTables)
         const run = where.run;
@@ -1201,15 +1292,18 @@ export function removedReport(removed, file, o = {}) {
 /** An added table as mason wait --json says it: its copy, its error, and how it is kept current, as the run's state has
  *  them (mason status --json's own fields, never derived again here) */
 export function waitTable(t) {
-    return { table: t.table, copy: t.copy, error: t.error, ...(t.kept ? { kept: t.kept } : {}) };
+    return { table: t.table, copy: t.copy, error: t.error, ...(t.kept ? { kept: t.kept } : {}), ...(t.sync ? { sync: t.sync } : {}) };
 }
-const WAIT_USAGE = `usage: mason wait [--timeout <seconds>] [--json]
+const WAIT_USAGE = `usage: mason wait [<generated table>] [--timeout <seconds>] [--json]
 
   Waits until every added table is synced and served, showing every added table on a line of its own: 100% for the
   finished (in the order they finished), a bar for the ones still syncing, at the bottom. Run it after mason add.
+  Named, a generated table instead: waits until it holds every change Mason had synced when the wait began, across its
+  chain (the tables it is generated from, and theirs), so what is read from it next includes them.
 
     mason add orders && mason wait
     mason wait --timeout 3600     a large table: wait up to an hour
+    mason wait daily_requests     a generated table: until it holds what is synced now
 
   --timeout <seconds>   how long to wait (default 600); the sync goes on after, and mason wait again picks it up
   --json                as data, once it ends: { ready, failed, waiting, timedOut, tables: [{ table, copy, error,
@@ -1217,19 +1311,36 @@ const WAIT_USAGE = `usage: mason wait [--timeout <seconds>] [--json]
                         rate, the seconds left, while its chunks are read }; kept as mason status --json says it —
                         { by: poll, sync: { mode: off } or { mode: poll, every, seconds }, syncedAt (its last whole read
                         or poll), nextAt (its next poll; null: off) }; kept's pending, when it applies, says why
-                        it is not kept current now, its phase included),
+                        it is not kept current now, its phase included; sync as mason status --json says it: its state —
+                        synced, syncing, behind, failed, waiting — asOf, promisedSeconds, behindBySeconds, behindWhy),
                         stream (replication mode: where the stream is, as mason status --json says it), error (on a
                         failure or a timeout: { code, message, next }), next }
+                        Named, a generated table: the same ready, failed, waiting, timedOut, error and next, tables
+                        empty, and generatedTable (as mason status --json's generatedTables says it: its state,
+                        behindSeconds, behindSince — when the oldest change not in it was committed, null: none)
 
-  Exit status: 0 ready; 1 a first sync failed (printed, with what to do; Mason tries it again by itself); 124 timed out.
+  Exit status: 0 ready (a table behind what its sync: promises is said on its line, and ready); 1 a first sync failed,
+  or the sync keeping a synced table current failed (its poll, its catch-up, the stream, or a named publication that
+  does not carry it), or the generated table's run failed, or it or a parent was refused
+  before it was built (printed, with what to do; Mason tries a failed one again by itself); 124 timed out.
+  A generated table that serves and holds everything synced is ready (0) though its last run failed: after editing its
+  file, read mason status for whether the new definition was refused or failed.
 `;
+/** how often a wait not drawn in place says its block again though nothing in it changed, so a long one never goes
+ *  quiet: the copies' wait and a generated table's */
+export const SAY_AGAIN_MS = 30_000;
+/** whether a wait says its block now: what it is changed (`what`, its numbers taken out), or `every` ms went by since it
+ *  last said it */
+export function sayAgain(what, said, saidAt, now, every = SAY_AGAIN_MS) {
+    return what !== said || now - saidAt >= every;
+}
 export const WAIT = {
     needs: "run",
     name: "wait",
-    summary: "wait until every added table is synced and served (exit 0; 1 on a failure, with why)",
+    summary: "wait until every added table is synced, or a generated table holds what is synced now (1: a failure)",
     usage: WAIT_USAGE,
     options: { json: { type: "boolean" }, timeout: { type: "string" } },
-    json: ["ready", "failed", "waiting", "timedOut", "tables", "stream", "error", "next"],
+    json: ["ready", "failed", "waiting", "timedOut", "tables", "stream", "generatedTable", "error", "next"],
 };
 export async function wait(argv) {
     const f = parseCommand(WAIT, argv);
@@ -1239,9 +1350,14 @@ export async function wait(argv) {
     const timeout = f.values.timeout === undefined ? 600 : Number(f.values.timeout);
     if (!Number.isFinite(timeout) || timeout <= 0)
         return failed("wait", { message: `--timeout is a number of seconds, not ${JSON.stringify(f.values.timeout)}`, code: "usage" }, { json });
+    if (f.positionals.length > 1)
+        return failed("wait", { message: `name one generated table, not ${f.positionals.length}`, code: "usage", usage: WAIT_USAGE }, { json });
+    const named = f.positionals[0];
     const run = await runOr(WAIT, json);
     if (!run)
         return 1;
+    if (named !== undefined)
+        return waitGenerated(run, named, timeout, json);
     return guarded("wait", json, async () => {
         const until = Date.now() + timeout * 1000;
         // a terminal gets the block — every added table on its line (tableLines), then the stream — redrawn in place;
@@ -1266,7 +1382,7 @@ export async function wait(argv) {
             }
             // the same work, other numbers (a stream's positions included: they move with every change)
             const what = lines.join("\n").replace(/[█░]+/g, "").replace(/\b[0-9A-F]+\/[0-9A-F]+\b/g, "#").replace(/[\d,.]+(%| rows\/s| s| min| h)?/g, "#");
-            if (what !== said || Date.now() - saidAt >= 30_000) {
+            if (sayAgain(what, said, saidAt, Date.now())) {
                 err(lines.map((l) => `  ${l}`).join("\n"));
                 said = what;
                 saidAt = Date.now();
@@ -1309,6 +1425,50 @@ export async function wait(argv) {
         }
     });
 }
+/** `mason wait <generated table>`: until it holds every change synced when the wait began (src/cli/readiness.ts
+ *  generatedReadiness), a line when what it waits for changes; the same outcome and exit codes as the wait for copies */
+async function waitGenerated(run, named, timeout, json) {
+    return guarded("wait", json, async () => {
+        const since = Date.now(), until = since + timeout * 1000;
+        let said = "", saidAt = 0;
+        for (;;) {
+            const s = await readState(run);
+            const all = s.generatedTables ?? [];
+            const g = all.find((t) => t.table === named) ?? all.find((t) => t.table === `public.${named}`);
+            if (g === undefined) {
+                const names = all.map((t) => entryName(t.table));
+                return failed("wait", { message: `no generated table ${JSON.stringify(named)}${names.length ? "" : ": the project has none"}`, code: "not_found",
+                    ...(names.length ? { fix: `name one of: ${names.join(", ")}` } : {}), next: [["mason status", "the generated tables and what each is doing"]] }, { json });
+            }
+            const r = generatedReadiness(g, since);
+            const next = [["mason status", "the generated tables and what each is doing"]];
+            const failure = r.failed.length
+                ? { message: r.failed[0], code: "failed", fix: "Mason tries a failed run again by itself; mason logs says why it failed", next: [["mason logs", "the detail of the failure"], ...next] }
+                : !r.ready && Date.now() >= until
+                    ? { message: `${g.table} does not hold what was synced ${timeout} s ago yet`, code: "timeout", why: r.waiting.join("\n"), fix: "nothing stopped: its runs go on",
+                        next: [[`mason wait ${entryName(g.table)}`, "keep waiting (--timeout <seconds> for longer)"], ...next] }
+                    : null;
+            if (json && (r.ready || failure)) {
+                out(jsonText(WAIT, { ...r, timedOut: !r.ready && failure?.code === "timeout", tables: [], generatedTable: g, ...(failure ? { error: errorJson(failure) } : {}) }, failure ? failure.next ?? [] : next));
+            }
+            if (r.ready) {
+                if (!json)
+                    out(withEnd(styleOut().green(`Ready: ${g.table} holds every change synced when the wait began.`), { next }));
+                return 0;
+            }
+            if (failure)
+                return json ? (failure.code === "timeout" ? 124 : 1) : failed("wait", failure, { json: false });
+            const line = r.waiting.join("\n").replace(/\d+ s behind/, "# s behind");
+            // when what it waits for changes, and every 30 s while it does not, as the copies' wait says its block
+            if (!json && sayAgain(line, said, saidAt, Date.now())) {
+                err(`  ${r.waiting.join("\n  ")}`);
+                said = line;
+                saidAt = Date.now();
+            }
+            await new Promise((res) => setTimeout(res, 1000));
+        }
+    });
+}
 // ------------------------------------------------------------------ mason logs
 /** What the sync's events leave out, said where they are listed (mason logs --help, the page's Sync events, held equal
  *  by tests/web-page.test.ts): a scheduled poll that succeeds is no event, so a person who synced reads where it is. */
@@ -1357,8 +1517,9 @@ const LOGS_USAGE = `usage: mason logs [-n <lines>] [-f] [--start] [--requests [<
   --running        the statements running now (Mason must be running)
   --json           as data: { lines: [{ at, text }] } (the log's entries, oldest first; at is null for a line with no
                    time); with --requests { requests: [{ requestId, startedAt, endedAt, session, applicationName,
-                   tokenName, user (the mason user), role, attributes (the user's values its role's row filters read, or
-                   null), method, outcome (ok, refused, failed, cancelled), status
+                   clientAddress (the client's address; behind a TCP proxy, the one its PROXY header carries),
+                   tokenName, user (the mason user), role, attributes (the user's values its role's row filters
+                   read, or null), method, outcome (ok, refused, failed, cancelled), status
                    (completed, failed, cancelled: what a reader shows), sqlstate, message, detail, hint, rows,
                    bytesSent, durationMs, query, queryTruncated }], keptDays, before (the position of the page before,
                    or null: none older) }; with --events { events: [{ at, kind (copy_failed, poll_failed,
@@ -1572,16 +1733,22 @@ export async function logs(argv) {
         return failed("logs", t, { json });
     // the run's log by default (mason logs once showed no actual logs: it showed
     // mason start's terminal, which after the start carries only warnings and errors)
-    const file = path.join(t.project.dir, f.values.start ? "dev.log" : "mason.log");
+    const file = logPath(t.project.dir, f.values.start ? "start" : "run");
     if (!fs.existsSync(file)) {
         return failed("logs", { message: `${file} does not exist yet`, code: "nothing_yet", why: `Mason has not run for ${t.project.config.name}`, next: [["mason start", "start it, in the background"]] }, { json });
     }
-    const text = fs.readFileSync(file, "utf8");
+    // read through the one reader, every line masked as it is read (src/lib/log-read.ts, issue 621: an older Mason's lines
+    // held the source's password in a `password=` value); a line not yet ended is -f's to show as it stands, else read whole
+    const reader = new LogReader(file);
+    const read = reader.readLines();
+    const unended = f.values.follow ? "" : reader.rest();
+    if (unended !== "")
+        read.push(unended);
     // WHY THE FILE, even with the run up: it is the whole record (the run's memory keeps only its last LOG_KEPT entries,
     // src/lib/log-buffer.ts) and the only one when the run is down. The entries are parsed by the buffer's own parser, so
     // `{ at, text }` is the shape of GET /api/logs too (the run's answer, which a `mason serve` run has no file for).
     // -n counts entries, a multi-line one being ONE; dev.log's lines (the start's steps, indented under each other) are a line each.
-    const all = logEntries(text, { perLine: f.values.start === true });
+    const all = entriesOfLines(read, { perLine: f.values.start === true });
     const last = all.slice(Math.max(0, all.length - lines));
     if (json) {
         out(jsonText(LOGS, { lines: last }, [["mason logs --requests", "every statement the Postgres API met"]]));
@@ -1591,24 +1758,13 @@ export async function logs(argv) {
         out(logLineText(l));
     if (!f.values.follow)
         return 0;
-    let offset = Buffer.byteLength(text);
     for (;;) {
+        // the lines written since, each masked once it is whole, then the line not ended yet as it stands, masked (a run
+        // killed mid-write leaves its last words unended); a new run that started the file over is read from its start
+        const more = reader.follow();
+        if (more !== "")
+            process.stdout.write(more);
         await new Promise((res) => setTimeout(res, 500));
-        const size = fs.statSync(file).size;
-        if (size < offset)
-            offset = 0; // a new run started the file over
-        if (size === offset)
-            continue;
-        const buf = Buffer.alloc(size - offset);
-        const fd = fs.openSync(file, "r");
-        try {
-            fs.readSync(fd, buf, 0, buf.length, offset);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-        offset = size;
-        process.stdout.write(buf.toString());
     }
 }
 // ------------------------------------------------------------------ mason stop