@mason-data/cli 0.9.0 → 0.11.0

package/dist/src/cli/commands.js

@@ -8,13 +8,13 @@
  *   mason tables [<table>…] [--json]      the database's tables, their columns, keys and foreign keys
  *   mason add <table>… [--columns …]      copy tables into Mason: every column, or the ones --columns names
  *   mason remove <table>…                 take tables out of the sources file; their copies are dropped
- *   mason wait [--timeout <s>] [--json]   until every added table is synced: 0 ready, 1 a copy failed (said), 124 timed out
+ *   mason wait [--timeout <duration>] [--json]   until every added table is synced: 0 ready, 1 a copy failed (said), 124 timed out
  *   mason logs [-n <lines>] [-f] [--start] [--requests] [--events]   the run's log; --start, the start's terminal; --requests, its request log; --events, the sync's events
  *   mason stop                            stop Mason for this folder's project (the copy stays)
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { asFailure, endText, errorJson, failed, jsonText, nextBlock, parseCommand, reportText, withEnd } from "./command.js";
+import { asFailure, endText, errorJson, failed, failureCode, jsonText, listFlag, nextBlock, noArguments, parseCommand, reportText, withEnd } from "./command.js";
 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";
@@ -25,7 +25,7 @@ import { withPlaceholders, postgresFacts, postgresLink } from "./pg-url.js";
 import { listenerText } from "./pg-tls.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 { catalogTable, entryName, findEntry, 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";
@@ -33,7 +33,8 @@ import { copyingText, copyProgress, duration, generatedReadiness, msText, readin
 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";
-import { agoText, BIG_TABLE_ROWS, parseSync, syncText } from "../lib/table-sync.js";
+import { agoText, BIG_TABLE_ROWS, parseDuration, parseSync, syncText } from "../lib/table-sync.js";
+import { didYouMean } from "../lib/did-you-mean.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const err = (m) => { process.stderr.write(`${m}\n`); };
 // ------------------------------------------------------------------ shared
@@ -265,7 +266,14 @@ const STATUS_USAGE = `usage: mason status [--json]
 
   Status: running, not running, or hung — then this project's facts, one a line: its folder, its database and how
   its changes are read, the run and the synced data's file and the synced tables in all (synced, rows, the last sync), the Postgres API
-  and how it listens. Then each added table as mason wait shows it, with how it is kept current and when it was last synced
+  and how it listens.
+
+    mason status
+    mason status --json
+
+  --json   as data: its shape is at the end
+
+  Then each added table as mason wait shows it, with how it is kept current and when it was last synced
   (sync: off, last synced 3 days ago; polled every 30s, last 4 s ago); the sync's latest failures (mason logs --events
   lists every event) and the latest statements refused, failed or cancelled (mason logs --requests --failed); the Postgres API's statements of the last day and the last week (each outcome, the completed
   ones' average, p50 and p95 time, the rows and bytes sent); the ones it answered slowly in the last day; and the ones it refused or
@@ -273,76 +281,6 @@ const STATUS_USAGE = `usage: mason status [--json]
   running", how the last run ended, and the tables are the ones the sources file names. Hung is a run that is alive and does
   not answer its commands (a statement may be holding its main thread): the same rows, and mason stop ends it (exit 1).
 
-    mason status
-    mason status --json
-
-  --json   as data: { running, pid, postgres: { url, host, port, database, sslmode (require when it is TLS), shown (the URL with
-           <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), 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 (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), 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, 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
-           (its entry of docs/SQL-SUPPORT.md), title (what it is; null for an entry this Mason no longer has), runs
-           (the statements it refused in the last day), users, clients (application_name), last, example (the latest,
-           cut at 1,000 characters) }] (the most refused first: GET /api/unsupported) or { error },
-           recentErrors: { sync: [{ at, kind, failed, table, message }] (the latest failures of the sync and restarts,
-           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), 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, 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) }; 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
-           database), walStatus (reserved, extended, unreserved, lost), safeWalSizeBytes (the WAL left before Postgres
-           invalidates it; null: max_slot_wal_keep_size unset, nothing caps it), at } or { error }, publication, running, failure, position,
-           applied, database: { lsn, at } or { error }, lag: { bytes, seconds }, lastBatch: { appliedAt, committedAt },
-           tables: [{ table, state (streamed, catching-up, waiting, left-out), why, catchUp: { phase (queued, polling,
-           applying), from, startedAt, held, retryAt }, applied: { inserts, updates, deletes, truncates } }] }.
-           jsonPaths: [{ table, column, steps, either, canonical, asText (false: a path's -> and ->> share it), name,
-           state (waiting, backfilling, ready, dropped), rowsTotal, rowsDone, marked, statements, slowestMs, totalMs,
-           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 }]. 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) }
-
   In replication mode a Stream section says where the stream is: its position against the database's (bytes behind),
   when the newest change applied was committed and how long after it was applied, and each added table — streamed,
   with the changes applied this run; being caught up by one poll; not streamed yet; or left out — and why.
