@mason-data/cli 0.0.0-stage → 0.6.2

package/dist/src/cli/project.js

@@ -0,0 +1,127 @@
+/**
+ * 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";
+/** 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) {
+    return { name, folder, remote, 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",
+        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 };
+}

package/dist/src/cli/registry.js

@@ -0,0 +1,217 @@
+/**
+ * EVERY `mason` COMMAND, AND THE HELP MADE FROM THEM. `mason --help` is generated from this list — each
+ * command's summary, in this order — so a command cannot exist without being listed, and tests/cli-help.test.ts holds
+ * each one to src/cli/command.ts's rules (its own --help, an example, every option documented).
+ */
+import { failed, parseCommand, reportText } from "./command.js";
+import { dev } from "./dev.js";
+import { devInBackground } from "./background.js";
+import { ADD, LOGS, REMOVE, STATUS, STOP, TABLES, WAIT, add, logs, remove, status, stop, tables, wait } from "./commands.js";
+import { USER, user } from "./user.js";
+import { UI, ui } from "./ui.js";
+import { GUIDES, guideText } from "./guides.js";
+import { DOCTOR, NODE_MIN, doctor } from "./doctor.js";
+import { DESTROY, destroy } from "./machine.js";
+import { INIT, init } from "./init.js";
+import { SYNC, sync } from "./sync.js";
+import { SERVE, serve } from "./serve.js";
+import { PROJECT_LINE } from "./dev.js";
+import { version } from "./version.js";
+import { didYouMean } from "../lib/did-you-mean.js";
+import { out as styleOut, wrap } from "./style.js";
+import { theProject } from "./project.js";
+import { liveRun } from "./runs.js";
+export { version } from "./version.js";
+export const DEV = {
+    needs: "project",
+    name: "start",
+    summary: "start Mason for this folder's project, in the background (mason init makes the project)",
+    usage: `usage: mason start [--attach] [--replication [--publication <name>] | --poll] [--self-signed-tls] [--port <n>] [--json]
+
+  Starts Mason for the project of this folder (mason init made it): one process, which copies the tables you add
+  (mason add) from the project's database into its own file, keeps them current, and answers the Postgres protocol
+  for BI tools and your app. It only reads the database (SELECT): no wal_level, replication slot or publication is
+  needed or made. It returns once Mason is up; run it again any time (it says so when Mason is already running). The
+  copy and Mason's state stay between runs: the next start resumes.
+
+  With --replication it reads the database's change log instead: it needs wal_level = logical and a user that may
+  replicate, and makes its own publication and replication slot on the database (mason destroy, or mason start --poll,
+  drops them). The project keeps the mode until --poll; a switch keeps the copies and catches each table up by one
+  poll. --publication <name> (else PG_PUBLICATION) names a publication that is the database owner's: it is read as it
+  is, verified to carry every added table and column, and never created, altered or dropped — Mason makes only its
+  slot. A read replica needs one (it takes no CREATE PUBLICATION). The name is kept with the project, so the next
+  mason start --replication reads it again.
+
+  The Postgres API's port is the project's: the first start takes 5433, or the next port free on every address when a
+  second Postgres holds it, and records it; every later start listens on the same port, so a BI tool's saved connection
+  keeps working, and refuses, naming what holds it, rather than move. MASON_PG_PORT=<n> in your shell names the port,
+  or moves the project to it (said): that port is used, or start refuses, naming what holds it.
+
+  The Postgres API listens on 127.0.0.1 unless MASON_PG_HOST names another address (0.0.0.0: every address of this
+  machine). Off this machine a password travels on the connection, so it then needs TLS: MASON_PG_TLS_CERT and
+  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.
+
+  ${PROJECT_LINE}
+
+    mason start
+    mason start --attach      in the foreground: Ctrl-C stops it
+    mason start --replication read the change log, as production does
+    mason start --replication --publication app_pub   through the database owner's publication
+    MASON_PG_HOST=0.0.0.0 mason start --self-signed-tls   the Postgres API for other machines, over TLS
+
+  --attach            stay in the foreground (Ctrl-C stops Mason)
+  --replication       read the database's changes from its change log (logical replication), as production does
+  --publication <name>  with --replication: the publication to read, the owner's, never altered (PG_PUBLICATION;
+                      default: Mason's own, mason_dev_<project>_<source>)
+  --poll              read them with SELECTs (the default; takes back --replication)
+  --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)
+  --json              as data, once it is up: { running, pid, postgres: { url, host, port, database, sslmode }, next }
+`,
+    options: {
+        port: { type: "string" }, attach: { type: "boolean", default: false }, json: { type: "boolean", default: false },
+        replication: { type: "boolean", default: false }, poll: { type: "boolean", default: false }, publication: { type: "string" },
+        "self-signed-tls": { type: "boolean", default: false },
+    },
+    json: ["running", "pid", "postgres", "next"],
+};
+async function runDev(argv) {
+    const f = parseCommand(DEV, argv);
+    if (typeof f === "number")
+        return f;
+    const v = f.values;
+    if (v.replication && v.poll)
+        return failed("start", { message: "--replication or --poll, not both", code: "usage", usage: DEV.usage }, { json: v.json });
+    if (v.publication !== undefined && v.poll)
+        return failed("start", { message: "--publication goes with --replication, not --poll", code: "usage", usage: DEV.usage }, { json: v.json });
+    if (v.publication !== undefined && !/^\S+$/.test(v.publication))
+        return failed("start", { message: `--publication must name a publication, not ${JSON.stringify(v.publication)}`, code: "usage", usage: DEV.usage }, { json: v.json });
+    if (f.positionals.length) {
+        // 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);
+    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)
+        return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"] });
+    return dev({ port, version: version(), changes: v.replication ? "replication" : v.poll ? "poll" : null, publication: v.publication ?? null, selfSignedTls: v["self-signed-tls"] });
+}
+export const HELP = {
+    name: "help",
+    summary: "the commands by step, or one command's usage: mason help add",
+    usage: `usage: mason help [<command> | <guide>]
+
+  The commands by step (mason help), how to use one (mason help add — the same as mason add --help), or a guide,
+  offline, short enough to read whole and listing exactly what Mason accepts:
+
+    mason help
+    mason help add
+${Object.entries(GUIDES).map(([k, v]) => `    mason help ${k.padEnd(14)} ${v}`).join("\n")}
+`,
+    options: {},
+};
+async function runHelp(argv) {
+    const f = parseCommand(HELP, argv);
+    if (typeof f === "number")
+        return f;
+    const [asked, ...rest] = f.positionals;
+    if (rest.length)
+        return failed("help", { message: "one command or guide at a time", code: "usage", usage: HELP.usage }, { json: false });
+    if (asked === undefined) {
+        process.stdout.write(topUsage());
+        return 0;
+    }
+    if (asked === "version") {
+        process.stdout.write("usage: mason version (or --version, -v): the CLI's version\n");
+        return 0;
+    }
+    if (Object.hasOwn(GUIDES, asked)) {
+        process.stdout.write(await guideText(asked));
+        return 0;
+    }
+    const cmd = COMMANDS.find((c) => c.name === asked);
+    if (cmd) {
+        process.stdout.write(cmd.usage);
+        return 0;
+    }
+    return failed("help", { message: `there is no command or guide ${JSON.stringify(asked)}${didYouMean(asked, [...COMMANDS.map((c) => c.name), ...Object.keys(GUIDES)])}`, code: "usage",
+        why: `the guides: ${Object.keys(GUIDES).join(", ")}`, next: [["mason help", "every command"]] }, { json: false });
+}
+/**
+ * EVERY COMMAND, IN THE ORDER A FIRST SESSION NEEDS THEM (listed in the order a developer will likely need them, the
+ * reference, `mason help`, first because it is read first), under the step each belongs to: `mason --help` prints the
+ * steps as headings, so the list reads as the runbook it is. A new command goes into its step here; COMMANDS is
+ * derived, so the order is written once.
+ */
+export const STEPS = [
+    ["Learn", [{ ...HELP, run: runHelp }]],
+    ["Set up", [{ ...DOCTOR, run: (argv) => doctor(argv) }, { ...INIT, run: (argv) => init(argv) }, { ...DEV, run: runDev }]],
+    ["Add your tables", [{ ...TABLES, run: tables }, { ...ADD, run: add }, { ...REMOVE, run: remove }, { ...WAIT, run: wait }]],
+    ["Connect", [{ ...USER, run: user }]],
+    ["Run", [{ ...STATUS, run: status }, { ...UI, run: ui }, { ...SYNC, run: sync }, { ...LOGS, run: logs }, { ...STOP, run: stop }, { ...DESTROY, run: (argv) => destroy(argv) }]],
+    ["Go to production", [{ ...SERVE, run: serve }]],
+];
+/** Every command, in the order `mason --help` lists them. */
+export const COMMANDS = STEPS.flatMap(([, commands]) => commands);
+/**
+ * `mason` ALONE: where you are and what to run next (`mason help` once showed the same as `mason` alone, and read as
+ * broken). One line on what Mason is, whether this folder is a project and whether Mason runs for
+ * it, then the next command for that moment — and mason help, every command. `mason help` and `mason --help` are the
+ * whole list (topUsage).
+ */
+export async function orientation(cwd, s = styleOut()) {
+    const t = theProject(cwd);
+    const project = "project" in t ? t.project : null;
+    const run = project ? await liveRun(project) : null;
+    const rows = project
+        ? [["Project", `${project.config.name}, files in ${project.folder}`], ["Mason", run ? `running (pid ${run.pid})` : "not running"]]
+        : [["Project", "none here: mason init makes this folder one"]];
+    const next = !project
+        ? [["mason init", "make this folder a project (DATABASE_URL from .env, or mason init postgres://…)"], ["mason doctor", "what this machine needs for Mason, and whether it has it"]]
+        : !run ? [["mason start", "start Mason for this project, in the background"], ["mason status", "the project and its tables"]]
+            : [["mason status", "what Mason is doing: its tables, and the last day's slow and refused statements"], ["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"]];
+    return `${reportText({ headline: "Mason: your Postgres tables, copied and served to BI tools and your app.", details: rows,
+        next: [...next, ["mason help", "every command, and the guides"]] }, s)}\n`;
+}
+/** `mason --help`: what Mason is, every command with its summary, and where each one's help is. On a terminal the steps are
+ *  bold, the commands cyan and every line wrapped at its width under its own column (src/cli/style.ts); anywhere else,
+ *  plain and unwrapped. */
+export function topUsage(s = styleOut()) {
+    // what each step lists: its commands, and under Learn the guides too (`mason help` shows the guides listed under
+    // Learn), so the pages a session reads first are a line each, not a paragraph after the list
+    const entries = (step, commands) => [
+        ...commands.map((c) => [c.name, c.summary]),
+        ...(step === "Learn" ? Object.entries(GUIDES).map(([g, what]) => [`help ${g}`, what]) : []),
+    ];
+    const listed = STEPS.map(([step, commands]) => [step, entries(step, commands)]);
+    // the commands' column is the longest COMMAND's, everywhere; a guide's longer name widens Learn alone, so it never
+    // pushes every other step's summaries right
+    const commandWidth = Math.max(...COMMANDS.map((c) => c.name.length));
+    const para = (text) => `  ${wrap(text, s.width, 2)}`;
+    const block = (es) => {
+        const w = Math.max(commandWidth, ...es.map(([name]) => name.length));
+        // the column a summary starts in: "    mason " + the longest name + 3
+        const col = 4 + "mason ".length + w + 3;
+        return es.map(([name, summary]) => `    ${s.cyan(`mason ${name.padEnd(w)}`)}   ${s.dim(wrap(summary, s.width, col))}`).join("\n");
+    };
+    return [
+        `${s.bold("usage:")} mason <command> [options]`,
+        "",
+        para("Mason: your Postgres tables, copied and served to BI tools and your app. Make your app's folder a project (mason init), " +
+            `start Mason (mason start), add tables, connect a tool (mason user add). It needs Node ${NODE_MIN} or later; mason doctor checks.`),
+        para(PROJECT_LINE),
+        "",
+        listed.map(([step, es]) => `  ${s.bold(step)}\n${block(es)}`).join("\n\n"),
+        "",
+        para("mason <command> --help (or mason help <command>) says how to use one, with examples; the guides are offline and short enough to read whole."),
+        para("A command means the project of the folder it runs in (or above it)."),
+        para("Every command but help 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."),
+        "",
+    ].join("\n");
+}

