@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/preflight.js

@@ -10,49 +10,103 @@
  */
 import * as os from "node:os";
 import { PgConnection, PgError } from "../cdc/pg-wire.js";
-import { parseDatabaseUrl } from "../lib/database-url.js";
+import { parseDatabaseUrl, queryProblem } from "../lib/database-url.js";
 /** A host on this machine: polling it costs nothing that leaves the machine. */
 export function isLocalHost(host) {
     const h = host.toLowerCase();
     return h === "localhost" || h === "::1" || h === "0.0.0.0" || /^127\./.test(h) || h === "host.docker.internal" || h.endsWith(".localhost");
 }
-/** The URL with its password masked: what is printed and shown, never the secret. */
-export function maskedUrl(url) {
+/**
+ * THE ONE WAY A VALUE OF THE SOURCE'S URL SETTING IS SHOWN (issue 541), wherever Mason prints, logs or answers it: the URL
+ * with its password replaced by `****`, or null — never shown. It fails closed, so a secret masked by recognising its
+ * shape cannot leak in another shape: shown only when the value parses WHOLE as a postgres:// URL with a host, nothing
+ * dropped or rewritten by the parse (no space or control character inside it, which a parse strips or encodes; one at
+ * either end, a secret file's last newline, is trimmed as the parse trims it), no `#` at all and no `@` after the host
+ * (a password holding `/`, `?` or `#` unencoded splits the authority there, and its tail would be shown as a path, a
+ * parameter or a fragment), and a query the URL is read by whole (src/lib/database-url.ts queryProblem: only the
+ * parameters read, each once, each value one the reading accepts — libpq takes any connection keyword there,
+ * `?password=…` included, and a value can hold one, `sslmode=prefer%26password=…`), so no part shown is one not read;
+ * the query shown is the one read, written out again. A keyword/value string, a bare password, any other URL: null.
+ */
+export function shownUrl(value) {
+    const v = value.trim();
+    if (/[\s\x00-\x1f\x7f#]/.test(v))
+        return null;
+    let u;
     try {
-        const u = new URL(url);
-        if (u.password)
-            u.password = "****";
-        return u.toString();
+        u = new URL(v);
     }
     catch {
-        // 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:****@");
+        return null;
     }
+    if (u.protocol !== "postgres:" && u.protocol !== "postgresql:")
+        return null;
+    if (!u.hostname || /@/.test(u.pathname + u.search))
+        return null;
+    if (queryProblem(u.searchParams) !== null)
+        return null;
+    u.search = u.searchParams.toString();
+    if (u.password)
+        u.password = "****";
+    return u.toString();
 }
-/**
- * Parse the URL `mason start` was given. The user defaults to the OS user (libpq's default, and Homebrew's and
- * Postgres.app's superuser); the database never defaults — guessing it would read the wrong one.
- */
-export function parseSource(url) {
+/** A value of the source's URL setting in a sentence: `shownUrl`'s, or words that say it is not shown, never the value. */
+export function maskedUrl(value) {
+    return shownUrl(value) ?? "a value that is not a postgres:// URL (not shown)";
+}
+const URL_FORM = "postgres://user:password@host:5432/your_app";
+/** The schemes a wrong URL is named by: Mason's own list, so a scheme said is never a part of the value Mason did not know. */
+const KNOWN_SCHEMES = new Set(["mysql", "mariadb", "mssql", "sqlserver", "oracle", "mongodb", "mongodb+srv", "redis", "rediss", "sqlite", "clickhouse",
+    "http", "https", "file", "pg", "pgsql", "psql", "postgis", "postgre", "postgress", "postgresq"]);
+const ENCODE = "a password holding @ : / # ? % or a space is URL-encoded (encodeURIComponent; @ is %40, / is %2F, # is %23)";
+/** What is wrong with the query of a postgres:// URL that reads whole but for it (queryProblem's words), else null. */
+function queryOf(t) {
+    if (!/^postgres(ql)?:\/\//i.test(t) || /[\s\x00-\x1f\x7f#]/.test(t))
+        return null;
     let u;
     try {
-        u = new URL(url);
+        u = new URL(t);
     }
     catch {
-        // 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).` };
+        return null;
     }
-    if (u.protocol !== "postgres:" && u.protocol !== "postgresql:")
-        return { problem: `the URL's scheme is ${u.protocol.replace(/:$/, "")}; it must be postgres:// or postgresql://` };
+    // an @ after the host is a password split there (said as such), not a parameter
+    return u.hostname === "" || /@/.test(u.pathname + u.search) ? null : queryProblem(u.searchParams);
+}
+/**
+ * Why a value `shownUrl` will not show is not a URL Mason reads, told from its SHAPE alone (`name` says where it is):
+ * what it looks like and how to write it, never a part of it, so a coding agent fixes it from the message alone.
+ */
+function notShownProblem(value, name) {
+    const t = value.trim();
+    const why = t === "" ? "it is empty"
+        : /^[A-Za-z_][A-Za-z0-9_]*\s*=/.test(t) ? "it looks like a keyword/value connection string (host=… user=… password=…)"
+            : /^jdbc:/i.test(t) ? "it looks like a JDBC URL: drop jdbc:, and give the user and password before the host"
+                : !/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(t) ? "it is not a URL"
+                    : queryOf(t) !== null ? queryOf(t)
+                        : !/^postgres(ql)?:\/\//i.test(t) ? `its scheme is ${KNOWN_SCHEMES.has(t.slice(0, t.indexOf(":")).toLowerCase()) ? `${t.slice(0, t.indexOf(":")).toLowerCase()}, not` : "not"} postgres:// or postgresql://`
+                            : "it does not read as one URL (a character that is not URL-encoded splits it: an @ : / ? # % or a space in the password, an @ or # in the database " +
+                                "or a parameter; or the port is not a number up to 65535)";
+    return `${name} is not a postgres:// URL: ${why}. Write it as ${URL_FORM}, where ${ENCODE}`;
+}
+/**
+ * Parse the URL `mason start` was given (`name` says where it is, `DATABASE_URL in .env`: a problem names it, never the
+ * value). The user defaults to the OS user (libpq's default, and Homebrew's and Postgres.app's superuser); the database
+ * never defaults — guessing it would read the wrong one. Only a value `shownUrl` shows is read, so every URL a run
+ * connects with is one its messages can show.
+ */
+export function parseSource(url, name = "the URL") {
+    if (shownUrl(url) === null)
+        return { problem: notShownProblem(url, name) };
+    const u = new URL(url.trim());
     if (!u.username)
         u.username = encodeURIComponent(os.userInfo().username);
-    if (!u.pathname.replace(/^\//, "")) {
-        return { problem: `the URL names no database. Add it after the port: postgres://${decodeURIComponent(u.username)}@${u.host || "localhost:5432"}/your_app ` +
-                `(the one your app uses — its DATABASE_URL usually says).` };
-    }
     try {
+        // inside the try: a user name with a malformed %-escape is refused (decodeURIComponent throws), never a crash
+        if (!u.pathname.replace(/^\//, "")) {
+            return { problem: `${name} names no database. Add it after the port: postgres://${decodeURIComponent(u.username)}@${u.host || "localhost:5432"}/your_app ` +
+                    `(the one your app uses — its DATABASE_URL usually says).` };
+        }
         const parts = parseDatabaseUrl(u.toString());
         const remote = !isLocalHost(parts.host);
         // a database elsewhere is read over the network: never in the clear unless the URL says so outright
@@ -61,7 +115,9 @@ export function parseSource(url) {
         return { source: { ...parts, url: u.toString(), remote } };
     }
     catch (e) {
-        return { problem: e.message.replace(/^DATABASE_URL/, "the URL") };
+        if (e instanceof URIError)
+            return { problem: `${name} holds a % that starts no %-escape: a % in the user or the password is written %25. Write it as ${URL_FORM}, where ${ENCODE}` };
+        return { problem: e.message.replace(/^DATABASE_URL/, name) };
     }
 }
 /** What a failed connection means, and what to change. */
@@ -80,8 +136,9 @@ export function explainConnectError(e, s, o = {}) {
                 ],
             };
         }
+        // the database is not repeated (issue 541: a refusal echoes no part of the value); the hint lists the ones there are
         if (e.code === "3D000")
-            return { message: `${where} has no database ${JSON.stringify(s.database)}`, hints: [] };
+            return { message: `${where} has no database by the name the URL gives (the part after the port)`, hints: [] };
         return { message: `${where}: ${msg}`, hints: [] };
     }
     if (/ECONNREFUSED/.test(msg)) {
@@ -138,6 +195,18 @@ export async function connectSource(s, o = {}) {
         return { failure };
     }
 }
+/** pg_collation_actual_version (a libc collation's glibc now) exists from this server_version_num */
+const COLLATION_ACTUAL_NUM = 130000;
+/** The database's collations of its encoding, each as src/duck/collation.ts reads it. The locale's column differs by
+ *  version (colllocale from 17, colliculocale 15–16, none before: collcollate holds ICU's), so the row is read whole. */
+export async function readCollations(pg, versionNum) {
+    const version = versionNum >= COLLATION_ACTUAL_NUM ? "CASE WHEN c.collprovider = 'c' THEN pg_collation_actual_version(c.oid) END" : "NULL::text";
+    const rows = JSON.parse((await pg.query(`SELECT coalesce(json_agg(to_jsonb(c) || jsonb_build_object('schema', n.nspname, 'actual', ${version}) ORDER BY c.oid), '[]')::text ` +
+        "FROM pg_collation c JOIN pg_namespace n ON n.oid = c.collnamespace WHERE c.collencoding IN (-1, pg_char_to_encoding(getdatabaseencoding()))")).rows[0]?.[0] ?? "[]");
+    return rows.map((r) => ({ schema: String(r.schema), name: String(r.collname), provider: String(r.collprovider ?? "c"), collate: (r.collcollate ?? null), ctype: (r.collctype ?? null),
+        locale: (r.colllocale ?? r.colliculocale ?? (r.collprovider === "i" ? r.collcollate : null) ?? null), deterministic: r.collisdeterministic !== false,
+        version: (r.actual ?? r.collversion ?? null) }));
+}
 /** The source's plain views (never a materialized one: that is a table of its own), each definition printed under a
  *  search_path of pg_catalog alone, which qualifies every table, type and function a view reads (`public.orders`):
  *  `SET LOCAL` holds for the rest of this one Query and ends with it, whatever happens */
@@ -149,7 +218,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'
@@ -177,13 +246,21 @@ export const TABLES_SQL = `SELECT json_agg(t ORDER BY t.schema, t.table)::text F
       -- 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,
-        'type_array_oid', (SELECT typarray FROM pg_type WHERE oid = a.atttypid),
+    (SELECT coalesce(json_agg(json_build_object('name', a.attname, 'type', format_type(b.oid, b.mod), 'domain', b.oid <> a.atttypid,
+        'not_null', a.attnotnull, 'comment', col_description(c.oid, a.attnum), 'type_oid', b.oid,
+        'type_array_oid', (SELECT typarray FROM pg_type WHERE oid = b.oid),
+        'type_kind', (SELECT coalesce(e.typtype, t.typtype) FROM pg_type t LEFT JOIN pg_type e ON e.typarray = t.oid WHERE t.oid = b.oid),
         'default', pg_get_expr(d.adbin, d.adrelid), 'identity', a.attidentity, 'generated', a.attgenerated,
+        -- the column's own collation, where it is not its (base) type's: the catalog declares it (src/duck/collation.ts)
+        'collation', (SELECT json_build_object('schema', cn.nspname, 'name', co.collname) FROM pg_collation co JOIN pg_namespace cn ON cn.oid = co.collnamespace
+          WHERE co.oid = a.attcollation AND a.attcollation <> 0 AND a.attcollation <> (SELECT typcollation FROM pg_type WHERE oid = b.oid)),
         -- the sequence a serial or identity column owns: asked only of a column with a default or an identity
         'sequence', CASE WHEN d.adbin IS NOT NULL OR a.attidentity <> '' THEN pg_get_serial_sequence(format('%I.%I', n.nspname, c.relname), a.attname) END) ORDER BY a.attnum), '[]'::json)
       FROM pg_attribute a LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+      -- a domain's column is read and declared as its base type (a domain of a domain too)
+      CROSS JOIN LATERAL (WITH RECURSIVE base(oid, mod) AS (SELECT a.atttypid, a.atttypmod UNION ALL
+          SELECT t.typbasetype, t.typtypmod FROM base JOIN pg_type t ON t.oid = base.oid WHERE t.typtype = 'd')
+        SELECT base.oid, base.mod FROM base JOIN pg_type t ON t.oid = base.oid WHERE t.typtype <> 'd') b
       WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped) AS columns,
     (SELECT coalesce(json_agg(json_build_object('column', a.attname, 'target', tn.nspname || '.' || tc.relname, 'target_column', ta.attname)), '[]'::json)
       FROM pg_constraint f
@@ -199,8 +276,18 @@ export const TABLES_SQL = `SELECT json_agg(t ORDER BY t.schema, t.table)::text F
 /** What a never-analysed table counted to, by oid: `mason start` reads the catalog every 10 s, and a table is counted
  *  once per run, never per read (review of #404: a remote one over the network each time). */
 const COUNTED = new Map();
+/** the server_version_num from which `pg_database_collation_actual_version` exists */
+const COLLATION_ACTUAL_VERSION_NUM = 150000;
+const COLLATION_ACTUAL_VERSION_SQL = "SELECT pg_database_collation_actual_version(oid) FROM pg_database WHERE datname = current_database()";
+/** The collation library's version now, else what the database recorded (`recorded`, datcollversion; before Postgres 15, none). */
+export async function collationVersion(pg, versionNum, recorded) {
+    if (versionNum < COLLATION_ACTUAL_VERSION_NUM)
+        return recorded;
+    return (await pg.query(COLLATION_ACTUAL_VERSION_SQL)).rows[0]?.[0] ?? recorded;
+}
 /** The database's facts: its version, whether it is a standby, and every table this user can read. */
-export async function readSourceFacts(pg, counted = COUNTED) {
+/** `collations: false` (the run's 10-second refresh) leaves the database's collations unread: they were read at the start */
+export async function readSourceFacts(pg, counted = COUNTED, o = {}) {
     const r = (await pg.query("SELECT current_setting('server_version_num'), current_setting('server_version'), pg_is_in_recovery()::text")).rows[0];
     const rows = JSON.parse((await pg.query(TABLES_SQL)).rows[0]?.[0] ?? "null");
     const tables = [];
@@ -213,23 +300,28 @@ export async function readSourceFacts(pg, counted = COUNTED) {
         }
         tables.push({
             source: `${t.schema}.${t.table}`, schema: t.schema, table: t.table, key: t.key, rows: count, bytes: Number(t.bytes), comment: t.comment,
-            columns: t.columns.map((c) => ({ name: c.name, type: c.type, notNull: c.not_null, comment: c.comment,
-                ...(c.type_oid >= 16384 ? { typeOid: c.type_oid, ...(c.type_array_oid > 0 ? { typeArrayOid: c.type_array_oid } : {}) } : {}),
+            columns: t.columns.map((c) => ({ name: c.name, type: c.type, typeKind: c.type_kind, ...(c.domain ? { domain: true } : {}), notNull: c.not_null, comment: c.comment,
+                // an oid is a STRING in Postgres's JSON (only the int, float and numeric types are numbers): one spelling, here
+                ...(Number(c.type_oid) >= 16384 ? { typeOid: Number(c.type_oid), ...(Number(c.type_array_oid) > 0 ? { typeArrayOid: Number(c.type_array_oid) } : {}) } : {}),
                 // a generated column's pg_attrdef row is its expression, never a default
                 ...(c.default !== null && c.generated === "" ? { default: c.default } : {}), ...(c.identity === "a" || c.identity === "d" ? { identity: c.identity } : {}),
-                ...(c.generated === "s" ? { generated: true } : {}), ...(c.sequence !== null ? { sequence: c.sequence } : {}) })),
+                ...(c.generated === "s" ? { generated: true } : {}), ...(c.sequence !== null ? { sequence: c.sequence } : {}),
+                ...(c.collation !== null && c.collation !== undefined ? { collation: c.collation } : {}) })),
             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 } : {}),
+            ...(Number(t.row_type_oid) > 0 ? { rowTypeOid: Number(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
     const db = JSON.parse((await pg.query("SELECT to_jsonb(d)::text FROM pg_database d WHERE datname = current_database()")).rows[0]?.[0] ?? "{}");
-    // datcollversion (Postgres 15+): the library's version of it (glibc's for libc), which moves when the OS's does
-    const collation = { provider: db.datlocprovider ?? "c", collate: db.datcollate ?? "C", locale: db.datlocale ?? db.daticulocale ?? null, version: db.datcollversion ?? null };
+    // the library's version of it NOW (Postgres 15+; glibc's for libc): datcollversion is what the database was created or
+    // last refreshed under, so it stays where it was through an OS upgrade, which is what must read the order again
+    const collation = { provider: db.datlocprovider ?? "c", collate: db.datcollate ?? "C", ctype: db.datctype ?? db.datcollate ?? "C", locale: db.datlocale ?? db.daticulocale ?? null, version: await collationVersion(pg, Number(r[0]), db.datcollversion ?? null) };
     const views = JSON.parse((await pg.query(VIEWS_SQL)).rows[0]?.[0] ?? "[]")
         .map((v) => ({ schema: v.schema, name: v.name, definition: v.definition, comment: v.comment }));
-    return { version: Number(r[0]), versionText: r[1] ?? "", standby: r[2] === "true", tables, systemIdentifier: await systemIdentifier(pg), collation, views };
+    const collations = o.collations === false ? undefined : await readCollations(pg, Number(r[0]));
+    return { version: Number(r[0]), versionText: r[1] ?? "", standby: r[2] === "true", tables, systemIdentifier: await systemIdentifier(pg), collation, ...(collations !== undefined ? { collations } : {}), views };
 }
 /** The server's system identifier, or null when this user may not read it (only that refusal: any other error is real). */
 export async function systemIdentifier(pg) {
@@ -261,7 +353,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 +372,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 +383,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. */
@@ -309,7 +401,7 @@ export function versionProblem(f) {
  * after the check's facts.
  */
 export async function checkSource(url, o) {
-    const parsed = parseSource(url);
+    const parsed = parseSource(url, o.name);
     if ("problem" in parsed) {
         o.say(`${o.cmd}: ${parsed.problem}`);
         return { exit: 2 };

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";
@@ -74,6 +76,53 @@ export function readProject(root) {
     }
     return { root, dir, folder: path.resolve(root, config.folder), config };
 }
+/** Why a path could not be resolved, in a person's words (the system's code beside them). */
+export function unresolvedWhy(e) {
+    const code = e.code;
+    const words = {
+        ELOOP: "a symbolic link on the way leads back to itself (a loop)",
+        ENOTDIR: "a part of the path is a file, not a folder",
+        EACCES: "a folder on the way may not be read by this user",
+        EPERM: "a folder on the way may not be read by this user",
+        ENAMETOOLONG: "the path is longer than this system takes",
+    };
+    return code !== undefined && words[code] !== undefined ? `${words[code]} (${code})` : `the system could not resolve it (${code ?? e.message})`;
+}
+/**
+ * WHERE A PROJECT'S FILES ARE, against its root (the folder `.mason/` is in): strictly `inside` it (a folder of their own,
+ * `mason/`), the `root` itself (`mason init --folder .`), or `outside` it (`..`, `../app`, an absolute path elsewhere, a
+ * link that leaves it). Read from the real paths — a folder not made yet by its nearest folder that is — so every
+ * spelling of one place is one answer. A path that cannot be resolved (a loop, a file as a folder, a folder this user
+ * may not read, a path too long) is a fourth answer, `unknown` with why, never an exception: fail closed, each caller
+ * refuses it with the way out. The one authority: `mason init` refuses outside and unknown, `mason deploy` sends only
+ * from inside (src/cli/deploy.ts: a root's or an outside folder's YAML is the application's, or anyone's).
+ */
+export function folderPlace(root, folder) {
+    const real = (p) => {
+        const rest = [];
+        for (let d = path.resolve(p);; d = path.dirname(d)) {
+            try {
+                return path.join(fs.realpathSync(d), ...rest.reverse());
+            }
+            catch (e) {
+                // a part not made yet: the nearest one that is decides (a folder mason init will make); anything else is unknown
+                if (e.code !== "ENOENT" || path.dirname(d) === d)
+                    throw e;
+                rest.push(path.basename(d));
+            }
+        }
+    };
+    let rel;
+    try {
+        rel = path.relative(real(root), real(folder));
+    }
+    catch (e) {
+        return { place: "unknown", why: unresolvedWhy(e) };
+    }
+    if (rel === "")
+        return { place: "root" };
+    return { place: rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel) ? "outside" : "inside" };
+}
 /** Whether a lookup found a project it could read. */
 export const isProject = (p) => p !== null && !("broken" in p);
 /** What a broken project's commands say: the file, what is wrong with it, and the two ways out. */
@@ -113,7 +162,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 +176,92 @@ 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;
+}
+/** The setting that says the project's files are deployed, and read-only where Mason runs (`projectWriteRefusal`). */
+export const READONLY_SETTING = "MASON_PROJECT_READONLY";
+/** MASON_PROJECT_READONLY as the environment says it: 1 true, 0 or unset false, anything else what is wrong with it. */
+export function projectReadOnlySetting(env) {
+    const v = env[READONLY_SETTING];
+    if (v === undefined || v === "" || v === "0")
+        return false;
+    if (v === "1")
+        return true;
+    return { problem: `${READONLY_SETTING}=${JSON.stringify(v)}: 1 (the project's files are deployed, and read-only here) or 0 (the default)` };
+}
+/** what a refused edit of a deployed project says to run next */
+const READONLY_NEXT = [["mason status", "what Mason syncs here, as the deployed files say"]];
+/**
+ * WHETHER THE PROJECT'S FILES MAY BE WRITTEN HERE — THE ONE AUTHORITY (issue 473): null when they may, else the refusal.
+ * A deployment that ships its committed project folder (CI, GitOps, a platform that deploys the folder) runs the files
+ * as committed: an edit on the server would run what nobody committed, and the next deploy would undo it without a word.
+ * MASON_PROJECT_READONLY=1 says so, and EVERY WRITER OF A PROJECT FILE ASKS THIS FIRST and writes nothing on a refusal:
+ * the sources file (`mason add` and `mason remove` at both entrances, the page's Add and Remove: src/cli/source-edit.ts
+ * `sourceToEdit`; `mason serve`'s first file, `serveSource`), `mason.yml` (src/cli/pin.ts `ensurePin`) and what `mason
+ * init` writes (the sources, roles and generated tables' files, `.env`, `.gitignore`). The users (`.mason/users.json`),
+ * the sync and every read are not the project's files, and are unchanged.
+ *
+ * Read from two places, either refusing: this process's environment, and THE RECORD the run makes in the project's
+ * config at its start (`projectReadOnly`, src/cli/dev.ts) — so a command beside the run (`docker compose exec mason
+ * mason add …`), with the run up or down, is refused whatever its own environment says (`MASON_PROJECT_READONLY=0
+ * mason add` does not un-say the run's). `root` is the project's (where `.mason/` is), or null where no record is to be
+ * read (`mason serve` before it writes the config: its own environment decides). Fail closed: a value that is not 0 or
+ * 1, or a config that cannot be read, cannot tell, and refuses.
+ */
+export function projectWriteRefusal(root, env) {
+    const set = projectReadOnlySetting(env);
+    if (typeof set !== "boolean") {
+        return { message: `${set.problem}, so whether the project's files may be written here cannot be told`, code: "refused",
+            why: "Mason writes none of them until it can tell", fix: `set ${READONLY_SETTING}=1 or ${READONLY_SETTING}=0, or unset it`, next: READONLY_NEXT };
+    }
+    const p = root === null ? null : readProject(root);
+    if (p !== null && "broken" in p) {
+        return { message: `whether the project's files may be written here cannot be told: ${p.file}: ${p.broken}`, code: "refused",
+            why: "the config records whether Mason runs the project read-only, and Mason writes none of its files until it can tell", fix: brokenProblem(p).fix, next: READONLY_NEXT };
+    }
+    const recorded = p?.config.projectReadOnly === true;
+    if (!set && !recorded)
+        return null;
+    return { message: `the project's files are read-only here (${READONLY_SETTING}=1${set ? "" : " when Mason last started"})`, code: "refused",
+        why: "Mason runs them as they were deployed: an edit here would run what nobody committed, and the next deploy would undo it",
+        fix: "edit the files and deploy them: mason add or mason remove where the project is committed, then commit and deploy",
+        next: READONLY_NEXT };
+}
+/**
+ * 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 readOnly = projectReadOnlySetting(env);
+    if (typeof readOnly !== "boolean")
+        return { message: readOnly.problem, code: "refused", fix: `set ${READONLY_SETTING}=1 or ${READONLY_SETTING}=0, or unset it` };
+    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,50 @@ 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, now = Date.now()) {
+    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 (behindOf(c.kept, now).behindBySeconds ?? 0) > 0 ? "behind" : "synced";
+}
+export function behindOf(k, now) {
+    if (k === undefined || k.by === "generated")
+        return { asOf: null, promisedSeconds: null, behindBySeconds: null, behindWhy: null };
+    const asOf = k.by === "recopy" ? k.syncedAt ?? k.copiedAt : k.syncedAt;
+    const promisedSeconds = k.promisedSeconds ?? null;
+    if (promisedSeconds === null || asOf === null)
+        return { asOf, promisedSeconds, behindBySeconds: null, behindWhy: null };
+    const over = (now - Date.parse(asOf)) / 1000 - promisedSeconds;
+    return over > 0 ? { asOf, promisedSeconds, behindBySeconds: Math.round(over * 10) / 10, behindWhy: k.lateWhy ?? "its next sync is late" }
+        : { asOf, promisedSeconds, behindBySeconds: 0, behindWhy: null };
+}
+export function tableSync(c, now) {
+    const s = c?.synced;
+    return { state: syncStateOf(c, now), 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), ...behindOf(c?.kept, now) };
+}
+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
@@ -61,8 +106,12 @@ export function copyProgress(source, copied, rowsEstimate, p) {
 export function readiness(s) {
     const failed = [], waiting = [];
     for (const t of s.tables.filter((t) => t.added)) {
-        if (t.error) {
-            failed.push(`${t.table}: ${firstLine(t.error)}`);
+        // the table's state in one word (`syncStateOf`), never a second reading of its error or phase: a copied table whose
+        // poll, catch-up, stream or publication check failed is failed here as it is there (issues 100, 82). Behind is said
+        // on its line, never a failure: it is served and being kept. A run from before `sync` was said: its error and phase.
+        const state = t.sync?.state ?? (t.error ? "failed" : t.copy?.phase === "copying" ? "syncing" : !t.copy ? "waiting" : "synced");
+        if (state === "failed") {
+            failed.push(`${t.table}: ${firstLine(t.error ?? "its sync failed (mason status says why)")}`);
             continue;
         }
         if (t.copy?.phase === "copying") {
@@ -70,7 +119,28 @@ 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 };
 }
+/**
+ * WHERE A GENERATED TABLE IS, for `mason wait <table>`: ready once it is served and holds every base change Mason had
+ * synced when the wait began (`since`, ms), across its chain — nothing behind (`behindSince` null), or only changes
+ * committed after it began. A last run that failed, or a parent that blocks it, is a failure, so an agent is never left
+ * waiting for a run that cannot come. The marks are the run's clock and `since` this machine's: `mason wait` reads a run
+ * on this machine.
+ */
+export function generatedReadiness(g, since) {
+    const caught = g.serving && (g.behindSince === null || Date.parse(g.behindSince) > since);
+    if (caught)
+        return { ready: true, failed: [], waiting: [] };
+    const fail = (why) => ({ ready: false, failed: [`${g.table}: ${why}`], waiting: [] });
+    if (g.error !== null)
+        return fail(`its last run failed: ${firstLine(g.error)}`);
+    if (g.state === "refused" && !g.serving)
+        return fail(`refused: ${g.refusals[0]?.message ?? "mason status says why"}`);
+    if (g.waitingFor !== null && /(failed its last run|is refused)$/.test(g.waitingFor))
+        return fail(`not run, because ${g.waitingFor}`);
+    return { ready: false, failed: [], waiting: [`${g.table}: ${!g.serving ? g.waitingFor === null ? "being built" : `waiting for ${g.waitingFor}` :
+                `${Math.round(g.behindSeconds)} s behind its bases; its next run brings in what was synced before the wait`}`] };
+}