@mason-data/cli 0.7.0 → 0.8.0

package/dist/src/cli/metrics.js

@@ -0,0 +1,79 @@
+/** The content type of the text exposition format, version 0.0.4. */
+export const METRICS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/**
+ * HOW MANY SAMPLES OLD A NUMBER READ FROM THE DATABASE (the stream's position, the slot) or THE SAMPLER (p50 / p95) may
+ * be and still be said: the sampler refreshes each once a minute (src/duck/usage.ts SAMPLE_SECONDS), and a scrape never
+ * reads them itself (src/cli/run-server.ts `metricsFacts`), so one older than two samples means the sampler could not
+ * take them — said as unknown (absent), never as a stale number that looks current.
+ */
+export const FRESH_SAMPLES = 2;
+/** a label value escaped as the format says: backslash, double quote and line feed */
+const labelValue = (v) => v.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", "\\n");
+/** a sample's value: an integer as written, a fraction as JavaScript prints it (Go's ParseFloat reads both) */
+const valueText = (n) => (Number.isInteger(n) ? n.toFixed(0) : String(n));
+/** a sample that must be a count: a whole number, at least 0 */
+const isCount = (s, kind) => kind === "counter" || s.suffix === "_count";
+/** One metric's lines, its HELP and TYPE first — or none, the WHOLE family absent, when a sample it needs is unknown
+ *  or any value is not finite (or a count not a whole number). */
+function metric(name, kind, help, samples) {
+    const whole = samples.every((s) => s.value === null ? s.optional === true
+        : Number.isFinite(s.value) && (!isCount(s, kind) || (Number.isInteger(s.value) && s.value >= 0)));
+    const kept = samples.filter((s) => s.value !== null);
+    if (!whole || kept.length === 0)
+        return [];
+    const lines = [`# HELP ${name} ${help.replaceAll("\\", "\\\\").replaceAll("\n", "\\n")}`, `# TYPE ${name} ${kind}`];
+    for (const s of kept) {
+        const labels = s.labels ? Object.entries(s.labels).map(([k, v]) => `${k}="${labelValue(v ?? "")}"`).join(",") : "";
+        lines.push(`${name}${s.suffix ?? ""}${labels ? `{${labels}}` : ""} ${valueText(s.value)}`);
+    }
+    return lines;
+}
+/** The PHASES `mason_tables` says, in order: the sync's (src/duck/sync.ts `CopyState.phase`), as `/healthz` counts them. */
+export const TABLE_PHASES = ["copied", "copying", "waiting", "failed"];
+/** The OUTCOMES `mason_statements_total` says: the request log's (`outcomeOf`), `ok` said as `completed`. */
+export const STATEMENT_OUTCOMES = ["completed", "failed", "refused", "cancelled"];
+/**
+ * THE BODY OF `GET /metrics`. Starting or stopping: `mason_ready 0` and `mason_info` alone (a scrape must not fail
+ * while Mason starts; whether it is up is `/healthz`'s to say). Serving: `mason_ready 1` and the run's numbers.
+ */
+export function metricsText(f) {
+    const lines = [
+        ...metric("mason_ready", "gauge", "1 once Mason serves the synced data; 0 while it starts or stops (/healthz answers 503 then).", [{ value: f.run === null ? 0 : 1 }]),
+        ...metric("mason_info", "gauge", "Mason's version, as a label; the value is always 1.", [{ labels: { version: f.version }, value: 1 }]),
+    ];
+    const r = f.run;
+    if (r !== null) {
+        const u = r.usage, st = r.statements;
+        // a number read from the database (the stream's position, the slot) as of `readAt`: said only while fresh
+        const fresh = (value, readAt) => readAt !== null && isFresh(r, readAt) ? value : null;
+        lines.push(...metric("mason_uptime_seconds", "gauge", "Seconds since mason serve started.", [{ value: r.uptimeSeconds }]), ...metric("mason_tables", "gauge", "The synced tables the run holds, by phase (a removed table's data is held until dropped).", TABLE_PHASES.map((phase) => ({ labels: { phase }, value: u.tables[phase] }))), ...metric("mason_copy_bytes", "gauge", "The size of the synced data's file on disk, bytes.", [{ value: u.copyBytes }]), ...metric("mason_copy_rows", "gauge", "The rows of the synced tables served.", [{ value: u.totals.rows }]), 
+        // absent, not NaN, before any added table was synced: nothing has an age yet (see the module's comment)
+        ...metric("mason_sync_oldest_age_seconds", "gauge", "Seconds since the stalest added table was last brought current; absent before any sync.", [{ value: u.oldestSyncSeconds }]), 
+        // absent where no table is replicated (the run polls): a 0 would claim a stream that is not there. The database's
+        // position under the bytes, and the slot, are as the sampler last read them (a scrape never asks the database):
+        // absent when that is more than FRESH_SAMPLES samples old. The seconds are the run's own clock against the last
+        // batch's commit time, read from nothing: current at every scrape
+        ...metric("mason_stream_lag_bytes", "gauge", "Replication: WAL bytes between the database's position (as last sampled, at most two samples old) and what Mason has applied; absent when nothing is replicated or not known.", [{ value: fresh(u.streamLag?.bytes ?? null, u.streamLagReadAt) }]), ...metric("mason_stream_lag_seconds", "gauge", "Replication: seconds since the newest change applied was committed on the database; absent when nothing is replicated.", [{ value: u.streamLag?.seconds ?? null }]), ...metric("mason_slot_wal_held_bytes", "gauge", "Replication: WAL bytes the replication slot holds on the database (as last sampled, at most two samples old); absent when nothing is replicated or not known.", [{ value: fresh(u.slotWalHeldBytes, u.slotWalReadAt) }]), ...metric("mason_disk_free_bytes", "gauge", "Bytes free on the disk the synced data is on.", [{ value: u.diskFreeBytes }]), ...metric("mason_sessions_open", "gauge", "Sessions logged in to Mason's Postgres API now.", [{ value: u.sessionsOpen }]), ...metric("mason_statements_total", "counter", "Statements the listener answered since the process started, whether or not the request log kept each, by outcome (refused: the statement's fault; failed: Mason's or the machine's).", STATEMENT_OUTCOMES.map((outcome) => ({ labels: { outcome }, value: outcome === "completed" ? st.completed : st[outcome] }))), ...durationSummary(r));
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** a time `readAt` (ISO) at most `freshSeconds` before the facts were read */
+const isFresh = (r, readAt) => (r.at - Date.parse(readAt)) / 1000 <= r.freshSeconds;
+/**
+ * `mason_statement_duration_seconds`, a summary: the quantiles are the last usage sample's (its minute's completed
+ * statements, as `mason usage` says them: src/duck/usage.ts `lastDurations`; past DURATIONS_KEPT in a minute, of a
+ * uniform sample of them), absent before the first sample, for a minute none completed, and when the last sample is
+ * more than FRESH_SAMPLES samples old (a sample that could not be taken keeps the one before); `_sum` and `_count` are
+ * the completed statements since the process started (the counter), as a Prometheus client's summary is: quantiles
+ * over a recent window, sum and count cumulative.
+ */
+function durationSummary(r) {
+    const d = r.durations !== null && isFresh(r, r.durations.at) ? r.durations : null;
+    const seconds = (ms) => (ms === null || ms === undefined ? null : ms / 1000);
+    return metric("mason_statement_duration_seconds", "summary", "Completed statements' duration, seconds: p50 and p95 of the last minute's usage sample (sampled: a busy minute's of a uniform sample); sum and count since the process started.", [
+        { labels: { quantile: "0.5" }, value: seconds(d?.p50Ms), optional: true },
+        { labels: { quantile: "0.95" }, value: seconds(d?.p95Ms), optional: true },
+        { suffix: "_sum", value: r.statements.completedMs / 1000 },
+        { suffix: "_count", value: r.statements.completed },
+    ]);
+}

package/dist/src/cli/pg-tls.js

@@ -42,22 +42,30 @@ export function runListenerSettings(shell, o) {
         ...(s.fix ? { fix: s.kind === "plain" ? `${s.fix}. Or mason start --self-signed-tls: a certificate made for this project in .mason/` : s.fix } : {}),
         ...(s.kind === "plain" ? { next: [["mason start --self-signed-tls", "TLS from a certificate made in .mason/ (clients connect with sslmode=require)"]] } : {}) };
 }
+/** The name in every self-signed certificate: a certificate is handed to whoever connects, before any login, so it
+ *  names no project. */
+const SELF_SIGNED_NAME = "mason";
 /**
  * The project's self-signed certificate: the one in `.mason/` when it is still good (it parses, its key is its own, it
- * has not expired), else a new one, both files 0600. `said` is why a new one was made, for the run to print.
+ * has not expired, it names no project), else a new one, both files 0600. `said` is why a new one was made, for the run to print.
  */
-export function ensureSelfSigned(home, project, now = new Date()) {
+export function ensureSelfSigned(home, now = new Date()) {
     const certFile = path.join(home, SELF_SIGNED_FILES.cert), keyFile = path.join(home, SELF_SIGNED_FILES.key);
     const kept = keptCertificate(certFile, keyFile, now);
     if ("fingerprint" in kept)
         return { fingerprint: kept.fingerprint, said: null };
-    const made = selfSignedCertificate(`mason-${project}`, { now });
+    const made = selfSignedCertificate(SELF_SIGNED_NAME, { now });
     for (const [file, text] of [[keyFile, made.key], [certFile, made.cert]]) {
         fs.writeFileSync(file, text, { mode: 0o600 });
         fs.chmodSync(file, 0o600); // a file that was there keeps its mode through writeFileSync
     }
     return { fingerprint: new crypto.X509Certificate(made.cert).fingerprint256, said: kept.why };
 }
+/** The project's self-signed certificate as a listener reads it: the two files of `ensureSelfSigned`, and what it said. */
+export function selfSignedPair(home) {
+    const { fingerprint, said } = ensureSelfSigned(home);
+    return { cert: fs.readFileSync(path.join(home, SELF_SIGNED_FILES.cert)), key: fs.readFileSync(path.join(home, SELF_SIGNED_FILES.key)), fingerprint, said };
+}
 function keptCertificate(certFile, keyFile, now) {
     if (!fs.existsSync(certFile) || !fs.existsSync(keyFile))
         return { why: `made a self-signed certificate: .mason/${SELF_SIGNED_FILES.cert}` };
@@ -65,6 +73,8 @@ function keptCertificate(certFile, keyFile, now) {
         const x = new crypto.X509Certificate(fs.readFileSync(certFile));
         if (!x.checkPrivateKey(crypto.createPrivateKey(fs.readFileSync(keyFile))))
             return { why: `made a new self-signed certificate: .mason/${SELF_SIGNED_FILES.key} was not the key of .mason/${SELF_SIGNED_FILES.cert}` };
+        if (x.subject !== `CN=${SELF_SIGNED_NAME}` || x.issuer !== `CN=${SELF_SIGNED_NAME}`)
+            return { why: "made a new self-signed certificate: the one in .mason/ named this project to whoever connected" };
         if (new Date(x.validTo).getTime() <= now.getTime())
             return { why: `made a new self-signed certificate: the one in .mason/ expired ${x.validTo}` };
         return { fingerprint: x.fingerprint256 };

package/dist/src/cli/pg-url.js

@@ -40,6 +40,10 @@ export const withPlaceholders = (recorded) => recorded.replace(/^postgresql:\/\/
 export const withoutPlaceholders = (shown) => shown.replace(/^postgres:\/\/<user>:<password>@/, "postgresql://");
 /** The psql line for a URL, quoted for a shell. */
 export const psqlLine = (url) => `psql ${shellWord(url)}`;
+/** WHERE A TOOL CONNECTS, as `mason status --json` and `/api/state` say it (`postgres`): the recorded URL's parts, the
+ *  URL with the credentials' place shown (`shown`, what `mason start` and `mason status` print) and its psql line — one
+ *  builder, so the web page's Connect panel and the commands print the same line. */
+export const postgresFacts = (recorded) => ({ ...postgresLink(recorded), shown: withPlaceholders(recorded), psql: psqlLine(withPlaceholders(recorded)) });
 /** What a tool connecting to the listener should know: it listens on every address; its certificate is self-signed. */
 export function listenerTips(l) {
     if (l === null)

package/dist/src/cli/pin.js

@@ -1,24 +1,25 @@
 /**
  * THE PROJECT'S VERSION PIN, as the mason command holds it (src/lib/project-version.ts has the rule and the image's
  * side): `mason init` writes `mason.yml` with this command's version, `mason start` writes it into a project made
- * before there was one, and `mason init` and `mason start` refuse a command of another release line — what the
- * developer runs is then what production's image is held to.
+ * before there was one, and `mason init`, `mason start` and a `mason serve` of the package refuse a command of another
+ * release line — what the developer runs is then what production is held to.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { parseVersion, pinFileText, pinProblem, readPin, versionText, PIN_FILE } from "../lib/project-version.js";
+import { parseVersion, pinFileText, projectPinProblem, PIN_FILE } from "../lib/project-version.js";
 /** Why this mason command may not run the project in `folder`, or null (a checkout's `dev` checks nothing). */
+export function commandPinProblem(folder, cliVersion) {
+    return projectPinProblem(folder, cliVersion, { what: "this mason command",
+        run: (p) => `run the mason command it names: npm i -g @mason-data/cli@${p} (or npx @mason-data/cli@${p} …)` });
+}
+const sentence = (clause) => `${clause[0].toUpperCase()}${clause.slice(1)}.`;
+/** The refusal as `mason init` and `mason start` say it: one line of sentences. */
 export function cliPinProblem(folder, cliVersion) {
-    const running = parseVersion(cliVersion);
-    if (running === null)
-        return null;
-    const read = readPin(folder);
-    if ("problem" in read)
-        return read.problem;
-    if (read.pin === null)
+    const r = commandPinProblem(folder, cliVersion);
+    if (r === null)
         return null;
-    const p = versionText(read.pin);
-    return pinProblem(read.pin, running, read.file, "this mason command", `Run the mason command it names: npm i -g @mason-data/cli@${p} (or npx @mason-data/cli@${p} …).`);
+    const [run, ...others] = r.ways;
+    return run === undefined ? r.problem : [`${r.problem}.`, sentence(run), ...others.map((w) => sentence(`or ${w}`))].join(" ");
 }
 /**
  * Write `folder`'s mason.yml with this command's version when it has none; the file written, or null when there was one

package/dist/src/cli/preflight.js

@@ -149,7 +149,7 @@ export const VIEWS_SQL = `SET LOCAL search_path = pg_catalog; SELECT coalesce(js
 ) v`;
 /** One catalog read: every ordinary or partitioned table outside the system schemas, its key, size, comments and FKs. */
 export const TABLES_SQL = `SELECT json_agg(t ORDER BY t.schema, t.table)::text FROM (
-  SELECT n.nspname AS schema, c.relname AS table, c.oid, c.reltype AS row_type_oid,
+  SELECT n.nspname AS schema, c.relname AS table, c.oid, c.reltype AS row_type_oid, c.relreplident AS replica_identity,
     -- a PARTITIONED table's rows and bytes are its leaves' (its own are -1 / 0 and ~0 bytes); "never analysed" is
     -- relpages = 0 AND reltuples <= 0 on any leaf, which Postgres 13 (reltuples 0) and 14+ (-1) both read
     CASE WHEN c.relkind = 'p'
@@ -221,6 +221,7 @@ export async function readSourceFacts(pg, counted = COUNTED) {
             foreignKeys: t.foreign_keys.map((f) => ({ column: f.column, target: f.target, targetColumn: f.target_column })),
             uniqueKeys: t.unique_keys.map((u) => ({ name: u.name, columns: u.columns, constraint: u.constraint, nullsNotDistinct: u.nulls_not_distinct })),
             ...(t.row_type_oid > 0 ? { rowTypeOid: t.row_type_oid } : {}),
+            ...(t.replica_identity === "d" || t.replica_identity === "n" || t.replica_identity === "f" || t.replica_identity === "i" ? { replicaIdentity: t.replica_identity } : {}),
         });
     }
     // the columns differ by version (datlocprovider from 15, daticulocale 15–16, datlocale from 17): read the row whole
@@ -261,7 +262,7 @@ export function serverlessHost(host) {
  *  on a database elsewhere (the tables worth copying are the big ones). */
 export function unpickableReason(t) {
     if (t.key.length === 0)
-        return "no primary key: Mason keeps one row per key, so it can only copy a table that has one";
+        return "no primary key: Mason keeps one row per key, so it can only sync a table that has one";
     return null;
 }
 /** The warnings `mason start` prints, and `mason status` shows, before anything is copied. */
@@ -280,8 +281,8 @@ export function sourceWarnings(s, f) {
 /** The warning a database on another machine gets at every start: what the copy is and how it is kept current (true of
  *  both modes — the mode is the start's, not known here: a poll scans each table, replication reads the change log). */
 export function remoteWarning(s) {
-    return `${s.host} is not this machine. mason start will copy the tables you pick to this machine (into its copy's file, ` +
-        "with no access control beyond this machine's), and keep them current while it runs: a scan of each table at every poll, or its change log with --replication";
+    return `${s.host} is not this machine. mason start will sync the tables you pick to this machine (into its synced data's file, ` +
+        "with no access control beyond this machine's), and keep them current while it runs: a scan of each table at every poll, or its change log for a table whose sync: is replication";
 }
 /**
  * THE CONFIRMATION A DATABASE ON ANOTHER MACHINE NEEDS (the refusal read as a failed connection and then a fix: only a
@@ -291,9 +292,9 @@ export function remoteWarning(s) {
  */
 export function remoteConfirmation(host, o) {
     return { code: "failed", exit: 1,
-        message: `stopped before ${o.cmd === "mason init" ? "writing anything" : "starting"}: ${host} is on another machine, and copying from it needs your say-so`,
-        why: "mason start would copy the tables you pick to this machine: a file under .mason/, with no access control beyond this machine's\n" +
-            "and keep them current while it runs by reading that database: a scan of each table at every poll, or its change log with --replication",
+        message: `stopped before ${o.cmd === "mason init" ? "writing anything" : "starting"}: ${host} is on another machine, and syncing from it needs your say-so`,
+        why: "mason start would sync the tables you pick to this machine: a file under .mason/, with no access control beyond this machine's\n" +
+            "and keep them current while it runs by reading that database: a scan of each table at every poll, or its change log for a table whose sync: is replication",
         fix: o.wayOut, next: o.next };
 }
 /** `pg_current_snapshot()` and xid8, which polling reads, arrived in Postgres 13. */

package/dist/src/cli/project.js

@@ -18,11 +18,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomBytes } from "node:crypto";
-import { readSource } from "./sources.js";
+import { connectDatabase, databaseSettingRefusal } from "../lib/database-name.js";
+import { changesRetired, pollMsRetired } from "../lib/table-sync.js";
+import { readSource, sourcesTop, writtenDatabase } from "./sources.js";
 export const STATE_DIR = ".mason";
 const CONFIG = "config.json";
-/** A project's name: the database name a tool connects to on the Postgres API, and (with the source's) what its
- *  replication slot is named for. */
+/** A project's name: what its commands call it and (with the source's) what its replication slot is named for. Never
+ *  the database name a tool connects with: src/lib/database-name.ts. */
 export const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,47}$/;
 /** The copy of the data, a DuckDB file in the project's `.mason/`: kept by mason stop, deleted by mason destroy. */
 export const DUCK_FILE = "duck.db";
@@ -113,7 +115,7 @@ export function theProject(cwd) {
     if (p)
         return { project: p };
     return { problem: "no Mason project here or above", code: "no_project", fix: "cd into a project's folder, or make this folder one (mason init demo: a demo database, nothing to install)",
-        next: [["mason init", "make this folder a project (DATABASE_URL from .env, or mason init postgres://…)"]] };
+        next: [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"]] };
 }
 /** Whether `root`'s .gitignore already ignores `.mason/`. */
 export function ignoresStateDir(gitignore) {
@@ -127,3 +129,40 @@ export function ignoresStateDir(gitignore) {
 export function projectSource(p, env = process.env, o = {}) {
     return readSource(p.folder, p.root, env, o);
 }
+/**
+ * THE DATABASE NAME THE PROJECT'S NEXT RUN WILL ANSWER AS, with Mason stopped (a run's is in its URL: `postgresLink`): by
+ * the one rule, from the sources file's one key, so it needs neither the database's URL nor the rest of the file right.
+ */
+export function projectDatabase(p, env = process.env) {
+    const written = writtenDatabase(p.folder, p.root);
+    return "message" in written ? written : connectDatabase(written, p.config, env);
+}
+/**
+ * THE NAME THE SOURCES FILE HAS MOVED TO SINCE A RUN STARTED answering as `answersAs` (the name is read at the start), or
+ * null. Only what the file says: a server's run may be named by its setting, in an environment the shell asking need
+ * not have, so a served project whose file writes no name has nothing to compare; a file that cannot be read is said
+ * as such by the commands that read it.
+ */
+export function databaseMoved(p, answersAs) {
+    const written = writtenDatabase(p.folder, p.root);
+    if ("message" in written || (written.database === null && p.config.served === true))
+        return null;
+    const says = connectDatabase(written, {}, {});
+    return says === answersAs ? null : says;
+}
+/**
+ * A SETTING A START REFUSES, for the start that is typed and the run it spawns alike: read by the parent where the person
+ * (or --json) reads the answer, and by the run, which `mason start --attach` and `mason serve` reach without the parent.
+ * One list, because a check in the run alone reaches a background start as "the run stopped", its way out in a log.
+ */
+export function startSettingRefusal(p, env, o) {
+    const top = () => sourcesTop(p.root, p.folder);
+    const pollMs = pollMsRetired(env, top);
+    if (pollMs !== null)
+        return { code: "refused", ...pollMs };
+    const changes = changesRetired(env, top);
+    if (changes !== null)
+        return { code: "refused", ...changes };
+    const database = o.serve ? null : databaseSettingRefusal(env, top().shown);
+    return database === null ? null : { code: "refused", ...database };
+}

package/dist/src/cli/readiness.js

@@ -8,11 +8,13 @@ export function duration(seconds) {
     const m = Math.round(s / 60);
     return m < 90 ? `${m} min` : `${Math.floor(m / 60)} h ${m % 60} min`;
 }
+/** A duration in milliseconds as a person reads it (src/lib/table-sync.ts, where the sync reads it too). */
+export { msText } from "../lib/table-sync.js";
 /**
  * WHAT A COPYING TABLE'S LINE SAYS, AND HOW FULL ITS BAR IS (a 20 M-row copy over the internet showed no progress: its
  * first line waited on 0 for minutes, then jumped to 100%). A copy's rows
  * land a chunk at a time, so the count is the committed chunks' rows PLUS what the chunks being read have read by now
- * at the rate the copy measured (`progress.rowsReading`, held under each chunk's expected rows, so a commit moves it
+ * at the rate the copy measured (`progress.rowsReading`, held under each chunk's expected rows, so a commit that holds them moves it
  * forward), and the text says what is happening: the chunks reading and for how long, the rate, and the time left at
  * it — never from the row estimate alone. Before anything is measured it says the first chunk is being read, never
  * `0 of`. The share is of the heap's PAGES read (`progress.share`: the ranges are exact), and only without the chunks'
@@ -35,7 +37,7 @@ export function copyingText(copied, rowsEstimate, p) {
     if (p.rowsPerSecond === null) {
         // nothing measured this attempt: its first chunks are being read (a copy resumed has rows from before)
         const first = p.reading === 0 ? "about to read the first chunk" : `reading the first ${p.reading === 1 ? "chunk" : chunks(p.reading)}${since}`;
-        return { fraction, text: copied === 0 ? `${first}${estimate === null ? "" : ` · ~${n(estimate)} rows to copy`}` : `${rowsText(copied)} · resumed, ${first}` };
+        return { fraction, text: copied === 0 ? `${first}${estimate === null ? "" : ` · ~${n(estimate)} rows to sync`}` : `${rowsText(copied)} · resumed, ${first}` };
     }
     const parts = [rowsText(shown)];
     const allIn = p.reading === 0 && p.chunksDone >= p.chunksTotal;
@@ -51,7 +53,39 @@ export function copyingText(copied, rowsEstimate, p) {
 /** A copy's progress on one line, as `mason wait` lists what it waits for: `public.orders: copying 12% · …` (`copyingText`). */
 export function copyProgress(source, copied, rowsEstimate, p) {
     const c = copyingText(copied, rowsEstimate, p);
-    return `${source}: ${c.fraction !== null ? `copying ${Math.floor(c.fraction * 100)}% · ` : /^\d/.test(c.text) ? "copying " : ""}${c.text}`;
+    return `${source}: ${c.fraction !== null ? `syncing ${Math.floor(c.fraction * 100)}% · ` : /^\d/.test(c.text) ? "syncing " : ""}${c.text}`;
+}
+export function syncStateOf(c) {
+    if (c === undefined || c.phase === "waiting")
+        return "waiting";
+    if (c.phase === "failed" || c.error !== null)
+        return "failed";
+    if (c.phase === "copying" || c.rebuilding !== undefined || c.behind !== undefined)
+        return "syncing";
+    return "synced";
+}
+export function tableSync(c, now) {
+    const s = c?.synced;
+    return { state: syncStateOf(c), syncedAt: s?.at ?? null, syncSeconds: s?.seconds ?? null, syncedBy: s?.by ?? null,
+        ageSeconds: s === undefined ? null : Math.max(0, Math.round((now - Date.parse(s.at)) / 100) / 10) };
+}
+export function syncTotals(added, copies) {
+    const copied = copies.filter((c) => c.phase === "copied");
+    const latest = copies.flatMap((c) => c.synced === undefined ? [] : [c.synced.at]).sort().pop() ?? null;
+    return { added, copied: copied.length, failed: copies.filter((c) => syncStateOf(c) === "failed").length, rows: copied.reduce((n, c) => n + (c.rows ?? 0), 0), syncedAt: latest };
+}
+export function phaseCounts(copies) {
+    const counts = { total: 0, copied: 0, copying: 0, waiting: 0, failed: 0 };
+    for (const c of copies) {
+        counts.total++;
+        counts[c.phase]++;
+    }
+    return counts;
+}
+/** WHERE A RUN IS IN ONE WORD, as `mason status` heads its last line and the web page's Status says it: every added
+ *  table copied and served, a failure, or still under way. */
+export function readinessWord(r) {
+    return r.ready ? "Ready" : r.failed.length ? "Failed" : "Under way";
 }
 /**
  * WHERE A RUN IS. Ready when every added table's copy has ended well: `mason add` followed by `mason wait` returns
@@ -70,7 +104,7 @@ export function readiness(s) {
             continue;
         }
         if (!t.copy)
-            waiting.push(`${t.table}: waiting for its copy to start`);
+            waiting.push(`${t.table}: waiting for its first sync to start`);
     }
     return { ready: failed.length === 0 && waiting.length === 0, failed, waiting };
 }

package/dist/src/cli/registry.js

@@ -3,18 +3,23 @@
  * command's summary, in this order — so a command cannot exist without being listed, and tests/cli-help.test.ts holds
  * each one to src/cli/command.ts's rules (its own --help, an example, every option documented).
  */
-import { failed, parseCommand, reportText } from "./command.js";
+import { failed, parseCommand, reportText, wantsJson } from "./command.js";
+import { removedStartFlags } from "../lib/table-sync.js";
+import { sourcesTop } from "./sources.js";
 import { dev } from "./dev.js";
 import { devInBackground } from "./background.js";
 import { ADD, LOGS, REMOVE, STATUS, STOP, TABLES, WAIT, add, logs, remove, status, stop, tables, wait } from "./commands.js";
 import { USER, user } from "./user.js";
 import { MCP, mcp } from "./mcp.js";
+import { SHARE, share } from "./share.js";
 import { UI, ui } from "./ui.js";
 import { GUIDES, guideText } from "./guides.js";
 import { DOCTOR, NODE_MIN, doctor } from "./doctor.js";
 import { DESTROY, destroy } from "./machine.js";
 import { INIT, init } from "./init.js";
 import { SYNC, sync } from "./sync.js";
+import { USAGE, usage } from "./usage.js";
+import { CANCEL, cancel } from "./cancel.js";
 import { SERVE, serve } from "./serve.js";
 import { PROJECT_LINE } from "./dev.js";
 import { version } from "./version.js";
@@ -27,21 +32,31 @@ export const DEV = {
     needs: "project",
     name: "start",
     summary: "start Mason for this folder's project, in the background (mason init makes the project)",
-    usage: `usage: mason start [--attach] [--replication [--publication <name>] | --poll] [--self-signed-tls] [--port <n>] [--json]
+    usage: `usage: mason start [--attach] [--self-signed-tls] [--port <n>] [--json]
 
-  Starts Mason for the project of this folder (mason init made it): one process, which copies the tables you add
-  (mason add) from the project's database into its own file, keeps them current, and answers the Postgres protocol
-  for BI tools and your app. It only reads the database (SELECT): no wal_level, replication slot or publication is
-  needed or made. It returns once Mason is up; run it again any time (it says so when Mason is already running). The
-  copy and Mason's state stay between runs: the next start resumes.
+  Starts Mason for the project of this folder (mason init made it): one process, which syncs the tables you add
+  (mason add) from the project's database into its own file, keeps them current as the sources file says, and answers
+  the Postgres protocol for BI tools and your app. It only reads the database (SELECT, and a table's change log when
+  its sync: says replication). It returns once Mason is up; run it again any time (it says so when Mason is
+  already running). The synced data and Mason's state stay between runs: the next start resumes.
 
-  With --replication it reads the database's change log instead: it needs wal_level = logical and a user that may
-  replicate, and makes its own publication and replication slot on the database (mason destroy, or mason start --poll,
-  drops them). The project keeps the mode until --poll; a switch keeps the copies and catches each table up by one
-  poll. --publication <name> (else PG_PUBLICATION) names a publication that is the database owner's: it is read as it
-  is, verified to carry every added table and column, and never created, altered or dropped — Mason makes only its
-  slot. A read replica needs one (it takes no CREATE PUBLICATION). The name is kept with the project, so the next
-  mason start --replication reads it again.
+  After its first sync, each table is kept current as the sources file's sync: says — at the top for every table, or
+  on a table's entry: off (the default, which mason init writes) reads it again only when you run mason sync <table>;
+  poll <interval> (poll 5s, poll 5m, poll 1h) polls it with SELECTs at that interval; replication reads its changes
+  from the database's change log, as they are made. Each poll scans its table whole
+  on your database, and the next waits at least four times as long as that poll took, so the polls never take more
+  than a fifth of your database's time. The start says the file's default once; mason status says how each table is
+  kept current and when it was last synced. A table whose sync: changed keeps its synced data and is caught up by one poll.
+
+  A table under sync: replication needs wal_level = logical, a user that may replicate, and a primary key (a key:
+  table is polled): Mason makes one replication slot for the project and its own publication, carrying the replicated
+  tables alone, and drops them, verified gone, when no table's sync is replication any more (and at mason destroy).
+  publication: <name> at the top of the sources file (\${PG_PUBLICATION} reads it from .env) names a publication that
+  is the database owner's: it is read as it is, verified to carry every replicated table and column, and never
+  created, altered or dropped — Mason makes only its slot. A read replica needs one (it takes no CREATE PUBLICATION).
+
+  --replication, --poll and --publication are gone: each answers with the line to write at the top of the sources
+  file (sync: replication, sync: poll 5m, publication: <name>) and exit 2, and starts nothing.
 
   The Postgres API's port is the project's: the first start takes 5433, or the next port free on every address when a
   second Postgres holds it, and records it; every later start listens on the same port, so a BI tool's saved connection
@@ -58,15 +73,9 @@ export const DEV = {
 
     mason start
     mason start --attach      in the foreground: Ctrl-C stops it
-    mason start --replication read the change log, as production does
-    mason start --replication --publication app_pub   through the database owner's publication
     MASON_PG_HOST=0.0.0.0 mason start --self-signed-tls   the Postgres API for other machines, over TLS
 
   --attach            stay in the foreground (Ctrl-C stops Mason)
-  --replication       read the database's changes from its change log (logical replication), as production does
-  --publication <name>  with --replication: the publication to read, the owner's, never altered (PG_PUBLICATION;
-                      default: Mason's own, mason_dev_<project>_<source>)
-  --poll              read them with SELECTs (the default; takes back --replication)
   --self-signed-tls   the Postgres API requires TLS, from a certificate made for this project in .mason/ (kept and
                       served again by every later start with the flag); not with MASON_PG_TLS_CERT / _KEY
   --port <n>          the port the mason commands reach it on (default 4039, or the next free one)
@@ -74,22 +83,22 @@ export const DEV = {
 `,
     options: {
         port: { type: "string" }, attach: { type: "boolean", default: false }, json: { type: "boolean", default: false },
-        replication: { type: "boolean", default: false }, poll: { type: "boolean", default: false }, publication: { type: "string" },
         "self-signed-tls": { type: "boolean", default: false },
     },
     json: ["running", "pid", "postgres", "next"],
 };
 async function runDev(argv) {
+    // --replication, --poll and --publication are gone (issue 33): each answered with the edit to make in the sources
+    // file, exit 2, before the options are parsed (it would be an unknown option there) and before anything starts. The
+    // file is read only when one is given. A decision: `mason start --replication --help` answers the refusal, not the
+    // usage — the flag is wrong whatever else the line asks
+    const removed = removedStartFlags(argv, () => startSourcesTop(process.cwd()));
+    if (removed !== null)
+        return failed("start", { code: "usage", ...removed, next: [["mason start", "each table kept current as its sync: says"], ["mason help production", "sync: and publication:, and what each needs"]] }, { json: wantsJson(argv, DEV) });
     const f = parseCommand(DEV, argv);
     if (typeof f === "number")
         return f;
     const v = f.values;
-    if (v.replication && v.poll)
-        return failed("start", { message: "--replication or --poll, not both", code: "usage", usage: DEV.usage }, { json: v.json });
-    if (v.publication !== undefined && v.poll)
-        return failed("start", { message: "--publication goes with --replication, not --poll", code: "usage", usage: DEV.usage }, { json: v.json });
-    if (v.publication !== undefined && !/^\S+$/.test(v.publication))
-        return failed("start", { message: `--publication must name a publication, not ${JSON.stringify(v.publication)}`, code: "usage", usage: DEV.usage }, { json: v.json });
     if (f.positionals.length) {
         // the database is the project's now: a URL here is the old habit, answered with the new way
         return failed("start", { message: "it takes no database URL: the project has one", code: "usage", why: "mason init <url> made it; .mason/config.json holds it", usage: DEV.usage }, { json: v.json });
@@ -98,8 +107,14 @@ async function runDev(argv) {
     if (!Number.isInteger(port) || port < 1 || port > 65_535)
         return failed("start", { message: `--port must be a port number (1-65535), not ${JSON.stringify(v.port)}`, code: "usage" }, { json: v.json });
     if (!v.attach)
-        return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"], changes: v.replication ? "replication" : v.poll ? "poll" : null });
-    return dev({ port, version: version(), changes: v.replication ? "replication" : v.poll ? "poll" : null, publication: v.publication ?? null, selfSignedTls: v["self-signed-tls"] });
+        return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"] });
+    return dev({ port, version: version(), selfSignedTls: v["self-signed-tls"] });
+}
+/** The project's sources file as a person names it (`mason/sources/app.yml`), for a removed flag's answer: the one file
+ *  of the project of this folder, else the name every project's has. */
+function startSourcesTop(cwd) {
+    const t = theProject(cwd);
+    return "problem" in t ? { shown: "mason/sources/<name>.yml", sync: null, publication: null } : sourcesTop(t.project.root, t.project.folder);
 }
 export const HELP = {
     name: "help",
@@ -152,8 +167,8 @@ export const STEPS = [
     ["Learn", [{ ...HELP, run: runHelp }]],
     ["Set up", [{ ...DOCTOR, run: (argv) => doctor(argv) }, { ...INIT, run: (argv) => init(argv) }, { ...DEV, run: runDev }]],
     ["Add your tables", [{ ...TABLES, run: tables }, { ...ADD, run: add }, { ...REMOVE, run: remove }, { ...WAIT, run: wait }]],
-    ["Connect", [{ ...USER, run: user }, { ...MCP, run: mcp }]],
-    ["Run", [{ ...STATUS, run: status }, { ...UI, run: ui }, { ...SYNC, run: sync }, { ...LOGS, run: logs }, { ...STOP, run: stop }, { ...DESTROY, run: (argv) => destroy(argv) }]],
+    ["Connect", [{ ...USER, run: user }, { ...MCP, run: mcp }, { ...SHARE, run: share }]],
+    ["Run", [{ ...STATUS, run: status }, { ...UI, run: ui }, { ...SYNC, run: sync }, { ...LOGS, run: logs }, { ...CANCEL, run: cancel }, { ...USAGE, run: (argv) => usage(argv) }, { ...STOP, run: stop }, { ...DESTROY, run: (argv) => destroy(argv) }]],
     ["Go to production", [{ ...SERVE, run: serve }]],
 ];
 /** Every command, in the order `mason --help` lists them. */
@@ -164,6 +179,9 @@ export const COMMANDS = STEPS.flatMap(([, commands]) => commands);
  * it, then the next command for that moment — and mason help, every command. `mason help` and `mason --help` are the
  * whole list (topUsage).
  */
+/** WHAT MASON IS, in one line: the first `mason` alone and `mason --help` print, in the words its reader was told it
+ *  in ("a drop-in read replica for analytics"). */
+export const TAGLINE = "Mason: a drop-in read replica of your Postgres, for analytics — the tables you add, synced, kept current and served to psql, BI tools and your app.";
 export async function orientation(cwd, s = styleOut()) {
     const t = theProject(cwd);
     const project = "project" in t ? t.project : null;
@@ -172,12 +190,12 @@ export async function orientation(cwd, s = styleOut()) {
         ? [["Project", `${project.config.name}, files in ${project.folder}`], ["Mason", run ? `running (pid ${run.pid})` : "not running"]]
         : [["Project", "none here: mason init makes this folder one"]];
     const next = !project
-        ? [["mason init", "make this folder a project (DATABASE_URL from .env, or mason init postgres://…)"],
+        ? [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"],
             ["mason init demo", "or try it on a demo database Mason makes itself: nothing to install"],
             ["mason doctor", "what this machine needs for Mason, and whether it has it"]]
         : !run ? [["mason start", "start Mason for this project, in the background"], ["mason status", "the project and its tables"]]
             : [["mason status", "what Mason is doing: its tables, and the last day's slow and refused statements"], ["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"]];
-    return `${reportText({ headline: "Mason: your Postgres tables, copied and served to BI tools and your app.", details: rows,
+    return `${reportText({ headline: TAGLINE, details: rows,
         next: [...next, ["mason help", "every command, and the guides"]] }, s)}\n`;
 }
 /** `mason --help`: what Mason is, every command with its summary, and where each one's help is. On a terminal the steps are
@@ -204,8 +222,9 @@ export function topUsage(s = styleOut()) {
     return [
         `${s.bold("usage:")} mason <command> [options]`,
         "",
-        para("Mason: your Postgres tables, copied and served to BI tools and your app. Make your app's folder a project (mason init), " +
+        para(`${TAGLINE} Make your app's folder a project (mason init), ` +
             `add tables (mason add, before or after the start), start Mason (mason start), connect a tool (mason user add). It needs Node ${NODE_MIN} or later; mason doctor checks.`),
+        para("Try it first with nothing to install: mason init demo, then mason start and mason ui (a demo shop database, hosted by Mason itself)."),
         para(PROJECT_LINE),
         "",
         listed.map(([step, es]) => `  ${s.bold(step)}\n${block(es)}`).join("\n\n"),

package/dist/src/cli/replication-checks.js

@@ -64,6 +64,8 @@ export function suggestedWalCapGb(bytesPerSecond) {
         return null;
     return Math.max(4, Math.ceil((bytesPerSecond * 86_400) / 1024 ** 3));
 }
+/** What Mason does about a lost slot (src/duck/sync.ts `prepareReplication`), one wording for every check that says it. */
+const SLOT_REMADE = "Mason makes a new slot and catches each table up with one poll (a scan of each table on your database), never a full sync";
 /** What wal_level = logical takes on this server: its provider's way, or postgresql.conf's. */
 function walLevelFix(f) {
     if (f.rds)
@@ -77,12 +79,12 @@ export function replicationChecks(f, slot, slotState) {
     const out = [];
     out.push(f.walLevel === "logical"
         ? { name: "wal_level", ok: true, detail: "logical" }
-        : { name: "wal_level", ok: false, detail: `${f.walLevel}: logical replication needs logical. To fix: ${walLevelFix(f)}. Or read changes by polling instead (--poll: SELECT alone, for a small database)` });
+        : { name: "wal_level", ok: false, detail: `${f.walLevel}: logical replication needs logical. To fix: ${walLevelFix(f)}. Or poll the table instead: give its entry sync: poll <interval> in the sources file (SELECTs alone, no change log)` });
     if (f.standby) {
         out.push(f.version >= 160000
             ? { name: "standby", ok: true, warn: !f.hotStandbyFeedback,
-                detail: `a read replica (Postgres 16+ decodes on a standby)${f.hotStandbyFeedback ? "" : ". hot_standby_feedback is off: the primary may remove catalog rows the slot still needs, which invalidates it (Mason then rebuilds from scratch) — turn it on"}` }
-            : { name: "standby", ok: false, detail: `a read replica on Postgres ${f.versionText}: logical decoding on a standby needs Postgres 16. Point Mason at the primary, upgrade the replica, or poll it (--poll)` });
+                detail: `a read replica (Postgres 16+ decodes on a standby)${f.hotStandbyFeedback ? "" : `. hot_standby_feedback is off: the primary may remove catalog rows the slot still needs, which invalidates it (${SLOT_REMADE}) — turn it on`}` }
+            : { name: "standby", ok: false, detail: `a read replica on Postgres ${f.versionText}: logical decoding on a standby needs Postgres 16. Point Mason at the primary, upgrade the replica, or poll the table: give its entry sync: poll <interval> in the sources file` });
     }
     const canReplicate = f.superuser || f.replication || f.rds?.member === true;
     out.push(canReplicate
@@ -92,7 +94,7 @@ export function replicationChecks(f, slot, slotState) {
     const free = f.maxSlots - f.slotsUsed;
     if (slotState) {
         out.push(slotState.walStatus === "lost"
-            ? { name: "slot", ok: true, warn: true, detail: `${slot} exists and Postgres invalidated it (wal_status lost): Mason drops it and rebuilds from scratch at its start` }
+            ? { name: "slot", ok: true, warn: true, detail: `${slot} exists and Postgres invalidated it (wal_status lost): ${SLOT_REMADE}` }
             : slotState.active
                 ? { name: "slot", ok: false, detail: `${slot} is in use by another reader${slotState.activePid !== null ? ` (pid ${slotState.activePid} on the database)` : ""}: one slot has one reader. ` +
                         `Stop the other Mason for this project (mason stop). A run that crashed holds it until its connection ends${slotState.activePid !== null ? `: SELECT pg_terminate_backend(${slotState.activePid}) ends it now` : ""}` }
@@ -110,7 +112,7 @@ export function replicationChecks(f, slot, slotState) {
     const size = gb === null ? "a day of this database's WAL" : `${gb}GB`;
     const basis = gb === null ? "" : ` (a day of the WAL this server writes: ${bytesText(f.walBytesPerSecond)}/s since its statistics were reset)`;
     out.push(f.slotWalKeepMb >= 0
-        ? { name: "WAL cap", ok: true, detail: `max_slot_wal_keep_size = ${f.slotWalKeepMb >= 1024 ? `${(f.slotWalKeepMb / 1024).toFixed(f.slotWalKeepMb % 1024 ? 1 : 0)}GB` : `${f.slotWalKeepMb}MB`}: past it Postgres drops the slot rather than fill its disk, and Mason rebuilds from scratch${gb !== null && f.slotWalKeepMb < gb * 1024 ? `. A day of this server's WAL is about ${gb}GB${basis}: an outage longer than the cap's worth means a rebuild` : ""}` }
+        ? { name: "WAL cap", ok: true, detail: `max_slot_wal_keep_size = ${f.slotWalKeepMb >= 1024 ? `${(f.slotWalKeepMb / 1024).toFixed(f.slotWalKeepMb % 1024 ? 1 : 0)}GB` : `${f.slotWalKeepMb}MB`}: past it Postgres invalidates the slot rather than fill its disk, and ${SLOT_REMADE}${gb !== null && f.slotWalKeepMb < gb * 1024 ? `. A day of this server's WAL is about ${gb}GB${basis}: an outage longer than the cap's worth means that catch-up` : ""}` }
         : { name: "WAL cap", ok: false,
             detail: `max_slot_wal_keep_size is unlimited: while Mason is stopped its slot holds every byte of WAL, until the disk fills and Postgres stops taking writes. Cap it at the outage you want Mason to survive, e.g. ${size}${basis}` +
                 (f.rds || f.cloudSql ? ` — in the ${f.rds ? "DB parameter group" : "database flags"} (max_slot_wal_keep_size, in MB)` : ""),