@mason-data/cli 0.6.2 → 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

@@ -25,7 +25,9 @@ export function maskedUrl(url) {
         return u.toString();
     }
     catch {
-        return url.replace(/:\/\/([^:@/]*):[^@/]*@/, "://$1:****@");
+        // not a URL: everything from the user's colon to the LAST @ is the password, whatever it holds (a / or an @ that
+        // was not encoded) — a host never holds an @
+        return url.replace(/:\/\/([^:@/]*):.*@/, "://$1:****@");
     }
 }
 /**
@@ -38,7 +40,8 @@ export function parseSource(url) {
         u = new URL(url);
     }
     catch {
-        return { problem: `${JSON.stringify(url)} is not a URL. The form is postgres://user:password@localhost:5432/your_app — a password ` +
+        // its password masked: the problem is printed (and, under mason mcp, kept in the MCP client's log)
+        return { problem: `${JSON.stringify(maskedUrl(url))} is not a URL. The form is postgres://user:password@localhost:5432/your_app — a password ` +
                 `containing @ : / # ? or % must be URL-encoded (encodeURIComponent; @ is %40).` };
     }
     if (u.protocol !== "postgres:" && u.protocol !== "postgresql:")
@@ -62,7 +65,7 @@ export function parseSource(url) {
     }
 }
 /** What a failed connection means, and what to change. */
-export function explainConnectError(e, s) {
+export function explainConnectError(e, s, o = {}) {
     const where = `${s.host}:${s.port}`;
     const msg = e?.message ?? String(e);
     if (e instanceof PgError) {
@@ -82,6 +85,9 @@ export function explainConnectError(e, s) {
         return { message: `${where}: ${msg}`, hints: [] };
     }
     if (/ECONNREFUSED/.test(msg)) {
+        // the demo database is served by the project's own run: nothing else could be listening there
+        if (o.demo)
+            return { message: `the demo database is not running on ${where}`, hints: ["the demo database runs inside mason start: start it first"] };
         return {
             message: `nothing is listening on ${where}`,
             hints: [
@@ -106,13 +112,13 @@ export function explainConnectError(e, s) {
     return { message: `${where}: ${msg}`, hints: [] };
 }
 /** Connect as the service will. The failure is explained; for a missing database, the ones that exist are listed. */
-export async function connectSource(s) {
+export async function connectSource(s, o = {}) {
     const opts = { host: s.host, port: s.port, database: s.database, user: s.user, password: s.password, sslmode: s.sslmode, connectTimeoutMs: 10_000, applicationName: "mason-dev" };
     try {
         return { pg: await PgConnection.connect(opts) };
     }
     catch (e) {
-        const failure = explainConnectError(e, s);
+        const failure = explainConnectError(e, s, o);
         if (e instanceof PgError && e.code === "3D000") {
             try {
                 const pg = await PgConnection.connect({ ...opts, database: "postgres" });
@@ -143,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'
@@ -156,17 +162,20 @@ export const TABLES_SQL = `SELECT json_agg(t ORDER BY t.schema, t.table)::text F
       THEN (SELECT coalesce(sum(pg_total_relation_size(pt.relid)), 0) FROM pg_partition_tree(c.oid) pt WHERE pt.isleaf)
       ELSE pg_total_relation_size(c.oid) END AS bytes,
     obj_description(c.oid, 'pg_class') AS comment,
+    -- the primary key: only a valid index enforces it
     (SELECT coalesce(json_agg(a.attname ORDER BY k.n), '[]'::json)
       FROM pg_index i CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, n)
       JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
-      WHERE i.indrelid = c.oid AND i.indisprimary) AS key,
+      WHERE i.indrelid = c.oid AND i.indisprimary AND i.indisvalid) AS key,
     (SELECT coalesce(json_agg(json_build_object('name', ic.relname, 'constraint', EXISTS (SELECT FROM pg_constraint u WHERE u.conindid = i.indexrelid AND u.contype = 'u'),
         -- indnullsnotdistinct is Postgres 15's: read through the row, which an older server's lacks
         'nulls_not_distinct', coalesce((to_jsonb(i) ->> 'indnullsnotdistinct')::boolean, false),
         'columns', (SELECT json_agg(a.attname ORDER BY k.n) FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, n)
           JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum)) ORDER BY ic.relname), '[]'::json)
       FROM pg_index i JOIN pg_class ic ON ic.oid = i.indexrelid
-      WHERE i.indrelid = c.oid AND i.indisunique AND NOT i.indisprimary AND i.indpred IS NULL AND i.indexprs IS NULL
+      -- an INVALID index (a CREATE UNIQUE INDEX CONCURRENTLY that failed, its duplicates still in the table) enforces
+      -- nothing: never declared to the catalog, never a key: Mason accepts
+      WHERE i.indrelid = c.oid AND i.indisunique AND i.indisvalid AND NOT i.indisprimary AND i.indpred IS NULL AND i.indexprs IS NULL
         AND i.indnkeyatts = i.indnatts) AS unique_keys,
     (SELECT coalesce(json_agg(json_build_object('name', a.attname, 'type', format_type(a.atttypid, a.atttypmod),
         'not_null', a.attnotnull, 'comment', col_description(c.oid, a.attnum), 'type_oid', a.atttypid,
@@ -212,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
@@ -252,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. */
@@ -271,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
@@ -282,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,14 +18,18 @@
 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";
+/** The demo database's folder in the project's `.mason/` (`mason init demo`): hosted by mason start, deleted by mason destroy. */
+export const DEMO_DIR = "demo";
 /** A name from a folder's: lower case, the rest of it dashes. */
 export function nameFromFolder(dir) {
     const n = path.basename(path.resolve(dir)).toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^[-_]+|[-_]+$/g, "").slice(0, 48);
@@ -97,8 +101,8 @@ export function writeConfig(dir, c) {
     fs.chmodSync(file, 0o600);
 }
 /** A new project's config: the secrets made here, once. */
-export function newConfig(name, folder, remote) {
-    return { name, folder, remote, apiKey: randomBytes(24).toString("hex"), sourceServer: null, running: null, lastRun: null };
+export function newConfig(name, folder, remote, o = {}) {
+    return { name, folder, remote, ...(o.demo ? { demo: true } : {}), apiKey: randomBytes(24).toString("hex"), sourceServer: null, running: null, lastRun: null };
 }
 /**
  * THE PROJECT A COMMAND MEANS: the nearest at or above `cwd`; or the sentence that says why there is none, with the
@@ -110,8 +114,8 @@ export function theProject(cwd) {
         return brokenProblem(p);
     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",
-        next: [["mason init", "make this folder a project (DATABASE_URL from .env, or mason init postgres://…)"]] };
+    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 (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"]] };
 }
 /** Whether `root`'s .gitignore already ignores `.mason/`. */
 export function ignoresStateDir(gitignore) {
@@ -125,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 };
 }