@mason-data/cli 0.8.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 */
@@ -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,24 +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) {
@@ -310,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

@@ -76,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. */
@@ -150,12 +197,64 @@ export function databaseMoved(p, answersAs) {
     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)

package/dist/src/cli/readiness.js

@@ -55,19 +55,30 @@ export function copyProgress(source, copied, rowsEstimate, p) {
     const c = copyingText(copied, rowsEstimate, p);
     return `${source}: ${c.fraction !== null ? `syncing ${Math.floor(c.fraction * 100)}% · ` : /^\d/.test(c.text) ? "syncing " : ""}${c.text}`;
 }
-export function syncStateOf(c) {
+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 "synced";
+    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), 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) };
+    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");
@@ -95,8 +106,12 @@ export function readinessWord(r) {
 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") {
@@ -108,3 +123,24 @@ export function readiness(s) {
     }
     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`}`] };
+}

package/dist/src/cli/registry.js

@@ -12,6 +12,7 @@ import { ADD, LOGS, REMOVE, STATUS, STOP, TABLES, WAIT, add, logs, remove, statu
 import { USER, user } from "./user.js";
 import { MCP, mcp } from "./mcp.js";
 import { SHARE, share } from "./share.js";
+import { DEFAULT_UI_PORT } from "./ports.js";
 import { UI, ui } from "./ui.js";
 import { GUIDES, guideText } from "./guides.js";
 import { DOCTOR, NODE_MIN, doctor } from "./doctor.js";
@@ -21,6 +22,10 @@ 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 { LOGIN, LOGOUT, login, logout } from "./login.js";
+import { DEPLOY, deploy } from "./deploy.js";
+import { REPLICA, replica } from "./replica-hosted.js";
+import { TOKEN, token } from "./token-hosted.js";
 import { PROJECT_LINE } from "./dev.js";
 import { version } from "./version.js";
 import { didYouMean } from "../lib/did-you-mean.js";
@@ -68,6 +73,9 @@ export const DEV = {
   MASON_PG_TLS_KEY (PEM files), or --self-signed-tls, which makes a certificate for the project in .mason/ and serves
   it again at every later start with the flag. Every client then connects with sslmode=require. A team whose own proxy
   or load balancer terminates TLS keeps it on 127.0.0.1, or sets MASON_PG_PLAIN=1 for a private network.
+  Behind a TCP proxy that sends the PROXY protocol v2, MASON_PG_PROXY_FROM=<cidr>[,<cidr>…] names the proxy's own
+  addresses: a connection from one must begin with the header, whose client the request log names, and a header from
+  any other address is refused.
 
   ${PROJECT_LINE}
 
@@ -78,7 +86,7 @@ export const DEV = {
   --attach            stay in the foreground (Ctrl-C stops Mason)
   --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)
+  --port <n>          the port the mason commands reach it on (default ${DEFAULT_UI_PORT}, or the next free one)
   --json              as data, once it is up: { running, pid, postgres: { url, host, port, database, sslmode }, next }
 `,
     options: {
@@ -103,7 +111,7 @@ async function runDev(argv) {
         // 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 });
     }
-    const port = v.port === undefined ? 4039 : Number(v.port);
+    const port = v.port === undefined ? DEFAULT_UI_PORT : Number(v.port);
     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)
@@ -169,7 +177,7 @@ export const STEPS = [
     ["Add your tables", [{ ...TABLES, run: tables }, { ...ADD, run: add }, { ...REMOVE, run: remove }, { ...WAIT, run: wait }]],
     ["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 }]],
+    ["Go to production", [{ ...SERVE, run: serve }, { ...LOGIN, run: login }, { ...LOGOUT, run: logout }, { ...REPLICA, run: replica }, { ...TOKEN, run: token }, { ...DEPLOY, run: deploy }]],
 ];
 /** Every command, in the order `mason --help` lists them. */
 export const COMMANDS = STEPS.flatMap(([, commands]) => commands);
@@ -233,7 +241,7 @@ export function topUsage(s = styleOut()) {
         para("A command means the project of the folder it runs in (or above it)."),
         para("Every command but help and mcp (whose stdout is the MCP protocol's) takes --json: one JSON object for a program, always with next (what to run " +
             "next); a failure is { error: { code, message, why, fix }, next }. The exit code says how it went: 0 done, 1 failed " +
-            "with the reason, 2 a wrong command line, 124 mason wait timed out. Driving Mason from a coding agent: mason help agent."),
+            "with the reason, 2 a wrong command line, 124 a wait timed out (mason wait, mason deploy, mason replica create). Driving Mason from a coding agent: mason help agent."),
         "",
     ].join("\n");
 }