package/dist/src/cli/replication-checks.js

@@ -0,0 +1,120 @@
+/** Everything the checks read of the server, in one statement: settings and roles only. */
+export const SERVER_FACTS_SQL = `SELECT json_build_object(
+  'version', current_setting('server_version_num')::int, 'version_text', current_setting('server_version'),
+  'standby', pg_is_in_recovery(), 'user', current_user,
+  'wal_level', current_setting('wal_level'),
+  'slot_wal_keep_mb', (SELECT CASE WHEN setting = '-1' THEN -1 ELSE setting::bigint END FROM pg_settings WHERE name = 'max_slot_wal_keep_size'),
+  'max_slots', current_setting('max_replication_slots')::int, 'slots_used', (SELECT count(*) FROM pg_replication_slots),
+  'max_senders', current_setting('max_wal_senders')::int, 'senders_used', (SELECT count(*) FROM pg_stat_replication),
+  'superuser', r.rolsuper, 'replication', r.rolreplication,
+  'rds', CASE WHEN EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'rds_replication')
+    THEN json_build_object('member', pg_has_role(current_user, 'rds_replication', 'member')) END,
+  'cloud_sql', current_setting('cloudsql.logical_decoding', true) IS NOT NULL,
+  'hot_standby_feedback', current_setting('hot_standby_feedback') = 'on',
+  'idle_in_transaction_ms', (SELECT setting::bigint FROM pg_settings WHERE name = 'idle_in_transaction_session_timeout'),
+  'statement_timeout_ms', (SELECT setting::bigint FROM pg_settings WHERE name = 'statement_timeout')
+)::text FROM pg_roles r WHERE r.rolname = current_user`;
+/** pg_stat_wal (Postgres 14+): the WAL written since the statistics were reset, and over how long. */
+export const WAL_RATE_SQL = "SELECT wal_bytes::text, extract(epoch FROM now() - stats_reset)::text FROM pg_stat_wal";
+export async function readServerFacts(pg) {
+    const j = JSON.parse((await pg.query(SERVER_FACTS_SQL)).rows[0]?.[0] ?? "null");
+    if (j === null)
+        throw new Error("the server's settings did not read (no pg_roles row for this user)");
+    let walBytesPerSecond = null;
+    if (Number(j.version) >= 140000 && j.standby !== true) {
+        const r = (await pg.query(WAL_RATE_SQL)).rows[0];
+        const bytes = Number(r?.[0]), seconds = Number(r?.[1]);
+        // a reset moments ago says nothing about the rate: an hour of statistics at least
+        if (Number.isFinite(bytes) && Number.isFinite(seconds) && seconds >= 3600)
+            walBytesPerSecond = bytes / seconds;
+    }
+    return {
+        version: Number(j.version), versionText: String(j.version_text), standby: j.standby === true, user: String(j.user),
+        walLevel: String(j.wal_level), slotWalKeepMb: Number(j.slot_wal_keep_mb),
+        maxSlots: Number(j.max_slots), slotsUsed: Number(j.slots_used), maxSenders: Number(j.max_senders), sendersUsed: Number(j.senders_used),
+        superuser: j.superuser === true, replication: j.replication === true,
+        rds: j.rds === null || j.rds === undefined ? null : { member: j.rds.member === true },
+        cloudSql: j.cloud_sql === true, hotStandbyFeedback: j.hot_standby_feedback === true,
+        idleInTransactionMs: Number(j.idle_in_transaction_ms), statementTimeoutMs: Number(j.statement_timeout_ms), walBytesPerSecond,
+    };
+}
+/** The slot Mason would read, if it exists: whether a reader holds it and whether Postgres invalidated it. */
+export async function readSlotFacts(pg, slot) {
+    const r = (await pg.query(`SELECT active::text, active_pid::text, wal_status, plugin FROM pg_replication_slots WHERE slot_name = '${slot.replace(/'/g, "''")}'`)).rows[0];
+    return r ? { active: r[0] === "true", activePid: r[1] ? Number(r[1]) : null, walStatus: r[2] ?? null, plugin: r[3] ?? null } : null;
+}
+/** The way out of a slot another reader holds, in the words of the command that met it. */
+/** Bytes as a person reads them: 1.4 GiB, 312 MiB, 18 KiB. */
+export function bytesText(n) {
+    const units = ["bytes", "KiB", "MiB", "GiB", "TiB"];
+    let i = 0, v = n;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return i === 0 ? `${n} bytes` : `${v < 10 ? v.toFixed(1) : Math.round(v)} ${units[i]}`;
+}
+const q = (s) => /^[a-z_][a-z0-9_]*$/.test(s) ? s : `"${s.replace(/"/g, '""')}"`;
+/**
+ * A `max_slot_wal_keep_size` to suggest: a day of this server's WAL at its measured rate, rounded up to a whole GB, at
+ * least 4 GB; null when the rate is unknown (a standby, Postgres 13, statistics reset within the hour).
+ */
+export function suggestedWalCapGb(bytesPerSecond) {
+    if (bytesPerSecond === null)
+        return null;
+    return Math.max(4, Math.ceil((bytesPerSecond * 86_400) / 1024 ** 3));
+}
+/** What wal_level = logical takes on this server: its provider's way, or postgresql.conf's. */
+function walLevelFix(f) {
+    if (f.rds)
+        return "set rds.logical_replication = 1 in the DB parameter group (Aurora: the DB cluster parameter group), then reboot the instance";
+    if (f.cloudSql)
+        return "set the database flag cloudsql.logical_decoding = on (the instance restarts)";
+    return "set wal_level = logical (ALTER SYSTEM SET wal_level = logical, or postgresql.conf; a managed Postgres: its parameter or flag of that name), then restart Postgres";
+}
+/** The checks of the server for the stream (REPLICATION). */
+export function replicationChecks(f, slot, slotState) {
+    const out = [];
+    out.push(f.walLevel === "logical"
+        ? { name: "wal_level", ok: true, detail: "logical" }
+        : { name: "wal_level", ok: false, detail: `${f.walLevel}: logical replication needs logical. To fix: ${walLevelFix(f)}. Or read changes by polling instead (--poll: SELECT alone, for a small database)` });
+    if (f.standby) {
+        out.push(f.version >= 160000
+            ? { name: "standby", ok: true, warn: !f.hotStandbyFeedback,
+                detail: `a read replica (Postgres 16+ decodes on a standby)${f.hotStandbyFeedback ? "" : ". hot_standby_feedback is off: the primary may remove catalog rows the slot still needs, which invalidates it (Mason then rebuilds from scratch) — turn it on"}` }
+            : { name: "standby", ok: false, detail: `a read replica on Postgres ${f.versionText}: logical decoding on a standby needs Postgres 16. Point Mason at the primary, upgrade the replica, or poll it (--poll)` });
+    }
+    const canReplicate = f.superuser || f.replication || f.rds?.member === true;
+    out.push(canReplicate
+        ? { name: "replication role", ok: true, detail: `${f.user} may replicate${f.superuser ? " (a superuser)" : f.rds?.member ? " (rds_replication)" : " (REPLICATION)"}` }
+        : { name: "replication role", ok: false, detail: `${f.user} may not open a replication connection`,
+            sql: f.rds ? `GRANT rds_replication TO ${q(f.user)};` : `ALTER ROLE ${q(f.user)} WITH REPLICATION;` });
+    const free = f.maxSlots - f.slotsUsed;
+    if (slotState) {
+        out.push(slotState.walStatus === "lost"
+            ? { name: "slot", ok: true, warn: true, detail: `${slot} exists and Postgres invalidated it (wal_status lost): Mason drops it and rebuilds from scratch at its start` }
+            : slotState.active
+                ? { name: "slot", ok: false, detail: `${slot} is in use by another reader${slotState.activePid !== null ? ` (pid ${slotState.activePid} on the database)` : ""}: one slot has one reader. ` +
+                        `Stop the other Mason for this project (mason stop). A run that crashed holds it until its connection ends${slotState.activePid !== null ? `: SELECT pg_terminate_backend(${slotState.activePid}) ends it now` : ""}` }
+                : { name: "slot", ok: true, detail: `${slot} exists (${slotState.plugin ?? "?"}, ${slotState.walStatus ?? "?"}): Mason resumes from it` });
+    }
+    else {
+        out.push(free >= 1
+            ? { name: "slot", ok: true, detail: `${slot} is made at Mason's first start (${f.slotsUsed} of max_replication_slots ${f.maxSlots} in use)` }
+            : { name: "slot", ok: false, detail: `every replication slot is taken (${f.slotsUsed} of max_replication_slots ${f.maxSlots}): raise max_replication_slots (a restart), or drop a slot nobody reads` });
+    }
+    out.push(f.maxSenders - f.sendersUsed >= 1
+        ? { name: "wal senders", ok: true, detail: `${f.sendersUsed} of max_wal_senders ${f.maxSenders} in use` }
+        : { name: "wal senders", ok: false, detail: `every WAL sender is in use (${f.sendersUsed} of max_wal_senders ${f.maxSenders}): raise max_wal_senders (a restart)` });
+    const gb = suggestedWalCapGb(f.walBytesPerSecond);
+    const size = gb === null ? "a day of this database's WAL" : `${gb}GB`;
+    const basis = gb === null ? "" : ` (a day of the WAL this server writes: ${bytesText(f.walBytesPerSecond)}/s since its statistics were reset)`;
+    out.push(f.slotWalKeepMb >= 0
+        ? { name: "WAL cap", ok: true, detail: `max_slot_wal_keep_size = ${f.slotWalKeepMb >= 1024 ? `${(f.slotWalKeepMb / 1024).toFixed(f.slotWalKeepMb % 1024 ? 1 : 0)}GB` : `${f.slotWalKeepMb}MB`}: past it Postgres drops the slot rather than fill its disk, and Mason rebuilds from scratch${gb !== null && f.slotWalKeepMb < gb * 1024 ? `. A day of this server's WAL is about ${gb}GB${basis}: an outage longer than the cap's worth means a rebuild` : ""}` }
+        : { name: "WAL cap", ok: false,
+            detail: `max_slot_wal_keep_size is unlimited: while Mason is stopped its slot holds every byte of WAL, until the disk fills and Postgres stops taking writes. Cap it at the outage you want Mason to survive, e.g. ${size}${basis}` +
+                (f.rds || f.cloudSql ? ` — in the ${f.rds ? "DB parameter group" : "database flags"} (max_slot_wal_keep_size, in MB)` : ""),
+            ...(f.rds || f.cloudSql ? {} : { sql: `ALTER SYSTEM SET max_slot_wal_keep_size = '${gb ?? 4}GB';\nSELECT pg_reload_conf();` }) });
+    return out;
+}
+/** What polling costs this database: a scan of every replicated table at each poll, and the delete check's keys. */