@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/cli/preflight.js

@@ -0,0 +1,347 @@
+/**
+ * BEFORE `mason start` STARTS ANYTHING: can it read the database, and should it? Every failure says what to change,
+ * because the landing page's command is meant to be pasted and edited — a wrong password, a
+ * database that does not exist, nothing listening, a URL whose password needs encoding. Then, for a database that is
+ * not on this machine, what polling it would cost and where (src/cdc/poll.ts): a copy over the network, a scan of
+ * every table each poll, a serverless compute kept awake. Read-only: nothing here writes to the database.
+ *
+ * The connection is the change reader's own (src/cdc/pg-wire.ts: TCP, password / md5 / SCRAM, TLS by sslmode), so
+ * what passes here is what the service will use.
+ */
+import * as os from "node:os";
+import { PgConnection, PgError } from "../cdc/pg-wire.js";
+import { parseDatabaseUrl } 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) {
+    try {
+        const u = new URL(url);
+        if (u.password)
+            u.password = "****";
+        return u.toString();
+    }
+    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:****@");
+    }
+}
+/**
+ * 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) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    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).` };
+    }
+    if (u.protocol !== "postgres:" && u.protocol !== "postgresql:")
+        return { problem: `the URL's scheme is ${u.protocol.replace(/:$/, "")}; it must be postgres:// or postgresql://` };
+    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 {
+        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
+        if (remote && !u.searchParams.has("sslmode"))
+            parts.sslmode = "require";
+        return { source: { ...parts, url: u.toString(), remote } };
+    }
+    catch (e) {
+        return { problem: e.message.replace(/^DATABASE_URL/, "the URL") };
+    }
+}
+/** What a failed connection means, and what to change. */
+export function explainConnectError(e, s, o = {}) {
+    const where = `${s.host}:${s.port}`;
+    const msg = e?.message ?? String(e);
+    if (e instanceof PgError) {
+        if (e.code === "28P01" || e.code === "28000") {
+            return {
+                message: `${where} refused user ${s.user}: ${msg}`,
+                hints: [
+                    "Homebrew and Postgres.app: the user is your macOS username, with no password — postgres://" + os.userInfo().username + "@localhost:5432/your_app",
+                    "Docker's postgres image: the user is postgres (or POSTGRES_USER), the password POSTGRES_PASSWORD in your docker-compose.yml",
+                    "A Linux package (apt, dnf): the postgres user has no password until you set one (sudo -u postgres psql -c \"\\password postgres\"); Mason connects over TCP, so peer authentication does not apply",
+                    "Your app's DATABASE_URL (in .env) is a URL that works: pass that",
+                ],
+            };
+        }
+        if (e.code === "3D000")
+            return { message: `${where} has no database ${JSON.stringify(s.database)}`, hints: [] };
+        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: [
+                "Is Postgres running? (brew services list, docker ps, or Postgres.app's window)",
+                "Supabase's local stack listens on 54322; a second Postgres on a machine is often on 5433",
+            ],
+        };
+    }
+    if (/ENOTFOUND|EAI_AGAIN/.test(msg))
+        return { message: `the host ${s.host} does not resolve`, hints: ["Check the host name in the URL"] };
+    if (/timed out|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH/.test(msg)) {
+        return {
+            message: `${where} did not answer`,
+            hints: s.remote
+                ? ["A database in a private network (a VPC) is not reachable from this machine without a tunnel: ssh -L 5433:<db host>:5432 <bastion>, then postgres://…@localhost:5433/…"]
+                : ["Is Postgres running, and listening on that port?"],
+        };
+    }
+    if (/does not accept TLS/.test(msg)) {
+        return { message: msg, hints: ["A database on another machine is read over TLS by default; add ?sslmode=disable to the URL only on a network you trust"] };
+    }
+    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, 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, o);
+        if (e instanceof PgError && e.code === "3D000") {
+            try {
+                const pg = await PgConnection.connect({ ...opts, database: "postgres" });
+                try {
+                    const names = (await pg.query("SELECT datname FROM pg_database WHERE datallowconn AND NOT datistemplate ORDER BY datname")).rows.map((r) => r[0]);
+                    failure.hints.push(`The databases on ${s.host}:${s.port}: ${names.join(", ")}`);
+                }
+                finally {
+                    pg.close();
+                }
+            }
+            catch (inner) {
+                // listing is a courtesy: the refusal above stands either way, and says why the list is missing
+                failure.hints.push(`(could not list the databases there: ${inner.message})`);
+            }
+        }
+        return { failure };
+    }
+}
+/** 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 */
+export const VIEWS_SQL = `SET LOCAL search_path = pg_catalog; SELECT coalesce(json_agg(v ORDER BY v.oid), '[]'::json)::text FROM (
+  SELECT c.oid, n.nspname AS schema, c.relname AS name, pg_get_viewdef(c.oid) AS definition, obj_description(c.oid, 'pg_class') AS comment
+  FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE c.relkind = 'v' AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg\\_%'
+    AND has_table_privilege(c.oid, 'SELECT')
+) 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,
+    -- 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'
+      THEN (SELECT coalesce(sum(greatest(l.reltuples, 0)), 0)::bigint FROM pg_partition_tree(c.oid) pt JOIN pg_class l ON l.oid = pt.relid WHERE pt.isleaf)
+      ELSE greatest(c.reltuples, 0)::bigint END AS reltuples,
+    CASE WHEN c.relkind = 'p'
+      THEN coalesce((SELECT bool_or(l.relpages = 0 AND l.reltuples <= 0) FROM pg_partition_tree(c.oid) pt JOIN pg_class l ON l.oid = pt.relid WHERE pt.isleaf), false)
+      ELSE c.relpages = 0 AND c.reltuples <= 0 END AS unanalysed,
+    CASE WHEN c.relkind = 'p'
+      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 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
+      -- 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,
+        'type_array_oid', (SELECT typarray FROM pg_type WHERE oid = a.atttypid),
+        'default', pg_get_expr(d.adbin, d.adrelid), 'identity', a.attidentity, 'generated', a.attgenerated,
+        -- 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
+      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
+      JOIN pg_attribute a ON a.attrelid = f.conrelid AND a.attnum = f.conkey[1]
+      JOIN pg_class tc ON tc.oid = f.confrelid JOIN pg_namespace tn ON tn.oid = tc.relnamespace
+      JOIN pg_attribute ta ON ta.attrelid = f.confrelid AND ta.attnum = f.confkey[1]
+      WHERE f.conrelid = c.oid AND f.contype = 'f' AND cardinality(f.conkey) = 1) AS foreign_keys
+  FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE c.relkind IN ('r', 'p') AND NOT c.relispartition
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg\\_%'
+    AND has_table_privilege(c.oid, 'SELECT')
+) t`;
+/** 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 database's facts: its version, whether it is a standby, and every table this user can read. */
+export async function readSourceFacts(pg, counted = COUNTED) {
+    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 = [];
+    for (const t of rows ?? []) {
+        let count = t.unanalysed ? counted.get(t.oid) ?? null : Number(t.reltuples);
+        // never analysed: count it when it is small enough to count in a moment, once; a larger one's size is unknown (null)
+        if (count === null && t.unanalysed && Number(t.bytes) < 64 * 1024 * 1024) {
+            count = Number((await pg.query(`SELECT count(*) FROM ${pgQualified(t.schema, t.table)}`)).rows[0]?.[0] ?? "0");
+            counted.set(t.oid, count);
+        }
+        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 } : {}) } : {}),
+                // 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 } : {}) })),
+            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 } : {}),
+        });
+    }
+    // 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 };
+    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 };
+}
+/** 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) {
+    try {
+        return (await pg.query("SELECT system_identifier::text FROM pg_control_system()")).rows[0]?.[0] ?? null;
+    }
+    catch (e) {
+        // 42501 insufficient_privilege: a server that revoked pg_control_system from PUBLIC. The identity is then unknown,
+        // which mason start says it cannot check; it is never guessed
+        if (e instanceof PgError && e.code === "42501")
+            return null;
+        throw e;
+    }
+}
+const pgQualified = (schema, table) => `"${schema.replace(/"/g, '""')}"."${table.replace(/"/g, '""')}"`;
+/** Hosts whose compute sleeps when idle and bills while awake: polling keeps it awake. */
+export function serverlessHost(host) {
+    if (/\.neon\.tech$/i.test(host))
+        return "Neon";
+    if (/\.aws\.neon\.build$/i.test(host))
+        return "Neon";
+    if (/\.supabase\.(co|com)$/i.test(host))
+        return null; // always on: no sleep to keep awake
+    if (/serverless/i.test(host) && /\.rds\.amazonaws\.com$/i.test(host))
+        return "Aurora Serverless";
+    return null;
+}
+/** Why a table cannot be picked, or null: no primary key (a row version needs one). Its size is never a reason, here or
+ *  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 null;
+}
+/** The warnings `mason start` prints, and `mason status` shows, before anything is copied. */
+export function sourceWarnings(s, f) {
+    const out = [];
+    if (!s.remote)
+        return out;
+    out.push(remoteWarning(s));
+    if (!f.standby)
+        out.push("this is a PRIMARY (pg_is_in_recovery() = false): the database your app writes to. A read replica takes the reads instead");
+    const sleeper = serverlessHost(s.host);
+    if (sleeper)
+        out.push(`${sleeper} suspends an idle compute and bills while it runs: polling every few seconds, or an open replication connection, keeps it running`);
+    return out;
+}
+/** 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";
+}
+/**
+ * THE CONFIRMATION A DATABASE ON ANOTHER MACHINE NEEDS (the refusal read as a failed connection and then a fix: only a
+ * careful reading showed it was a warning that wanted a yes, and what the risks were). It is not
+ * a failed step — the check passed — but a stop before anything is written or started, said as one failure a reader
+ * scans: what stopped (the message), what would happen and the risk (why), the one way to say yes (fix, next).
+ */
+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",
+        fix: o.wayOut, next: o.next };
+}
+/** `pg_current_snapshot()` and xid8, which polling reads, arrived in Postgres 13. */
+export function versionProblem(f) {
+    return f.version >= 130000 ? null : `mason start needs Postgres 13 or later (pg_current_snapshot, which it polls with); this is ${f.versionText}`;
+}
+/**
+ * THE ONE CHECK OF A DATABASE (init checks the Postgres connection too, and fails when it cannot connect): connect as
+ * the service will, read its version and tables, say the warnings, and refuse a database on another machine unless
+ * `remote` says it is meant — `mason init` before it writes anything, `mason start` before it starts anything. Every
+ * refusal is said through `say`, with the way out; the result is the exit code then. A database elsewhere that only
+ * lacks the confirmation is answered as `NeedsRemote`: the caller says the confirmation, in its own command's words,
+ * after the check's facts.
+ */
+export async function checkSource(url, o) {
+    const parsed = parseSource(url);
+    if ("problem" in parsed) {
+        o.say(`${o.cmd}: ${parsed.problem}`);
+        return { exit: 2 };
+    }
+    const source = parsed.source;
+    // progress, not a finding: a caller with a checklist of its own (mason start) says it there
+    (o.progress ?? o.say)(`${o.cmd}: connecting to ${maskedUrl(source.url)} …`);
+    const connected = await connectSource(source);
+    if ("failure" in connected) {
+        o.say(`${o.cmd}: could not connect: ${connected.failure.message}`);
+        for (const h of connected.failure.hints)
+            o.say(`  - ${h}`);
+        return { exit: 1 };
+    }
+    let facts;
+    try {
+        facts = await readSourceFacts(connected.pg);
+    }
+    finally {
+        connected.pg.close();
+    }
+    const tooOld = versionProblem(facts);
+    if (tooOld) {
+        o.say(`${o.cmd}: ${tooOld}`);
+        return { exit: 1 };
+    }
+    const warnings = sourceWarnings(source, facts);
+    o.say(`  Postgres ${facts.versionText}${facts.standby ? " (a read replica)" : ""}, ${facts.tables.length} table(s) this user can read. ` +
+        "Mason only reads it: no setting, slot or publication is needed or made.");
+    for (const w of warnings)
+        o.say(`  ! ${w}`);
+    if (source.remote && !o.remote)
+        return { needsRemote: { source, facts, warnings } };
+    return { source, facts, warnings };
+}

