@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/cli/registry.js

@@ -0,0 +1,220 @@
+/**
+ * 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 { MCP, mcp } from "./mcp.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"], changes: v.replication ? "replication" : v.poll ? "poll" : null });
+    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 }, { ...MCP, run: mcp }]],
+    ["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 init demo", "or try it on a demo database Mason makes itself: nothing to install"],
+            ["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), " +
+            `add tables (mason add, before or after the start), start Mason (mason start), 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 and mcp (whose stdout is the MCP protocol's) takes --json: one JSON object for a program, always with next (what to run " +
+            "next); a failure is { error: { code, message, why, fix }, next }. The exit code says how it went: 0 done, 1 failed " +
+            "with the reason, 2 a wrong command line, 124 mason wait timed out. Driving Mason from a coding agent: mason help agent."),
+        "",
+    ].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. */

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

@@ -0,0 +1,148 @@
+/**
+ * `mason start --replication` (the journey to production, item 6): a project's run reading its database's
+ * change log as production does — a publication, a replication slot, `wal_level = logical` — instead of polling it with
+ * SELECTs (src/cdc/poll.ts). A developer then meets the setup production needs on their own database first. The mode is
+ * the project's (`.mason/config.json` `changes`), kept between starts until `--poll` takes it back.
+ *
+ * What it costs the developer's database, said where it happens: Mason creates its slot there (`mason_<deployment>`), and
+ * a slot holds WAL while nobody reads it — so `mason stop` says so, and `mason destroy`, or going back to polling, drops
+ * it (`dropOwnReplication`), verified gone, by the name the start that made it RECORDED (`madeReplication`), never one
+ * computed again. The PUBLICATION is Mason's own (`mason_<deployment>`, made and dropped with
+ * the slot) unless the operator names one (`--publication <name>`, else `PG_PUBLICATION`, else the one
+ * an earlier start recorded): that one is the database owner's, read as it is and never created, altered or dropped
+ * (src/duck/publication.ts) — on a read replica it is the only way, since CREATE PUBLICATION is refused on a standby.
+ *
+ * In the ClickHouse service this was cut from, the two modes kept row versions that could not continue each other (a
+ * counter per table against WAL positions): a switch was a copy from scratch, which that service did by itself. The DuckDB
+ * prototype keeps its copies through a switch: each table is caught up by one poll from its watermark (src/duck/sync.ts
+ * `prepareReplication`), and `mason start` says so.
+ */
+import { createHash } from "node:crypto";
+import { replicationNames } from "../cdc/source.js";
+import { connectSource, systemIdentifier } from "./preflight.js";
+import { readServerFacts, readSlotFacts, replicationChecks } from "./replication-checks.js";
+/** Postgres's longest identifier (NAMEDATALEN - 1): a longer slot name is refused, a longer publication's cut with a notice. */
+export const PG_NAME_BYTES = 63;
+/**
+ * THE NAME A SOURCE'S SLOT AND PUBLICATION ARE MADE FROM, `dev_<project>_<source>` (src/cdc/source.ts replicationNames
+ * puts `mason_` before it): one per project AND source, the source the sources file's name, since a project will sync
+ * several databases, each with a slot of its own. Lower case, `_` for any other character, as a slot's name must be. A
+ * project (48 at most) and a source (48) can pass Postgres's 63 bytes: then a readable prefix and `_` and 8 hex
+ * characters of the whole name's sha256, so two names sharing a long prefix never meet and none is ever cut silently.
+ */
+export function deploymentOf(project, source) {
+    const full = `dev_${project}_${source}`.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+    const room = PG_NAME_BYTES - "mason_".length;
+    if (full.length <= room)
+        return full;
+    return `${full.slice(0, room - 9)}_${createHash("sha256").update(full).digest("hex").slice(0, 8)}`;
+}
+/**
+ * The publication and slot a project's run reads: the publication `named` (the flag, `PG_PUBLICATION` or the recorded
+ * one: `namedPublication`), else Mason's own — by the change reader's own rule (src/cdc/source.ts `replicationNames`),
+ * which also says whether it is Mason's to make. The slot is always the project's own.
+ */
+export function projectReplication(name, source, named = null) {
+    const { publication, slot, owned } = replicationNames(named ? { PG_PUBLICATION: named } : {}, deploymentOf(name, source));
+    return { publication, slot, owned };
+}
+/**
+ * WHAT REPLICATION MODE MADE ON THE DATABASE, as the start that made it recorded it (`config.json` `replication`): what
+ * `--poll` and `mason destroy` drop. Recorded, never computed again, so a name that changes since — the sources file
+ * renamed, the naming rule — never leaves a slot that nobody drops, holding the database's WAL for ever. A project with
+ * no record (none started in replication mode since it was kept) has the names the rule gives now.
+ */
+export function madeReplication(cfg, source) {
+    return cfg.replication ?? projectReplication(cfg.name, source, cfg.publication ?? null);
+}
+/** The publication an operator named, and where: `--publication`, else `PG_PUBLICATION`, else the one an earlier start
+ *  of this copy recorded (`config.json` `publication`), else none (Mason's own). */
+export function namedPublication(flag, env, recorded) {
+    if (flag)
+        return { name: flag, from: "flag" };
+    if (env.PG_PUBLICATION)
+        return { name: env.PG_PUBLICATION, from: "env" };
+    if (recorded)
+        return { name: recorded, from: "recorded" };
+    return null;
+}
+/** The mode a start runs: the flag, else the project's, else polling. */
+export function changesOf(flag, recorded) {
+    return flag ?? recorded ?? "poll";
+}
+/**
+ * Whether the developer's database can be read by replication: what refuses it (wal_level, the role — REPLICATION, a
+ * superuser, or RDS's rds_replication membership, as `replicationChecks` reads them — a free slot and WAL sender, a
+ * standby before 16, and a standby with no publication named: Mason cannot make its own there), and what is only worth
+ * saying (the WAL cap), from the production checks' own rules.
+ */
+export function readinessVerdict(facts, slot, slotFacts, repl) {
+    const checks = replicationChecks(facts, slot, slotFacts);
+    // a standby takes no CREATE PUBLICATION (it is read-only): the publication must be the primary's, named
+    if (facts.standby && repl.owned) {
+        checks.push({ name: "publication", ok: false, detail: `this database is a read replica, where Mason cannot make its publication ${repl.publication} (CREATE ` +
+                "PUBLICATION is refused on a standby). Create one on the primary for the tables you add, then name it: mason start --replication --publication <name>" });
+    }
+    // a laptop's database has no cap on its slots by default: worth saying, never a reason to refuse a dev run
+    return { refused: checks.filter((x) => x.ok === false && x.name !== "WAL cap"), warnings: checks.filter((x) => (x.name === "WAL cap" && x.ok === false) || x.warn === true) };
+}
+export async function replicationReadiness(source, repl) {
+    const c = await connectSource(source);
+    if ("failure" in c)
+        return { failure: c.failure.message };
+    try {
+        return readinessVerdict(await readServerFacts(c.pg), repl.slot, await readSlotFacts(c.pg, repl.slot), repl);
+    }
+    finally {
+        c.pg.close();
+    }
+}
+/** The statements that remove what replication mode made, for a person to run when Mason could not: the slot, and the
+ *  publication only when it is Mason's own (a named one is its owner's). */
+export function dropStatements(o) {
+    return `SELECT pg_drop_replication_slot('${o.slot}') FROM pg_replication_slots WHERE slot_name = '${o.slot}' AND NOT active;` +
+        (o.owned ? ` DROP PUBLICATION IF EXISTS ${o.publication};` : "");
+}
+/**
+ * Drop what replication mode made on the developer's database — the slot, and the publication when it is Mason's own,
+ * never one the operator named — and verify it is gone: what was dropped, in words. A slot a reader still holds is never
+ * dropped (the run must be stopped first): that is a failure.
+ */
+export async function dropOwnReplication(source, o, from = null) {
+    const c = await connectSource(source);
+    if ("failure" in c)
+        throw new Error(`could not connect to drop them: ${c.failure.message}`);
+    const pg = c.pg;
+    const lit = (s) => `'${s.replace(/'/g, "''")}'`;
+    try {
+        // the server the copy came from (its system identifier, recorded at the copy): another one has none of its slot
+        if (from?.systemIdentifier) {
+            const now = await systemIdentifier(pg);
+            if (now !== null && now !== from.systemIdentifier) {
+                throw new Error(`${source.database} on ${source.host} is another server than the copy came from (system identifier ${now}, the copy's ${from.systemIdentifier}), where the slot is: put that server's URL back in the sources file and run mason destroy again, or drop them there by hand`);
+            }
+        }
+        const dropped = [];
+        const slot = await readSlotFacts(pg, o.slot);
+        if (slot) {
+            if (slot.active)
+                throw new Error(`replication slot ${o.slot} is in use by a reader: stop it first`);
+            await pg.query(`SELECT pg_drop_replication_slot(${lit(o.slot)})`);
+            dropped.push(`replication slot ${o.slot}`);
+        }
+        const hasPub = async () => (await pg.query(`SELECT 1 FROM pg_publication WHERE pubname = ${lit(o.publication)}`)).rows.length > 0;
+        if (o.owned && await hasPub()) {
+            await pg.query(`DROP PUBLICATION IF EXISTS "${o.publication.replace(/"/g, '""')}"`);
+            dropped.push(`publication ${o.publication}`);
+        }
+        // verified, never assumed: a slot left behind holds the database's WAL for ever
+        if (await readSlotFacts(pg, o.slot))
+            throw new Error(`replication slot ${o.slot} is still there after pg_drop_replication_slot`);
+        if (o.owned && await hasPub())
+            throw new Error(`publication ${o.publication} is still there after DROP PUBLICATION`);
+        return dropped;
+    }
+    finally {
+        pg.close();
+    }
+}