@mason-data/cli 0.0.0-stage → 0.6.2

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

@@ -0,0 +1,100 @@
+/**
+ * THE RUN'S POSTGRES LISTENER, REACHABLE FROM ANOTHER MACHINE (docs/POSTGRES-API.md "Connecting"). On
+ * a test server a hosted BI tool had to reach the run, which listened on 127.0.0.1 with no TLS, and a TLS proxy was
+ * written beside Mason for it. Now `mason start` reads where and how its listener listens with the one reader the
+ * ClickHouse stack's Query API used too (`pgListenerSettings`, src/api/postgres/listener.ts): `MASON_PG_HOST` (default
+ * 127.0.0.1), the port `mason start` chose (`MASON_PG_PORT`'s, or a free one), `MASON_PG_TLS_CERT` / `MASON_PG_TLS_KEY`, and the plain-listener rule
+ * (src/api/postgres/plain.ts): off loopback it needs TLS, or `MASON_PG_PLAIN=1` for a team that terminates TLS in a
+ * proxy of its own.
+ *
+ * `--self-signed-tls` (named for what the developer gets, in the variables' own word, TLS) is a certificate made for
+ * the project in its `.mason/` (0600), recorded in its config and reused by every later start with the flag; it is
+ * handed to the same reader through the same two variables, never a second path. With TLS the listener requires it of
+ * every client (src/api/postgres/server.ts: a plain startup is refused, 28000).
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isLoopback } from "../api/postgres/plain.js";
+import { pgListenerSettings } from "../api/postgres/listener.js";
+import { selfSignedCertificate } from "./self-signed-cert.js";
+/** the self-signed certificate's files, in the project's `.mason/` */
+export const SELF_SIGNED_FILES = { cert: "postgres-tls.crt", key: "postgres-tls.key" };
+/**
+ * Where and how the run's listener listens: the shell's `MASON_PG_*` with the port `mason start` chose and, under
+ * `--self-signed-tls`, the project's own files as the certificate — or why not, as a Problem (what, why, the way out).
+ * Reads no file: `mason start` asks it before it spawns the run, and the run before it connects to the database.
+ */
+export function runListenerSettings(shell, o) {
+    if (o.selfSigned && (shell.MASON_PG_TLS_CERT || shell.MASON_PG_TLS_KEY)) {
+        return { problem: "--self-signed-tls makes a certificate, and MASON_PG_TLS_CERT / MASON_PG_TLS_KEY name one: one or the other", code: "usage",
+            fix: "drop --self-signed-tls to serve your certificate, or unset MASON_PG_TLS_CERT and MASON_PG_TLS_KEY to serve a self-signed one" };
+    }
+    const s = pgListenerSettings({
+        MASON_PG_HOST: shell.MASON_PG_HOST, MASON_PG_PORT: String(o.port), MASON_PG_PLAIN: shell.MASON_PG_PLAIN,
+        MASON_PG_TLS_CERT: o.selfSigned ? path.join(o.home, SELF_SIGNED_FILES.cert) : shell.MASON_PG_TLS_CERT,
+        MASON_PG_TLS_KEY: o.selfSigned ? path.join(o.home, SELF_SIGNED_FILES.key) : shell.MASON_PG_TLS_KEY,
+    }, "127.0.0.1");
+    if (!("problem" in s))
+        return s;
+    return { problem: s.problem, code: "refused", ...(s.why ? { why: s.why } : {}),
+        // the run makes a certificate where the service cannot: said beside the variables
+        ...(s.fix ? { fix: s.kind === "plain" ? `${s.fix}. Or mason start --self-signed-tls: a certificate made for this project in .mason/` : s.fix } : {}),
+        ...(s.kind === "plain" ? { next: [["mason start --self-signed-tls", "TLS from a certificate made in .mason/ (clients connect with sslmode=require)"]] } : {}) };
+}
+/**
+ * The project's self-signed certificate: the one in `.mason/` when it is still good (it parses, its key is its own, it
+ * has not expired), else a new one, both files 0600. `said` is why a new one was made, for the run to print.
+ */
+export function ensureSelfSigned(home, project, now = new Date()) {
+    const certFile = path.join(home, SELF_SIGNED_FILES.cert), keyFile = path.join(home, SELF_SIGNED_FILES.key);
+    const kept = keptCertificate(certFile, keyFile, now);
+    if ("fingerprint" in kept)
+        return { fingerprint: kept.fingerprint, said: null };
+    const made = selfSignedCertificate(`mason-${project}`, { now });
+    for (const [file, text] of [[keyFile, made.key], [certFile, made.cert]]) {
+        fs.writeFileSync(file, text, { mode: 0o600 });
+        fs.chmodSync(file, 0o600); // a file that was there keeps its mode through writeFileSync
+    }
+    return { fingerprint: new crypto.X509Certificate(made.cert).fingerprint256, said: kept.why };
+}
+function keptCertificate(certFile, keyFile, now) {
+    if (!fs.existsSync(certFile) || !fs.existsSync(keyFile))
+        return { why: `made a self-signed certificate: .mason/${SELF_SIGNED_FILES.cert}` };
+    try {
+        const x = new crypto.X509Certificate(fs.readFileSync(certFile));
+        if (!x.checkPrivateKey(crypto.createPrivateKey(fs.readFileSync(keyFile))))
+            return { why: `made a new self-signed certificate: .mason/${SELF_SIGNED_FILES.key} was not the key of .mason/${SELF_SIGNED_FILES.cert}` };
+        if (new Date(x.validTo).getTime() <= now.getTime())
+            return { why: `made a new self-signed certificate: the one in .mason/ expired ${x.validTo}` };
+        return { fingerprint: x.fingerprint256 };
+    }
+    catch (e) {
+        return { why: `made a new self-signed certificate: the one in .mason/ could not be read (${e.message})` };
+    }
+}
+/** The certificate's SHA-256 fingerprint, for a client that checks it by hand; or why it is no certificate. */
+export function certificateFingerprint(pem) {
+    try {
+        return new crypto.X509Certificate(pem).fingerprint256;
+    }
+    catch (e) {
+        return { problem: `MASON_PG_TLS_CERT is not a PEM certificate: ${e.message}` };
+    }
+}
+/** What the listener serves, one line: its address, then TLS (whose certificate) or plain (and on what network). */
+export function listenerText(l, port) {
+    const every = l.host === "0.0.0.0" || l.host === "::";
+    const address = `${l.host.includes(":") ? `[${l.host}]` : l.host}:${port}${every ? " (every address of this machine)" : ""}`;
+    if (l.tls !== null) {
+        return `${address}, TLS required: ${l.tls === "self-signed" ? `a self-signed certificate (.mason/${SELF_SIGNED_FILES.cert})` : "the certificate MASON_PG_TLS_CERT names"}` +
+            `${l.fingerprint ? `, SHA-256 ${l.fingerprint}` : ""}`;
+    }
+    return `${address}, ${isLoopback(l.host) ? "plain: this machine only" : "PLAIN under MASON_PG_PLAIN=1: a password travels in clear on that network"}`;
+}
+/** Where a tool on another machine reaches it, when the recorded URL's host is not that: every address is localhost here. */
+export function elsewhereTip(l) {
+    return l.host === "0.0.0.0" || l.host === "::"
+        ? "It listens on every address of this machine: from another machine, put this machine's address or name in place of localhost."
+        : null;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * THE POSTGRES API'S URL, as the commands print it (`mason connect`'s helpers before it went: `mason user` is the one
+ * credential). A run records where its listener is as `postgresql://<host>:<port>/<database>` with no credential
+ * (src/cli/dev.ts); `mason user add` prints the URL a tool pastes, with the user and its password in it; `mason start`
+ * and `mason status` print it with the credential's PLACE shown, never a credential. WHAT A PERSON SEES BEGINS
+ * `postgres://` (a printed `postgresql://` read as inconsistent with everything else the CLI shows): the scheme every
+ * example, usage line and `mason init` uses; the recorded form keeps `postgresql://` (both are libpq's), and
+ * `withoutPlaceholders` maps the shown form back to it.
+ */
+import { shellWord } from "../lib/shell-word.js";
+import { elsewhereTip } from "./pg-tls.js";
+/** The parts of a recorded `postgresql://<host>:<port>/<database>`. A URL that is not one is a bug in what wrote it, said so. */
+export function postgresLink(recorded) {
+    let u;
+    try {
+        u = new URL(recorded);
+    }
+    catch {
+        throw new Error(`the recorded Postgres API ${JSON.stringify(recorded)} is not a URL`);
+    }
+    if (u.protocol !== "postgresql:" || !u.port || u.pathname.length < 2)
+        throw new Error(`the recorded Postgres API ${JSON.stringify(recorded)} is not postgresql://<host>:<port>/<database>`);
+    // a bracketed IPv6 host is spelled as the driver takes it
+    const sslmode = u.searchParams.get("sslmode");
+    if (sslmode !== null && sslmode !== "require")
+        throw new Error(`the recorded Postgres API ${JSON.stringify(recorded)} has sslmode=${sslmode}: a run records require or none`);
+    return { url: recorded, host: u.hostname.replace(/^\[|\]$/g, ""), port: Number(u.port), database: decodeURIComponent(u.pathname.slice(1)), ...(sslmode ? { sslmode } : {}) };
+}
+/** The connection URL a tool takes: the link with a user and its password, each escaped for a URL; with `password`
+ *  null, the user alone (psql takes the password from PGPASSWORD). */
+export function connectionUrl(link, user, password) {
+    const host = link.host.includes(":") ? `[${link.host}]` : link.host;
+    return `postgres://${encodeURIComponent(user)}${password === null ? "" : `:${encodeURIComponent(password)}`}@${host}:${link.port}/${encodeURIComponent(link.database)}` +
+        (link.sslmode ? `?sslmode=${link.sslmode}` : "");
+}
+/** The recorded URL with the credentials' PLACE shown — `postgres://<user>:<password>@host:port/db` — for a line that
+ *  must never carry a credential (mason start, mason status). */
+export const withPlaceholders = (recorded) => recorded.replace(/^postgresql:\/\//, "postgres://<user>:<password>@");
+/** The recorded URL back from its placeholder form (mason start's relay reads its own line). */
+export const withoutPlaceholders = (shown) => shown.replace(/^postgres:\/\/<user>:<password>@/, "postgresql://");
+/** The psql line for a URL, quoted for a shell. */
+export const psqlLine = (url) => `psql ${shellWord(url)}`;
+/** What a tool connecting to the listener should know: it listens on every address; its certificate is self-signed. */
+export function listenerTips(l) {
+    if (l === null)
+        return [];
+    const elsewhere = elsewhereTip(l);
+    return [
+        ...(elsewhere ? [elsewhere] : []),
+        ...(l.tls === "self-signed" ? [`The certificate is self-signed: sslmode=require encrypts and checks no certificate; to check it by hand, its SHA-256 is ${l.fingerprint ?? "in mason status"}.`] : []),
+    ];
+}

package/dist/src/cli/pin.js

@@ -0,0 +1,36 @@
+/**
+ * THE PROJECT'S VERSION PIN, as the mason command holds it (src/lib/project-version.ts has the rule and the image's
+ * side): `mason init` writes `mason.yml` with this command's version, `mason start` writes it into a project made
+ * before there was one, and `mason init` and `mason start` refuse a command of another release line — what the
+ * developer runs is then what production's image is held to.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseVersion, pinFileText, pinProblem, readPin, versionText, PIN_FILE } from "../lib/project-version.js";
+/** Why this mason command may not run the project in `folder`, or null (a checkout's `dev` checks nothing). */
+export function cliPinProblem(folder, cliVersion) {
+    const running = parseVersion(cliVersion);
+    if (running === null)
+        return null;
+    const read = readPin(folder);
+    if ("problem" in read)
+        return read.problem;
+    if (read.pin === null)
+        return null;
+    const p = versionText(read.pin);
+    return pinProblem(read.pin, running, read.file, "this mason command", `Run the mason command it names: npm i -g @mason-data/cli@${p} (or npx @mason-data/cli@${p} …).`);
+}
+/**
+ * Write `folder`'s mason.yml with this command's version when it has none; the file written, or null when there was one
+ * already (or this is a checkout's `dev`, which has no version to write).
+ */
+export function ensurePin(folder, cliVersion) {
+    if (parseVersion(cliVersion) === null)
+        return null;
+    const file = path.join(folder, PIN_FILE);
+    if (fs.existsSync(file))
+        return null;
+    fs.mkdirSync(folder, { recursive: true });
+    fs.writeFileSync(file, pinFileText(cliVersion));
+    return file;
+}

package/dist/src/cli/ports.js

@@ -0,0 +1,118 @@
+/**
+ * WHETHER A PORT IS FREE, DECIDED IN ONE PLACE (#499 finding 5): `mason start` picks its ports here and
+ * `mason doctor` reports them from here, so the two cannot disagree.
+ *
+ * A port is free only when no address a client may use is held. A probe of 127.0.0.1 alone binds beside a process on
+ * the wildcard (macOS allows it; OrbStack publishes a container's port on *:5433), and `::` (v6only) binds beside one on
+ * ::1 alone (macOS again: Node binds `localhost` there) — so 127.0.0.1:5433 reached Mason while a container, or a driver
+ * trying ::1 first, reached another server. An address family the machine lacks (no IPv6) holds nothing.
+ *
+ * A probe binds and lets go: it says who holds a port NOW, never that it stays free until the service listens on it.
+ */
+import * as net from "node:net";
+import { DEFAULT_PG_PORT, pgListenerAddress } from "../api/postgres/listener.js";
+export const PROBE_ADDRESSES = ["127.0.0.1", "0.0.0.0", "::", "::1"];
+/** The address that holds `port`, or null when every address binds. */
+export async function portHolder(port) {
+    for (const address of PROBE_ADDRESSES) {
+        const code = await new Promise((resolve) => {
+            const srv = net.createServer();
+            srv.once("error", (e) => resolve(e.code ?? "ERROR"));
+            srv.listen({ port, host: address, ipv6Only: address === "::" }, () => srv.close(() => resolve(null)));
+        });
+        if (code === null || code === "EADDRNOTAVAIL" || code === "EAFNOSUPPORT")
+            continue;
+        return { address, code };
+    }
+    return null;
+}
+/** Why a held port cannot be listened on, in a developer's words. */
+export function heldText(port, held) {
+    return held.code === "EACCES"
+        ? `port ${port} needs root here (a bind on ${held.address} answered EACCES): a port below 1024 is the system's`
+        : `something holds port ${port} on ${held.address} (${held.code})`;
+}
+/**
+ * A port free on every address, preferring `want`; `avoid` are ports already chosen for another listener of the same
+ * start (probed and let go, so a probe would call them free). `skipped` says who held `want` when another was chosen.
+ */
+export async function pickPort(want, avoid = new Set()) {
+    const held = avoid.has(want) ? { address: "this mason start", code: "chosen for another listener" } : await portHolder(want);
+    if (!held)
+        return { port: want };
+    for (let attempt = 0; attempt < 20; attempt++) {
+        // the OS picks on the wildcard, so the port it returns is free there; the probe then checks the other addresses
+        const port = await new Promise((resolve, reject) => {
+            const srv = net.createServer();
+            srv.once("error", reject);
+            srv.listen(0, "0.0.0.0", () => { const a = srv.address(); srv.close(() => resolve(a.port)); });
+        });
+        if (!avoid.has(port) && !(await portHolder(port)))
+            return { port, skipped: held };
+    }
+    throw new Error(`no free TCP port found on this machine after 20 tries (${heldText(want, held)}). Free some ports, then run mason start again`);
+}
+/** A free port, preferring `want` (`pickPort`). */
+export async function freePort(want, avoid) {
+    return (await pickPort(want, avoid)).port;
+}
+const PG_PORT_WAY_OUT = "set another MASON_PG_PORT (1024-65535), or unset it and mason start picks a free port";
+/** `MASON_PG_PORT` as the shell gives it, before any probe: a port to listen on, or why it is not one. */
+export function namedPgPort(named) {
+    const parsed = pgListenerAddress({ MASON_PG_PORT: named }, "127.0.0.1");
+    if ("problem" in parsed)
+        return { problem: parsed.problem, code: "refused", fix: PG_PORT_WAY_OUT };
+    if (parsed.port === 0)
+        return { problem: "MASON_PG_PORT=0 is not a port the Postgres API can be reached on", code: "refused",
+            why: "0 asks the system for any free port, and mason start would record port 0", fix: PG_PORT_WAY_OUT };
+    return { port: parsed.port };
+}
+/** The refusal for a named `MASON_PG_PORT` that is held: what, why (who holds it), the way out. */
+export function heldPgPort(port, held) {
+    return held.code === "EACCES"
+        ? { problem: `MASON_PG_PORT=${port} needs root`, code: "refused", why: heldText(port, held), fix: PG_PORT_WAY_OUT }
+        : { problem: `MASON_PG_PORT=${port} is in use`, code: "refused", why: `${heldText(port, held)}, so the Postgres API cannot listen there`,
+            fix: `stop what holds it (lsof -nP -iTCP:${port} -sTCP:LISTEN names it), or ${PG_PORT_WAY_OUT}` };
+}
+/** The refusal for the PROJECT'S recorded port that is held: it is never swapped, because every tool's saved connection names it. */
+export function heldProjectPort(port, held) {
+    const moved = `MASON_PG_PORT=<n> mason start moves this project to another port (every tool's saved connection must change with it)`;
+    return held.code === "EACCES"
+        ? { problem: `this project's Postgres API port ${port} needs root`, code: "refused", why: heldText(port, held), fix: moved }
+        : { problem: `this project's Postgres API port ${port} is in use`, code: "refused",
+            why: `${heldText(port, held)}, so the Postgres API cannot listen there; the port is the project's since its first start, so a tool's saved connection keeps working`,
+            fix: `stop what holds it (lsof -nP -iTCP:${port} -sTCP:LISTEN names it), or ${moved}` };
+}
+/**
+ * THE POSTGRES API'S PORT, THE PROJECT'S OWN (it must not change at every restart, even on a laptop, or every BI
+ * tool's saved credentials need updating each time). `recorded` is
+ * the port the project's first start chose (`ProjectConfig.pgPort`): every later start uses it, or is REFUSED by name
+ * when it is held (`heldProjectPort`), never moved to another port by itself. `MASON_PG_PORT` set in the shell is the
+ * developer naming it, or moving the project to it: used if free on every address, else REFUSED by name, and said as a
+ * move when it differs from the recorded one. With neither, 5433 is preferred and the next free port taken, and `said`
+ * names the address that held 5433 (often a second Postgres: an application's own stack); the caller records the choice.
+ * `avoid`: ports this start has already chosen. Free at the probe, not reserved (above): a later holder is the
+ * service's EADDRINUSE to say.
+ */
+export async function choosePgPort(named, avoid = new Set(), recorded = null) {
+    if (named !== undefined && named !== "") {
+        const n = namedPgPort(named);
+        if ("problem" in n)
+            return n;
+        const held = avoid.has(n.port) ? { address: "this mason start", code: "chosen for another listener" } : await portHolder(n.port);
+        if (held)
+            return heldPgPort(n.port, held);
+        const moved = recorded !== null && recorded !== n.port ? `, moved from ${recorded}: every tool's saved connection must change to it` : "";
+        return { port: n.port, said: `Postgres API: port ${n.port} (from MASON_PG_PORT)${moved}` };
+    }
+    if (recorded !== null) {
+        const held = avoid.has(recorded) ? { address: "this mason start", code: "chosen for another listener" } : await portHolder(recorded);
+        if (held)
+            return heldProjectPort(recorded, held);
+        return { port: recorded };
+    }
+    const { port, skipped } = await pickPort(DEFAULT_PG_PORT, avoid);
+    return skipped
+        ? { port, said: `Postgres API: ${heldText(DEFAULT_PG_PORT, skipped)}, often another Postgres, so using ${port}, this project's port from now on (MASON_PG_PORT=<n> mason start moves it)` }
+        : { port };
+}

package/dist/src/cli/preflight.js

@@ -0,0 +1,338 @@
+/**
+ * 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 {
+        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 {
+        return { problem: `${JSON.stringify(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) {
+    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)) {
+        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) {
+    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);
+        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,
+    (SELECT coalesce(json_agg(a.attname ORDER BY k.n), '[]'::json)
+      FROM pg_index i CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, n)
+      JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
+      WHERE i.indrelid = c.oid AND i.indisprimary) AS key,
+    (SELECT coalesce(json_agg(json_build_object('name', ic.relname, 'constraint', EXISTS (SELECT FROM pg_constraint u WHERE u.conindid = i.indexrelid AND u.contype = 'u'),
+        -- indnullsnotdistinct is Postgres 15's: read through the row, which an older server's lacks
+        'nulls_not_distinct', coalesce((to_jsonb(i) ->> 'indnullsnotdistinct')::boolean, false),
+        'columns', (SELECT json_agg(a.attname ORDER BY k.n) FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, n)
+          JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum)) ORDER BY ic.relname), '[]'::json)
+      FROM pg_index i JOIN pg_class ic ON ic.oid = i.indexrelid
+      WHERE i.indrelid = c.oid AND i.indisunique AND NOT i.indisprimary AND i.indpred IS NULL AND i.indexprs IS NULL
+        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 };
+}