@@ -355,6 +293,75 @@ const STATUS_USAGE = `usage: mason status [--json]
   waiting (its fill's cost holds it back: the line says the estimate and what would store it), queued (its column
   added, its fill after the one under way), backfilling (its existing rows being filled, N %) or ready (read from its
   column). MASON_STORE_JSON_PATHS=off turns it off.
+
+  The --json answer: { running, pid, postgres: { url, host, port, database, sslmode (require when it is TLS), shown (the URL with
+    <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), 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 (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), 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, 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
+    (its entry of docs/SQL-SUPPORT.md), title (what it is; null for an entry this Mason no longer has), runs
+    (the statements it refused in the last day), users, clients (application_name), last, example (the latest,
+    cut at 1,000 characters) }] (the most refused first: GET /api/unsupported) or { error },
+    recentErrors: { sync: [{ at, kind, failed, table, message }] (the latest failures of the sync and restarts,
+    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), 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), pageReadOnly (why the page changes nothing: mason serve with
+    MASON_UI_READ_ONLY=1, which refuses every change the page sends — or null), pageSocket (the Unix socket the
+    page is served on too: mason serve with MASON_UI_SOCKET — 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, 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) }; 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
+    database), walStatus (reserved, extended, unreserved, lost), safeWalSizeBytes (the WAL left before Postgres
+    invalidates it; null: max_slot_wal_keep_size unset, nothing caps it), at } or { error }, publication, running, failure, position,
+    applied, database: { lsn, at } or { error }, lag: { bytes, seconds }, lastBatch: { appliedAt, committedAt },
+    tables: [{ table, state (streamed, catching-up, waiting, left-out), why, catchUp: { phase (queued, polling,
+    applying), from, startedAt, held, retryAt }, applied: { inserts, updates, deletes, truncates } }] }.
+    jsonPaths: [{ table, column, steps, either, canonical, asText (false: a path's -> and ->> share it), name,
+    state (waiting, backfilling, ready, dropped), rowsTotal, rowsDone, marked, statements, slowestMs, totalMs,
+    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 }]. 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) }
 `;
 export const STATUS = {
     needs: "project",
@@ -363,13 +370,16 @@ export const STATUS = {
     usage: STATUS_USAGE,
     options: { json: { type: "boolean" } },
     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",
+        "refusedTotal", "unsupported", "recentErrors", "readiness", "ui", "served", "sourcesReadOnly", "pageReadOnly", "pageSocket",
         "roles", "share", "shareEnded", "lastRun", "lastStop", "hung", "next"],
 };
 export async function status(argv) {
     const f = parseCommand(STATUS, argv);
     if (typeof f === "number")
         return f;
+    const extra = noArguments(STATUS, f.positionals, f.values.json === true);
+    if (extra !== null)
+        return extra;
     const r0 = await theRun(process.cwd());
     // the first line goes straight to the point (Status: running); when the service is not running, the same rows and
     // tables show, with "not running" for each service that is not
@@ -440,7 +450,8 @@ 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", s.served === true ? "from your machine: mason ui --ssh <user@server>" : `${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)`) +
+                        (typeof s.pageSocket === "string" ? `; on this machine, the Unix socket ${s.pageSocket} too` : "")]] : []),
             // 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)`)