package/dist/src/cli/project.js

@@ -0,0 +1,129 @@
+/**
+ * A MASON PROJECT IS A FOLDER (the CLI works like docker's or supabase's: `mason init`, `mason ps`, `mason start` and
+ * `mason stop`). `mason init` makes one where it is run:
+ *
+ *   <root>/.mason/config.json   this machine's: the project's name and the API key (mode 0600, gitignored by init);
+ *                               while Mason runs, how the commands reach it
+ *   <root>/.mason/              the run's state too: the copy of the data (duck.db), the users, the logs (mason destroy
+ *                               empties it, keeping the config and the users)
+ *   <root>/<folder>/sources/    the project's files, yours to commit (`mason/` unless init's --folder says otherwise): one
+ *                               source file, the database and the tables it copies (src/cli/sources.ts); its URL is
+ *                               `${DATABASE_URL}`, from the root's .env (gitignored by init) or the shell
+ *
+ * Every command but init, doctor and help means the project of the folder it is run in: the nearest `.mason/` at or
+ * above it, as git finds `.git`. Nothing is kept in the home folder; the project folder is the only place a project
+ * lives (`--project <name>` and `mason list` found a project through its container's labels, and there is no
+ * container).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
+import { readSource } 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. */
+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);
+    return NAME_RE.test(n) ? n : "mason";
+}
+/** What a recorded run must carry besides its pid (src/cli/dev.ts writes all of it): how the commands reach it. */
+const RUNNING = ["controlUrl", "token", "postgresUrl"];
+/** The fields a config must have, each a string: what every command reads. */
+const REQUIRED = ["name", "folder", "apiKey"];
+/** The project whose `.mason/` is `root`'s; a broken one when its config cannot be read; null when there is none. */
+export function readProject(root) {
+    const dir = path.join(root, STATE_DIR);
+    const file = path.join(dir, CONFIG);
+    if (!fs.existsSync(file))
+        return null;
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        return { root, dir, file, broken: `it is not valid JSON (${e.message})` };
+    }
+    if (typeof config !== "object" || config === null || Array.isArray(config))
+        return { root, dir, file, broken: "it is not a JSON object" };
+    const missing = REQUIRED.filter((k) => typeof config[k] !== "string");
+    if (missing.length)
+        return { root, dir, file, broken: `it has no ${missing.join(", ")} (each a string)` };
+    if (!NAME_RE.test(config.name))
+        return { root, dir, file, broken: `its name ${JSON.stringify(config.name)} is not a project name (lower case letters, digits, - and _)` };
+    // the project's port is what every tool's saved connection names: a value that is no port would make every start refuse
+    const pgPort = config.pgPort;
+    if (pgPort !== undefined && pgPort !== null && !(Number.isInteger(pgPort) && pgPort >= 1 && pgPort <= 65_535)) {
+        return { root, dir, file, broken: `its "pgPort" ${JSON.stringify(pgPort)} is not a port number (1-65535, the Postgres API's port mason start recorded; remove it and the next start chooses one)` };
+    }
+    // a run recorded without how to reach it would read as "not running" and let mason start launch a second service
+    // beside a live one (review of #434): what mason start writes, whole, or nothing
+    const r = config.running;
+    if (r !== undefined && r !== null) {
+        const run = r;
+        const bad = typeof r !== "object" || !Number.isInteger(run.pid) ? ["pid"]
+            : [...RUNNING.filter((k) => typeof run[k] !== "string"), ...(typeof run.postgresListener?.host !== "string" ? ["postgresListener"] : [])];
+        if (bad.length)
+            return { root, dir, file, broken: `its "running" has no ${bad.join(", ")} (mason start writes the whole of it, or null when stopped)` };
+    }
+    return { root, dir, folder: path.resolve(root, config.folder), config };
+}
+/** 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. */
+export function brokenProblem(b) {
+    return { problem: `this folder's Mason project cannot be read: ${b.file}: ${b.broken}`, code: "bad_config",
+        fix: `repair it (JSON: ${REQUIRED.join(", ")}), or move ${b.dir} aside and run mason init again — your project's files stay where they are`,
+        next: [["mason init", `once ${b.dir} is moved aside: a new config for this folder`]] };
+}
+/** The nearest project at or above `cwd`, as git finds a repository (a broken one stops the search: it is the nearest). */
+export function findProject(cwd) {
+    for (let d = path.resolve(cwd);; d = path.dirname(d)) {
+        const p = readProject(d);
+        if (p)
+            return p;
+        if (path.dirname(d) === d)
+            return null;
+    }
+}
+export function writeConfig(dir, c) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = path.join(dir, CONFIG);
+    fs.writeFileSync(file, `${JSON.stringify(c, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+}
+/** A new project's config: the secrets made here, once. */
+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
+ * way out.
+ */
+export function theProject(cwd) {
+    const p = findProject(cwd);
+    if (p && "broken" in p)
+        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 (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://…)"]] };
+}
+/** Whether `root`'s .gitignore already ignores `.mason/`. */
+export function ignoresStateDir(gitignore) {
+    return gitignore.split("\n").map((l) => l.trim()).some((l) => /^\/?\.mason\/?(\*\*?)?$/.test(l));
+}
+/**
+ * THE PROJECT'S SOURCE — its sources file read and its URL resolved (src/cli/sources.ts readSource) — or what is wrong,
+ * with the way out: what every command that reads the database asks (mason start, tables, doctor, destroy). `shellFirst`
+ * for a server's run (mason serve: its environment before any .env).
+ */
+export function projectSource(p, env = process.env, o = {}) {
+    return readSource(p.folder, p.root, env, o);
+}

package/dist/src/cli/readiness.js

@@ -0,0 +1,76 @@
+const n = (x) => x.toLocaleString("en-US");
+const firstLine = (s) => s.split("\n")[0].trim();
+/** A span of seconds as a person reads it: `45 s`, `12 min`, `2 h 5 min`. */
+export function duration(seconds) {
+    const s = Math.max(1, Math.round(seconds));
+    if (s < 90)
+        return `${s} s`;
+    const m = Math.round(s / 60);
+    return m < 90 ? `${m} min` : `${Math.floor(m / 60)} h ${m % 60} min`;
+}
+/**
+ * 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
+ * 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'
+ * progress of the table's row estimate (Postgres's own); below 100 until the copy says it is done, and NEVER BACKWARDS:
+ * a copy that outruns the estimate (23.7 M rows under an estimate of 20.1 M went back to `0% copying
+ * 21,385,158 rows`) stays at its share and says it is past the estimate. Null when nothing gives one.
+ */
+export function copyingText(copied, rowsEstimate, p) {
+    const shown = copied + (p?.rowsReading ?? 0);
+    const estimate = rowsEstimate !== null && rowsEstimate > 0 ? rowsEstimate : null;
+    const past = estimate !== null && shown > estimate;
+    const fraction = p !== undefined ? p.share : estimate === null ? null : Math.min(0.99, shown / estimate);
+    // past the estimate: the count, and that it is past it (the share holds where it was: pages, or capped)
+    const of = estimate === null ? "" : past ? ` · past the ~${n(estimate)} estimated` : ` of ~${n(estimate)}`;
+    const rowsText = (k) => past ? `${n(k)} rows${of}` : `${n(k)}${of} rows`;
+    if (p === undefined)
+        return { fraction, text: rowsText(copied) };
+    const since = p.readingSeconds === null ? "" : ` (${duration(p.readingSeconds)})`;
+    const chunks = (k) => `${k} chunk${k === 1 ? "" : "s"}`;
+    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}` };
+    }
+    const parts = [rowsText(shown)];
+    const allIn = p.reading === 0 && p.chunksDone >= p.chunksTotal;
+    if (allIn)
+        parts.push(`every chunk read (${p.chunksDone}): checking it and swapping it in`);
+    else
+        parts.push(`${p.reading === 0 ? "starting the next chunk" : `${chunks(p.reading)} reading${since}`}, ${p.chunksDone} of ~${p.chunksTotal} in`);
+    parts.push(`${n(Math.round(p.rowsPerSecond))} rows/s`);
+    if (!allIn && p.secondsLeft !== null)
+        parts.push(`~${duration(p.secondsLeft)} left`);
+    return { fraction, text: parts.join(" · ") };
+}
+/** 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}`;
+}
+/**
+ * WHERE A RUN IS. Ready when every added table's copy has ended well: `mason add` followed by `mason wait` returns
+ * once the table is served. A copy that failed is a failure (the sync tries again by itself, and says so in the log),
+ * so an agent is never left waiting for a copy that cannot finish.
+ */
+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)}`);
+            continue;
+        }
+        if (t.copy?.phase === "copying") {
+            waiting.push(copyProgress(t.table, t.copy.rowsCopied, t.rows, t.copy.progress));
+            continue;
+        }
+        if (!t.copy)
+            waiting.push(`${t.table}: waiting for its copy to start`);
+    }
+    return { ready: failed.length === 0 && waiting.length === 0, failed, waiting };
+}