@@ -788,10 +799,12 @@ const TABLES_USAGE = `usage: mason tables [<table>…] [--all] [--json]
     mason tables --all                       every table with its columns, at once (long)
 
   --all       every table with its columns, not only the named ones
-  --json      as data: { database, source: { name (the source's: its sources file's), file (the sources file) },
-              tables: [{ table, rows, bytes, primaryKey, comment, addable,
-              reason, added, addedColumns (the columns it syncs: null when not added), copyKey (the key: the sources
-              file keys it by, null: its primary key), columns: [{ name, type, nullable, comment, references }] }], next }
+  --json      as data: its shape is at the end
+
+  The --json answer: { database, source: { name (the source's: its sources file's), file (the sources file) },
+    tables: [{ table, rows, bytes, primaryKey, comment, addable,
+    reason, added, addedColumns (the columns it syncs: null when not added), copyKey (the key: the sources
+    file keys it by, null: its primary key), columns: [{ name, type, nullable, comment, references }] }], next }
 `;
 export const TABLES = {
     // the project, not the run (the hands-on review of #451, item 15): what it lists is the database's catalog and the
@@ -978,12 +991,22 @@ async function viaRun(run, route, body) {
 const ADD_USAGE = `usage: mason add <table>… [--columns <column>,…] [--include <column>,…] [--key <column>,…] [--sync <sync>] [--json]
 
   Syncs tables into Mason: each one is added to the project's sources file (mason/sources/<name>.yml), under tables:
+
     mason add orders                                    every column:            orders: {}
     mason add orders --columns id,status,total          those columns:           orders: { columns: [id, status, total] }
     mason add orders customers                          several tables, every column of each
     mason add users --include password_hash             every column, and one that looks like a secret
     mason add event_log --key tenant_id,id              a table with no primary key, keyed by those columns
     mason add orders --sync "poll 30s"                  polled every 30 seconds:  orders: { sync: poll 30s }
+
+  --columns <a,b,…>   only these columns (one table at a time: the list is that table's); a list flag takes a comma
+                      list or the flag repeated, the same: --columns id,status is --columns id --columns status
+  --include <a,b,…>   these columns as well as every other one — a column that looks like a secret, named on purpose
+  --key <a,b,…>       for a table with no primary key: the columns that tell its rows apart, which it is keyed by (one
+                      table at a time; polled or off: logical replication cannot apply a change by them)
+  --sync <sync>       how it is kept current after its first sync, written on its entry: off, "poll 30s" or replication
+  --json              as data: its shape is at the end
+
   A table is its name (orders) or schema.table (billing.invoices). Its primary key is always synced. The rest of the
   file — your comments, other tables — stays as it was.
 
@@ -1007,19 +1030,14 @@ const ADD_USAGE = `usage: mason add <table>… [--columns <column>,…] [--inclu
   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
-  --key <a,b,…>       for a table with no primary key: the columns that tell its rows apart, which it is keyed by (one
-                      table at a time; polled or off: logical replication cannot apply a change by them)
-  --sync <sync>       how it is kept current after its first sync, written on its entry: off, "poll 30s" or replication
-  --json              as data: { added: [{ table, entry, columns (null: every one), exclude, key, addedKey (key columns
-                      added to --columns), skippedSecrets, already (the file said so already), sync: { value (off, poll
-                      30s), from (entry: its own sync:, file: the file's, default: off, as the file writes none) },
-                      bigOff (it is over ${BIG_TABLE_ROWS.toLocaleString("en-US")} rows and its entry was written sync: off), notReplicated (why
-                      its entry was written sync: poll 5m under a file whose sync: is replication, or null), pollCost (an estimate of
-                      what a frequent poll of a big table costs your database, or null) } or { table, error }],
-                      file (the sources file), error (when a table was not added: { code, message, why }), next };
-                      exit 1 when a table could not be added
+  The --json answer: { added: [{ table, entry, columns (null: every one), exclude, key, addedKey (key columns
+    added to --columns), skippedSecrets, already (the file said so already), sync: { value (off, poll
+    30s), from (entry: its own sync:, file: the file's, default: off, as the file writes none) },
+    bigOff (it is over ${BIG_TABLE_ROWS.toLocaleString("en-US")} rows and its entry was written sync: off), notReplicated (why
+    its entry was written sync: poll 5m under a file whose sync: is replication, or null), pollCost (an estimate of
+    what a frequent poll of a big table costs your database, or null) } or { table, error }],
+    file (the sources file), error (when a table was not added: { code, message, why }), next };
+    exit 1 when a table could not be added
 `;
 export const ADD = {
     // the project, not the run: the sources file is the list, so a table is added before mason start as well as after
@@ -1027,7 +1045,7 @@ export const ADD = {
     name: "add",
     summary: "sync tables into Mason, adding them to the sources file: mason add orders (--columns id,status: those only)",
     usage: ADD_USAGE,
-    options: { json: { type: "boolean" }, columns: { type: "string" }, include: { type: "string" }, key: { type: "string" }, sync: { type: "string" } },
+    options: { json: { type: "boolean" }, columns: { type: "string", multiple: true }, include: { type: "string", multiple: true }, key: { type: "string", multiple: true }, sync: { type: "string" } },
     json: ["added", "file", "error", "next"],
 };
 /** `--sync`, read by the sources file's own grammar (src/lib/table-sync.ts parseSync): a sync, or the usage's problem */
@@ -1070,7 +1088,7 @@ export async function add(argv) {
     if (typeof f === "number")
         return f;
     const json = f.values.json === true;
-    const specs = addSpecs(f.positionals, f.values.columns, f.values.include, f.values.key);
+    const specs = addSpecs(f.positionals, listFlag(f.values.columns), listFlag(f.values.include), listFlag(f.values.key));
     if (typeof specs === "string")
         return failed("add", { message: specs, code: "usage", usage: ADD_USAGE }, { json });
     const sync = addSync(f.values.sync);
@@ -1213,7 +1231,7 @@ export function addedLines(b, file) {
         ] };
 }
 // ------------------------------------------------------------------ mason remove
-const REMOVE_USAGE = `usage: mason remove <table>… [--json]
+const REMOVE_USAGE = `usage: mason remove <table>… [--dry-run] [--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
@@ -1223,8 +1241,12 @@ const REMOVE_USAGE = `usage: mason remove <table>… [--json]
 
     mason remove customers
     mason remove customers billing.invoices     several at once
+    mason remove customers --dry-run            what it would remove, changing nothing
 
-  --json   as data: { removed (the tables, schema.table), file (the sources file), next }
+  --dry-run  say which entries would go, and change nothing: the file is read, never written, and neither Mason nor
+             the database is asked
+  --json     as data: { dryRun, removedTables (the tables, schema.table; on a dry run, the ones that would go), removed
+             (the same, kept until 1.0; not on a dry run), file (the sources file), next }
 `;
 export const REMOVE = {
     // the project, not the run, as mason add
@@ -1232,8 +1254,8 @@ export const REMOVE = {
     name: "remove",
     summary: "take tables out of the sources file: mason remove customers (its synced data is dropped)",
     usage: REMOVE_USAGE,
-    options: { json: { type: "boolean" } },
-    json: ["removed", "file", "next"],
+    options: { json: { type: "boolean" }, "dry-run": { type: "boolean" } },
+    json: ["dryRun", "removedTables", "removed", "file", "next"],
 };
 export async function remove(argv) {
     const f = parseCommand(REMOVE, argv);
@@ -1251,6 +1273,8 @@ export async function remove(argv) {
     const readOnly = projectWriteRefusal(where.project.root, process.env);
     if (readOnly !== null)
         return failed("remove", readOnly, { json });
+    if (f.values["dry-run"] === true)
+        return removeDryRun(where.project, where.state === "up", names, 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;
@@ -1272,13 +1296,53 @@ function removedAnswer(r, names, running, json) {
     const next = running ? [["mason status", "the tables left"]]
         : [["mason start", "Mason in the background, for this project: it syncs the tables left"], ["mason status", "the tables left"]];
     if (json) {
-        out(jsonText(REMOVE, { removed: b.removed, file: b.file }, next));
+        out(jsonText(REMOVE, { dryRun: false, removed: b.removed, removedTables: b.removed, file: b.file }, next));
         return 0;
     }
     const rel = path.relative(process.cwd(), b.file);
     out(reportText({ ...removedReport(b.removed, rel.startsWith("..") ? b.file : rel, { running }), next }, styleOut()));
     return 0;
 }
+/**
+ * `mason remove --dry-run`: the entries the sources file would lose, CHANGING NOTHING — read as the edit reads the file
+ * (`sourceToEdit`: its refusals said the same), each name found as the edit finds it (`findEntry`); neither the run nor
+ * the database is asked, so the file's other entries are not checked against the database here, as the edit does.
+ */
+async function removeDryRun(p, up, names, json) {
+    if (!up) {
+        const st = await runState(p);
+        // a hung run refuses the edit itself (withoutRun): a dry run says what the edit would
+        if (st.kind === "hung")
+            return failed("remove", { ...asFailure(notAnswering(p, st.run)), code: "unreachable" }, { json });
+    }
+    const r = edited(() => {
+        const at = sourceToEdit(p.folder, p.root, () => projectSource(p));
+        const tables = names.map((n) => {
+            const e = findEntry(at.parsed, n);
+            if ("problem" in e)
+                throw new Refusal(e.usage ? 400 : 404, e.problem);
+            return e.table;
+        });
+        return { removed: [...new Set(tables)], file: at.file };
+    });
+    if (!("ok" in r)) {
+        return failed("remove", { message: `${names.join(", ")} would not be removed`, code: r.status === 404 ? "not_found" : r.status === 400 ? "usage" : "refused", why: r.error,
+            fix: "nothing was changed (a dry run)", next: [["mason status", "the tables added"]] }, { json });
+    }
+    const b = r.ok;
+    const next = [[`mason remove ${names.join(" ")}`, "remove them"]];
+    if (json) {
+        out(jsonText(REMOVE, { dryRun: true, removedTables: b.removed, file: b.file }, next));
+        return 0;
+    }
+    const rel = path.relative(process.cwd(), b.file);
+    const one = b.removed.length === 1;
+    out(reportText({ headline: `mason remove would remove ${b.removed.join(", ")}; nothing was changed`, details: [["from", rel.startsWith("..") ? b.file : rel]],
+        tips: [up ? `Mason would stop syncing ${one ? "it" : "them"} and drop ${one ? "its" : "their"} synced data at once`
+                : `what an earlier run synced of ${one ? "it" : "them"} would be dropped at the next mason start`,
+            "mason remove also checks the file's other entries against the database, which a dry run does not ask"], next }, styleOut()));
+    return 0;
+}
 /** What `mason remove` prints for the tables removed, `file` the sources file as the reader is shown it (the web page
  *  says the same, src/web/app.js; tests/web-page.test.ts holds the two equal). */
 export function removedReport(removed, file, o = {}) {
@@ -1294,30 +1358,22 @@ export function removedReport(removed, file, o = {}) {
 export function waitTable(t) {
     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 [<generated table>] [--timeout <seconds>] [--json]
+const WAIT_USAGE = `usage: mason wait [<table>…] [--timeout <duration>] [--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
+  Named synced tables: waits for those alone, until the first sync of each is done and it is served. Named, a
+  generated table (alone) 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 --timeout 1h       a large table: wait up to an hour
+    mason wait orders customers   these synced tables only
     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,
-                        kept }] (copy: { phase, rowsCopied, progress: the chunks done, reading and for how long, the
-                        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; 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)
+  --timeout <duration>  how long to wait (default 600, seconds; 10m, 1h); the sync goes on after, and mason wait
+                        again picks it up
+  --json                as data: its shape is at the end
 
   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
@@ -1325,6 +1381,19 @@ const WAIT_USAGE = `usage: mason wait [<generated table>] [--timeout <seconds>]
   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.
+
+  The --json answer, once it ends: { ready, failed, waiting, timedOut, tables: [{ table, copy, error,
+    kept }] (copy: { phase, rowsCopied, progress: the chunks done, reading and for how long, the
+    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; 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)
 `;
 /** 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 */
@@ -1337,7 +1406,7 @@ export function sayAgain(what, said, saidAt, now, every = SAY_AGAIN_MS) {
 export const WAIT = {
     needs: "run",
     name: "wait",
-    summary: "wait until every added table is synced, or a generated table holds what is synced now (1: a failure)",
+    summary: "wait until every added table (or those named) 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", "generatedTable", "error", "next"],
@@ -1347,18 +1416,26 @@ export async function wait(argv) {
     if (typeof f === "number")
         return f;
     const json = f.values.json === true;
-    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 read = parseDuration(typeof f.values.timeout === "string" ? f.values.timeout : "600");
+    if ("problem" in read)
+        return failed("wait", { message: `--timeout ${read.problem}`, code: "usage", usage: WAIT_USAGE }, { json });
+    const timeout = read.seconds;
+    const named = [...new Set(f.positionals)];
     const run = await runOr(WAIT, json);
     if (!run)
         return 1;
-    if (named !== undefined)
-        return waitGenerated(run, named, timeout, json);
     return guarded("wait", json, async () => {
+        // tables named: a generated table alone waits for its chain; synced tables for their first syncs alone
+        let only = null;
+        if (named.length) {
+            const pick = waitPick(await readState(run), named);
+            if ("message" in pick)
+                return failed("wait", pick, { json });
+            if ("generated" in pick)
+                return waitGenerated(run, pick.generated, timeout, json);
+            only = new Set(pick.tables);
+        }
+        const again = named.length ? `mason wait ${named.join(" ")}` : "mason wait";
         const until = Date.now() + timeout * 1000;
         // a terminal gets the block — every added table on its line (tableLines), then the stream — redrawn in place;
         // anything else (a coding agent's shell, a log) the block when what is under way changes, and every 30 s, so a
@@ -1390,10 +1467,18 @@ export async function wait(argv) {
         };
         for (;;) {
             // a copy's rate and progress are the run's own, measured per chunk (src/duck/sync.ts copyProgressNow)
-            const s = await readState(run);
+            const all = await readState(run);
+            // named tables: the wait reads them alone, so its lines, its readiness and its answer are theirs
+            const s = only === null ? all : { ...all, tables: all.tables.filter((t) => only.has(t.table)) };
             const r = readiness(s);
             const done = r.ready || r.failed.length > 0;
             const picked = s.tables.filter((t) => t.added);
+            // a table named and removed while it is waited for (mason remove, the page) has nothing left to wait for
+            if (only !== null && picked.length < only.size) {
+                const gone = [...only].filter((n) => !picked.some((t) => t.table === n));
+                return failed("wait", { message: `${gone.join(", ")} ${gone.length === 1 ? "is" : "are"} not added any more`, code: "not_found",
+                    next: [["mason status", "the added tables"]] }, { json });
+            }
             // the outcome and what to run next, the same for a person and under --json
             const readyNext = picked.length ? [...READY_STEPS] : addSteps(s.tables);
             const failure = r.failed.length
@@ -1402,7 +1487,7 @@ export async function wait(argv) {
                     next: [["mason logs", "the detail of each failure"], ["mason status", "the rest of the project"]] }
                 : !done && Date.now() >= until
                     ? { message: `not ready after ${timeout} s`, code: "timeout", why: r.waiting.join("\n"), fix: "nothing stopped: the syncs go on",
-                        next: [["mason wait", "keep waiting (--timeout <seconds> for longer)"], ["mason status", "what Mason is doing"]] }
+                        next: [[again, "keep waiting (--timeout <duration> for longer)"], ["mason status", "what Mason is doing"]] }
                     : null;
             if (json && (done || failure)) {
                 out(jsonText(WAIT, { ...r, timedOut: !done, tables: picked.map(waitTable),
@@ -1414,7 +1499,9 @@ export async function wait(argv) {
             const meanwhile = done ? [] : [...(copied ? [["mason user add <name>", "a user for your BI tool or psql: a synced table can be queried now"]] : []), ["mason status", "what Mason is doing"]];
             show([...tableLines(s), ...(s.stream ? ["Stream:", ...streamLines(s.stream).map((l) => `  ${l}`)] : [])], meanwhile); // done: the meanwhile Next is dropped
             if (r.ready) {
-                const head = !picked.length ? "Nothing to wait for: no table added yet." : "Ready: every added table is synced and served.";
+                const head = !picked.length ? "Nothing to wait for: no table added yet."
+                    : only !== null ? `Ready: ${picked.map((t) => t.table).join(", ")} ${picked.length === 1 ? "is" : "are"} synced and served.`
+                        : "Ready: every added table is synced and served.";
                 if (!json)
                     out(withEnd(picked.length ? styleOut().green(head) : head, { next: readyNext }));
                 return 0;
@@ -1425,6 +1512,44 @@ export async function wait(argv) {
         }
     });
 }
+/**
+ * WHAT `mason wait <table>…` WAITS FOR: a generated table named alone (its chain: `waitGenerated`), or synced tables, each
+ * found among the added ones as `mason sync` finds them (`findTable`) — a table of the database not added, or a name
+ * nothing has, refused with the way out.
+ */
+export function waitPick(s, names) {
+    const generated = s.generatedTables ?? [];
+    const added = s.tables.filter((t) => t.added);
+    const tables = [];
+    for (const name of names) {
+        const g = generated.find((t) => t.table === name || t.table === `public.${name}`);
+        if (g !== undefined) {
+            if (names.length > 1) {
+                return { message: `${entryName(g.table)} is a generated table, which is waited for alone`, code: "usage",
+                    fix: `mason wait ${entryName(g.table)}, then mason wait ${names.filter((n) => n !== name).join(" ")}`, next: [["mason wait --help", "what a wait waits for"]] };
+            }
+            return { generated: name };
+        }
+        const t = findTable(added, name);
+        if (!("message" in t)) {
+            tables.push(t.table);
+            continue;
+        }
+        // a table of the database that is not added is told so, with the command that adds it
+        const db = findTable(s.tables, name);
+        if ("message" in db && db.code === "usage")
+            return db;
+        if (!("message" in db)) {
+            return { message: `${db.table} is not added, so Mason does not sync it`, code: "not_found", fix: `mason add ${tableArg(db.table)}`, next: [["mason status", "the added tables"]] };
+        }
+        const choices = [...added.flatMap((x) => [x.table, tableArg(x.table)]), ...generated.map((x) => entryName(x.table))];
+        const named = [...added.map((x) => tableArg(x.table)), ...generated.map((x) => entryName(x.table))];
+        return { message: `there is no added or generated table ${JSON.stringify(name)}${didYouMean(name, choices)}`, code: "not_found",
+            ...(named.length ? { fix: `name one of: ${named.join(", ")}` } : {}),
+            next: [["mason status", "the added tables and the generated ones"], ["mason tables", "the database's tables"]] };
+    }
+    return { tables: [...new Set(tables)] };
+}
 /** `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) {
@@ -1446,7 +1571,7 @@ async function waitGenerated(run, named, timeout, json) {
                 ? { 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] }
+                        next: [[`mason wait ${entryName(g.table)}`, "keep waiting (--timeout <duration> 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));
@@ -1476,17 +1601,7 @@ export const EVENTS_LEAVE_OUT = "A scheduled poll that succeeds is not listed: t
 const LOGS_USAGE = `usage: mason logs [-n <lines>] [-f] [--start] [--requests [<filters>]] [--events [--failed]] [--running] [--json]
 
   The last lines of Mason's log: every sync, poll and statement it ran, warnings and errors with their reasons —
-  running or not. With --requests, the run's request log instead: every statement a tool sent the
-  Postgres API that Mason answered, and every one it refused, failed or cancelled, a line each, newest last — when, the
-  outcome and SQLSTATE, how long, the rows sent, the client's application_name (and the mason user's name), the
-  statement and the error's first line; the filters narrow it, and a page that has older rows ends with the line that
-  reads them (--before). With --events, the sync's events: each first sync that failed or finished, each poll, catch-up or
-  stream that failed, the database out of reach, a table current again, each sync asked by hand (mason sync, the
-  page's Sync now) and what it did, and each restart of the run — a line each, newest last (a failure repeated word for
-  word is said once an hour). 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). Both are kept MASON_HISTORY_DAYS days
-  (default 7) in the run's synced data, and read through the running Mason. With --running, the statements running now
-  instead, one per session, each with its number (mason cancel <session> --statement <n> stops one).
+  running or not.
 
     mason logs
     mason logs -f                 keep printing new lines as Mason works, until Ctrl-C
@@ -1505,7 +1620,8 @@ const LOGS_USAGE = `usage: mason logs [-n <lines>] [-f] [--start] [--requests [<
   --failed         with --requests: only the ones not answered (refused, failed or cancelled); with --events: only
                    the failures
   --outcome <o,…>  with --requests: only these outcomes — ok, refused (the statement's own fault), failed (Mason's or
-                   the machine's), cancelled (a cancel or a statement timeout, SQLSTATE 57014)
+                   the machine's), cancelled (a cancel or a statement timeout, SQLSTATE 57014); a comma list or
+                   the flag repeated, the same
   --since <time>   with --requests: started at or after it — an age (30m, 2h, 7d) or an ISO 8601 date or time with
                    its zone (2026-10-28, 2026-10-28T09:00:00Z)
   --until <time>   with --requests: started before it (as --since)
@@ -1515,18 +1631,32 @@ const LOGS_USAGE = `usage: mason logs [-n <lines>] [-f] [--start] [--requests [<
   --search <text>  with --requests: only the statements whose text has it, in any case (at most ${MAX_SEARCH} characters)
   --before <pos>   with --requests: the page before: the position a page answered with (its last Next line)
   --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,
-                   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,
-                   catch_up_failed, stream_failed, source_unreachable, restart, copied, recovered, synced (a sync
-                   asked by hand), sync_changed (a table's sync: changed)), failed, table (null: the whole sync),
-                   message }], keptDays }; with --running { running: [{ session, user,
-                   applicationName, method, startedAt, runningMs, rows (sent so far), query, queryTruncated }] }; next
+  --json           as data: its shape is at the end
+
+  With --requests, the run's request log instead: every statement a tool sent the
+  Postgres API that Mason answered, and every one it refused, failed or cancelled, a line each, newest last — when, the
+  outcome and SQLSTATE, how long, the rows sent, the client's application_name (and the mason user's name), the
+  statement and the error's first line; the filters narrow it, and a page that has older rows ends with the line that
+  reads them (--before). With --events, the sync's events: each first sync that failed or finished, each poll, catch-up or
+  stream that failed, the database out of reach, a table current again, each sync asked by hand (mason sync, the
+  page's Sync now) and what it did, and each restart of the run — a line each, newest last (a failure repeated word for
+  word is said once an hour). 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). Both are kept MASON_HISTORY_DAYS days
+  (default 7) in the run's synced data, and read through the running Mason. With --running, the statements running now
+  instead, one per session, each with its number (mason cancel <session> --statement <n> stops one).
+
+  The --json answer: { 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,
+    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,
+    catch_up_failed, stream_failed, source_unreachable, restart, copied, recovered, synced (a sync
+    asked by hand), sync_changed (a table's sync: changed)), failed, table (null: the whole sync),
+    message }], keptDays }; with --running { running: [{ session, user,
+    applicationName, method, startedAt, runningMs, rows (sent so far), query, queryTruncated }] }; next
 `;
 export const LOGS = {
     needs: "project",
@@ -1534,7 +1664,7 @@ export const LOGS = {
     summary: "Mason's log (-f follows it); --requests: the Postgres API's statements; --events: the sync's; --running: running now",
     usage: LOGS_USAGE,
     options: { lines: { type: "string", short: "n" }, follow: { type: "boolean", short: "f" }, start: { type: "boolean" },
-        requests: { type: "boolean" }, events: { type: "boolean" }, failed: { type: "boolean" }, outcome: { type: "string" }, since: { type: "string" },
+        requests: { type: "boolean" }, events: { type: "boolean" }, failed: { type: "boolean" }, outcome: { type: "string", multiple: true }, since: { type: "string" },
         until: { type: "string" }, user: { type: "string" }, client: { type: "string" }, slow: { type: "boolean" }, search: { type: "string" }, before: { type: "string" }, running: { type: "boolean" }, json: { type: "boolean" } },
     json: ["lines", "requests", "events", "keptDays", "before", "running", "next"],
 };
@@ -1674,7 +1804,7 @@ async function runningLogs(json) {
 /** A refusal the run answered, in the Failure shape it carries (`failure`, src/cli/run-server.ts sendFailure). */
 export function runFailure(reply, next) {
     const f = reply.body.failure;
-    const code = typeof f?.code === "string" ? f.code : reply.status === 400 ? "usage" : reply.status === 404 ? "not_found" : reply.status === 409 ? "refused" : "failed";
+    const code = failureCode(f?.code, reply.status === 400 ? "usage" : reply.status === 404 ? "not_found" : reply.status === 409 ? "refused" : "failed");
     return { message: typeof f?.message === "string" ? f.message : String(reply.body.error ?? `the run answered ${reply.status}`), code,
         ...(typeof f?.why === "string" ? { why: f.why } : {}), ...(typeof f?.fix === "string" ? { fix: f.fix } : {}), next };
 }
@@ -1682,6 +1812,9 @@ export async function logs(argv) {
     const f = parseCommand(LOGS, argv);
     if (typeof f === "number")
         return f;
+    const extra = noArguments(LOGS, f.positionals, f.values.json === true);
+    if (extra !== null)
+        return extra;
     const json = f.values.json === true;
     if (f.values.requests && f.values.events)
         return failed("logs", { message: "--requests and --events are two lists: ask for one", code: "usage", fix: "mason logs --requests, or mason logs --events" }, { json });
@@ -1711,7 +1844,7 @@ export async function logs(argv) {
     if (f.values.requests) {
         // the filters, read as the run reads its query string (src/cli/request-filter.ts): a mistake is said here, exit 2
         const text = (v) => typeof v === "string" ? v : undefined;
-        const q = requestFilter({ limit: text(f.values.lines), failed: f.values.failed === true, outcome: text(f.values.outcome), since: text(f.values.since),
+        const q = requestFilter({ limit: text(f.values.lines), failed: f.values.failed === true, outcome: listFlag(f.values.outcome), since: text(f.values.since),
             until: text(f.values.until), user: text(f.values.user), client: text(f.values.client),
             slow: f.values.slow === true, search: text(f.values.search), before: text(f.values.before) }, Date.now(), flagOf);
         if ("message" in q)
@@ -1775,9 +1908,9 @@ const STOP_USAGE = `usage: mason stop [--json]
 
     mason stop
 
-  mason destroy removes the synced data and the state too (your files stay), to free the disk or begin again.
-
   --json    as data: { stopped: [name], killed (a run that did not answer and ignored SIGTERM), supervisor (its pid, when one was stopped), next }
+
+  mason destroy removes the synced data and the state too (your files stay), to free the disk or begin again.
 `;
 export const STOP = {
     needs: "project",
@@ -1791,6 +1924,9 @@ export async function stop(argv) {
     const f = parseCommand(STOP, argv);
     if (typeof f === "number")
         return f;
+    const extra = noArguments(STOP, f.positionals, f.values.json === true);
+    if (extra !== null)
+        return extra;
     const json = f.values.json === true;
     const next = [["mason start", "resume, in seconds (in the project's folder)"], ["mason destroy", "remove its synced data and its state; your files stay"]];
     const r = await theRun(process.cwd());