@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/cdc/pgoutput.js

@@ -0,0 +1,107 @@
+/**
+ * THE `pgoutput` DECODER (protocol version 1): Postgres's built-in logical decoding output, the messages
+ * inside the replication stream's XLogData. Pure — a Buffer in, a message out — so every message shape is
+ * pinned by tests/cdc-pgoutput.test.ts against bytes built by hand from the protocol reference (Postgres's own documentation):
+ * https://www.postgresql.org/docs/current/protocol-logicalrep-message-formats.html
+ *
+ * Version 1 is enough: no streamed in-progress transactions (the server hands a transaction over only at
+ * its commit, which is what makes "acknowledge only complete transactions" simple), no two-phase commit.
+ */
+class Cursor {
+    b;
+    i = 0;
+    constructor(b) { this.b = b; }
+    byte() { return String.fromCharCode(this.b[this.i++]); }
+    int8() { return this.b.readInt8(this.i++); }
+    int16() { const v = this.b.readInt16BE(this.i); this.i += 2; return v; }
+    int32() { const v = this.b.readInt32BE(this.i); this.i += 4; return v; }
+    uint32() { const v = this.b.readUInt32BE(this.i); this.i += 4; return v; }
+    int64() { const v = this.b.readBigUInt64BE(this.i); this.i += 8; return v; }
+    cstr() {
+        const end = this.b.indexOf(0, this.i);
+        if (end < 0)
+            throw new Error("pgoutput: unterminated string");
+        const s = this.b.toString("utf8", this.i, end);
+        this.i = end + 1;
+        return s;
+    }
+    bytes(n) { const v = this.b.subarray(this.i, this.i + n); this.i += n; return v; }
+}
+function tuple(c) {
+    const n = c.int16();
+    const out = [];
+    for (let k = 0; k < n; k++) {
+        const kind = c.byte();
+        if (kind === "n")
+            out.push({ kind: "null" });
+        else if (kind === "u")
+            out.push({ kind: "unchanged" });
+        else if (kind === "t") {
+            const len = c.int32();
+            out.push({ kind: "text", text: c.bytes(len).toString("utf8") });
+        }
+        else if (kind === "b")
+            throw new Error("pgoutput: a binary column value arrived, but the reader asks for text");
+        else
+            throw new Error(`pgoutput: unknown tuple column kind ${JSON.stringify(kind)}`);
+    }
+    return out;
+}
+export function decode(data) {
+    const c = new Cursor(data);
+    const tag = c.byte();
+    switch (tag) {
+        case "B": return { type: "begin", finalLsn: c.int64(), commitTime: c.int64(), xid: c.int32() };
+        case "C": {
+            c.int8();
+            return { type: "commit", commitLsn: c.int64(), endLsn: c.int64(), commitTime: c.int64() };
+        }
+        case "R": {
+            const relid = c.uint32(), namespace = c.cstr(), name = c.cstr(), replicaIdentity = c.byte();
+            const n = c.int16();
+            const columns = [];
+            for (let k = 0; k < n; k++) {
+                const flags = c.int8();
+                columns.push({ isKey: (flags & 1) === 1, name: c.cstr(), typeOid: c.uint32(), typmod: c.int32() });
+            }
+            return { type: "relation", relid, namespace, name, replicaIdentity, columns };
+        }
+        case "I": {
+            const relid = c.uint32();
+            expect(c.byte(), "N", "insert");
+            return { type: "insert", relid, tuple: tuple(c) };
+        }
+        case "U": {
+            const relid = c.uint32();
+            let marker = c.byte();
+            let oldKey = null;
+            if (marker === "K" || marker === "O") {
+                oldKey = tuple(c);
+                marker = c.byte();
+            }
+            expect(marker, "N", "update");
+            return { type: "update", relid, oldKey, tuple: tuple(c) };
+        }
+        case "D": {
+            const relid = c.uint32();
+            const marker = c.byte();
+            if (marker !== "K" && marker !== "O")
+                throw new Error(`pgoutput: delete carries ${marker}, expected K or O`);
+            return { type: "delete", relid, key: tuple(c) };
+        }
+        case "T": {
+            const n = c.int32();
+            c.int8(); // options: CASCADE / RESTART IDENTITY
+            const relids = [];
+            for (let k = 0; k < n; k++)
+                relids.push(c.uint32());
+            return { type: "truncate", relids };
+        }
+        // Origin, Type and logical decoding messages carry nothing the reader stores
+        default: return { type: "other", tag };
+    }
+}
+function expect(got, want, what) {
+    if (got !== want)
+        throw new Error(`pgoutput: ${what} carries ${JSON.stringify(got)} where ${want} was expected`);
+}

package/dist/src/cdc/poll.js

@@ -0,0 +1,67 @@
+/**
+ * THE POLL'S SQL (so that development can read a local database without WAL): the
+ * xmin poll `mason start` keeps a copy current with by default (src/duck/sync.ts), with plain SELECTs — no
+ * `wal_level=logical`, no replication slot, no publication, no REPLICATION attribute, nothing created or changed on
+ * the source. Each poll reads, in one snapshot, every row whose `xmin` (the transaction that wrote this version of it)
+ * is at or past the WATERMARK — the oldest transaction still running at the last poll (`pg_snapshot_xmin`):
+ * everything that committed before it was read by an earlier poll (or the copy); a transaction that was running then
+ * has an id at or past it, and so has every subtransaction of it (a savepoint's rows carry the SUBtransaction's id,
+ * which `pg_visible_in_snapshot` would misjudge, so the bound is a range, never a visibility test). A copy taken in
+ * several source transactions is held to its first snapshot by the complement (`xminBeforeSql`).
+ *
+ * WHAT IT COSTS THE SOURCE: a poll reads every polled table whole (no index covers `xmin`), so the interval stretches
+ * to four times what the last poll took (`nextPollDelayMs`).
+ */
+/** The snapshot's `xmin` — the oldest transaction running when it was taken — from its text (`xmin:xmax:xip,…`). */
+export function snapshotXmin(snapshot) {
+    const m = /^(\d+):(\d+):/.exec(snapshot);
+    if (!m)
+        throw new Error(`not a pg_snapshot: ${JSON.stringify(snapshot)}`);
+    return BigInt(m[1]);
+}
+/** The poll's snapshot, its xmin and xmax (64-bit transaction ids, Postgres 13+), read as the transaction's first statement. */
+export const SNAPSHOT_SQL = "SELECT pg_current_snapshot()::text, pg_snapshot_xmax(pg_current_snapshot())::text";
+/**
+ * A row's `xmin` as a 64-bit transaction id. `xmin` is the 32-bit id; its epoch is the current one, or the one
+ * before when its low bits are past the current id's (it was assigned before the counter last wrapped). A row older
+ * than one wrap (2^31 transactions) is frozen long since and reads as old either way: it is never at the watermark.
+ */
+export function xmin8Sql(currentXid8) {
+    const epoch = currentXid8 >> 32n, low = currentXid8 & 0xffffffffn;
+    return `((${epoch}::bigint - (xmin::text::bigint > ${low})::int) << 32 | xmin::text::bigint)`;
+}
+/**
+ * A ROW WRITTEN BEFORE THE WATERMARK: the complement of `xmin8Sql(…) >= watermark` (the poll's "changed since"), for a
+ * copy taken in several source transactions that is held to its FIRST snapshot (src/duck/sync.ts `copy`): every
+ * transaction that commits after a snapshot has an id at or past its xmin (it was running then, or began later), and a
+ * tuple's xmin never changes, so a read in any later snapshot that keeps only these rows keeps none written after the
+ * first — and the catch-up poll from that watermark reads every row this leaves out.
+ *
+ * Written with `age()`, never `xmin::text::bigint` (measured on PG 18 over 3 M rows: the text casts took a
+ * scan from 320 to 1,640 ms of the source's CPU, `age` to 437): `age(x)` is the 32-bit distance from the transaction's
+ * stable latest id L (the next id, read once per transaction) to `x`, so for every row within 2^31 transactions of L,
+ * `age(xmin) > age(watermark)` is exactly "older than the watermark" — while L is within 2^31 of the watermark, which
+ * `xminBeforeHolds` checks. A row whose `age` is negative has a raw xmin more than 2^31 transactions old (frozen: a
+ * freeze keeps the raw id since 9.4), which `xmin8Sql` may place at or past a watermark: it is kept here AND read again by
+ * the catch-up (written by key, so once), never neither. `age` of a special id (frozen, bootstrap) is INT_MAX: kept.
+ * Normal ids never have low bits below 3 (FirstNormalTransactionId), so a watermark's below 3 reads as 3: the same rows.
+ */
+export function xminBeforeSql(watermark) {
+    const low = watermark & 0xffffffffn;
+    return `(age(xmin) > (SELECT age('${low < 3n ? 3n : low}'::xid)) OR age(xmin) < 0)`;
+}
+/** `xminBeforeSql` is exact while the transaction's latest id is within 2^31 of the watermark: held to a margin of half
+ *  that (a billion transactions), `current` being the reading transaction's snapshot xmax (`SNAPSHOT_SQL`) */
+export function xminBeforeHolds(current, watermark) {
+    return current >= watermark && current - watermark < 2n ** 30n;
+}
+/**
+ * The wait before the next poll: MASON_POLL_MS, or four times what the last poll took when that is longer, so a
+ * source whose tables take a while to read spends at most a fifth of its time on polls. Never sooner than either
+ * (the test server: a cap of a minute polled a 22 M-row production table every 74 s for 6.5 hours under
+ * MASON_POLL_MS=3600000, and a poll of 20 s every 60 s is a third of the source's time): the database's load decides,
+ * and a slow poll's freshness is said by its own timing line.
+ */
+export function nextPollDelayMs(pollMs, lastPollMs) {
+    return Math.max(pollMs, 4 * lastPollMs);
+}

package/dist/src/cdc/source.js

@@ -0,0 +1,65 @@
+/**
+ * THE REPLICATION SLOT, and the names a run replicates through (src/duck/sync.ts, src/cli/replication-mode.ts). The
+ * slot is the one object Mason creates on the source (its user needs the REPLICATION attribute); a publication is read,
+ * never created there, unless it is Mason's own (src/duck/publication.ts; CLAUDE.md "We are read-only on a customer's
+ * Postgres").
+ */
+import { PgConnection, parseLsn, pgIdent, pgLiteral } from "./pg-wire.js";
+import { parsePort } from "../lib/port.js";
+/**
+ * The publication and slot a project replicates through: `PG_PUBLICATION` / `PG_SLOT_NAME`, else Mason's own
+ * `mason_<name>`. A publication of Mason's own name is one Mason may create; any other is the database owner's and is
+ * only ever read.
+ */
+export function replicationNames(env, deployment) {
+    const own = `mason_${deployment.replace(/[^A-Za-z0-9_]/g, "_")}`;
+    const publication = env.PG_PUBLICATION || own;
+    return { publication, slot: env.PG_SLOT_NAME || own, owned: publication === own };
+}
+/** The connection options from the `PG_*` environment (DATABASE_URL already laid under it). */
+export function pgOptions(env, replication = false) {
+    const need = (k) => {
+        const v = env[k];
+        if (!v)
+            throw new Error(`${k} is not set (DATABASE_URL, or the PG_* variables)`);
+        return v;
+    };
+    const port = parsePort("PG_PORT", env.PG_PORT, 5432);
+    if (port.problem !== undefined)
+        throw new Error(port.problem);
+    return {
+        host: need("PG_HOST"), port: port.port, database: need("PG_DATABASE"), user: need("PG_USER"),
+        password: env.PG_PASSWORD ?? "", sslmode: (env.PG_SSLMODE || "prefer"),
+        replication, applicationName: replication ? "mason-cdc" : "mason",
+    };
+}
+const NO_SLOT = { exists: false, active: false, activePid: null, plugin: null, database: null, confirmedFlush: null,
+    walStatus: null, retainedBytes: null, safeBytes: null };
+export async function readSlot(pg, slot) {
+    const r = await pg.query(`SELECT plugin, database, active, active_pid::text, confirmed_flush_lsn::text, wal_status, safe_wal_size::text, ` +
+        `pg_wal_lsn_diff((CASE WHEN pg_is_in_recovery() THEN pg_last_wal_replay_lsn() ELSE pg_current_wal_lsn() END), restart_lsn)::text ` +
+        `FROM pg_replication_slots WHERE slot_name = ${pgLiteral(slot)}`);
+    const row = r.rows[0];
+    if (!row)
+        return NO_SLOT;
+    const big = (v) => (v === null || v === undefined || v === "" ? null : BigInt(v.split(".")[0]));
+    return { exists: true, plugin: row[0], database: row[1], active: row[2] === "t", activePid: row[3] ?? null, confirmedFlush: row[4] ?? null,
+        walStatus: row[5] ?? null, safeBytes: big(row[6]), retainedBytes: big(row[7]) };
+}
+/** Drop the slot (it must not be active). */
+export async function dropSlot(pg, slot) {
+    await pg.query(`SELECT pg_drop_replication_slot(${pgLiteral(slot)})`);
+}
+/** Where the source's WAL is now: the insert position on a primary, the replayed position on a standby (a
+ *  logical slot on a standby decodes only what it has replayed). */
+export async function currentLsn(pg) {
+    const r = await pg.query("SELECT (CASE WHEN pg_is_in_recovery() THEN pg_last_wal_replay_lsn() ELSE pg_current_wal_lsn() END)::text");
+    return parseLsn(r.rows[0]?.[0] ?? "");
+}
+/** Create the slot over a replication connection; returns the WAL position it starts at. */
+export async function createSlot(repl, slot) {
+    // NOEXPORT_SNAPSHOT: the first copy reads each table by key pages, each its own statement (the stream's
+    // versions win wherever they overlap) — no long snapshot to hold open.
+    const r = await repl.query(`CREATE_REPLICATION_SLOT ${pgIdent(slot)} LOGICAL pgoutput NOEXPORT_SNAPSHOT`);
+    return r.rows[0]?.[1] ?? "";
+}

package/dist/src/cli/background.js

@@ -0,0 +1,198 @@
+/**
+ * `mason start` IN THE BACKGROUND (an interface as good for people as for coding agents).
+ * The run is a process of its own (`mason start … --attach`, detached, its terminal the file `dev.log` in the run's
+ * folder): this shows the run's start as it happens, and returns once the run says it is ready — or with the run's own
+ * exit code when it stops first (a wrong password), its reason already shown. A coding agent's shell can
+ * then go on (`mason tables`, `mason add`, `mason wait`), and a person's terminal is theirs again.
+ *
+ * A second `mason start` for a project whose run is up does not start another: it says so and returns 0, so running it
+ * again is always safe.
+ *
+ * What is detached is the run's SUPERVISOR (src/cli/supervise.ts), which starts the run and starts it again if it dies
+ * once it was ready; a start that fails ends the supervisor with the run's own exit code, so this reads it as before.
+ */
+import { choosePgPort } from "./ports.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { runnable } from "../lib/runnable.js";
+import { READY, STEP_MARK } from "./dev.js";
+import { liveRun } from "./runs.js";
+import { projectSource, theProject } from "./project.js";
+import { runListenerSettings } from "./pg-tls.js";
+import { demoChangesRefusal, demoPort } from "./demo.js";
+import { endText, failed, jsonText, nextBlock } from "./command.js";
+import { DEV } from "./registry.js";
+import { out as styleOut, stepRenderer } from "./style.js";
+import { postgresLink, withoutPlaceholders } from "./pg-url.js";
+const say = (m) => { process.stdout.write(`${m}\n`); };
+const MAIN = path.join(path.dirname(fileURLToPath(import.meta.url)), "main.ts");
+const SUPERVISE = path.join(path.dirname(fileURLToPath(import.meta.url)), "supervise.ts");
+/** The commands to run next, as `mason start` prints them once the run is up: one a line, what each does beside it
+ *  (not `mason status | mason logs | mason stop` on one line). */
+export const NEXT_STEPS = [
+    ["mason tables", "the database's tables, and what you can add"],
+    ["mason add <table>", "copy a table into Mason"],
+    ["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"],
+    ["mason status", "what Mason is doing"],
+    ["mason logs", "its log: every copy, poll and statement"],
+    ["mason stop", "stop Mason; the next mason start resumes where it stopped"],
+];
+/** The ports a demo project's database takes (its URL's port, read as the run reads it), for the API's choice to avoid;
+ *  none for any other project. A sources file or a URL that cannot be read gives none HERE: the run refuses it in its
+ *  own words (its source step, its demo step), shown by this start as every other refusal of the run's is. */
+function demoPortsOf(project) {
+    if (project.config.demo !== true)
+        return new Set();
+    const src = projectSource(project, process.env);
+    if ("message" in src)
+        return new Set();
+    const at = demoPort(src.resolved, src.from);
+    return new Set("port" in at ? [at.port] : []);
+}
+/** `args` are `mason start`'s own, passed on to the run with --attach. */
+export async function devInBackground(args, o) {
+    const t = theProject(process.cwd());
+    if ("problem" in t)
+        return failed("start", t, { json: o.json });
+    const home = t.project.dir;
+    const other = await liveRun(t.project);
+    if (other !== null) {
+        // running already is what start wants: said, exit 0, the same answer as a start (what is up, and what to run)
+        if (o.json) {
+            say(jsonText(DEV, { running: true, pid: other.pid, postgres: postgresLink(other.postgresUrl) }, [["mason status", "what it is doing"], ["mason stop", "stop it"]]));
+            return 0;
+        }
+        say(`Mason is already running for ${t.project.config.name} (pid ${other.pid}).`);
+        say(nextBlock([["mason status", "what it is doing"], ["mason stop", "stop it"]]));
+        return 0;
+    }
+    // a demo project with --replication (src/cli/demo.ts): refused here too, where it is read, before a run is spawned
+    const demoRefused = demoChangesRefusal(t.project.config, o.changes ?? null);
+    if (demoRefused)
+        return failed("start", demoRefused, { json: o.json });
+    // a MASON_PG_PORT that is no port, or is held, is refused HERE, where the person (or --json) reads it, before a run is
+    // spawned; the run checks again for itself (choosePgPort, src/cli/ports.ts), since a port may be taken in between.
+    // A demo project's database port (its URL's, src/cli/demo.ts demoPort) is avoided as the run avoids it
+    const pg = await choosePgPort(process.env.MASON_PG_PORT, demoPortsOf(t.project), t.project.config.pgPort ?? null);
+    if ("problem" in pg)
+        return failed("start", pg, { json: o.json });
+    // and so is a listener off loopback without TLS, by the run's own check (src/cli/pg-tls.ts): read, never written
+    const listen = runListenerSettings(process.env, { port: pg.port, selfSigned: o.selfSignedTls, home });
+    if ("problem" in listen)
+        return failed("start", listen, { json: o.json });
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    // the run's terminal: its setup URL carries the run's token and it prints the API key, so only the developer reads it
+    const logFile = path.join(home, "dev.log");
+    const fd = fs.openSync(logFile, "a", 0o600);
+    fs.chmodSync(logFile, 0o600);
+    const from = fs.fstatSync(fd).size;
+    fs.writeSync(fd, `\n--- mason start ${new Date().toISOString()} ---\n`);
+    // the run is started IN the project's root, so it finds the same project
+    const run = [process.execPath, runnable(MAIN), "start", ...args.filter((a) => a !== "--json"), "--attach"];
+    const child = spawn(process.execPath, [runnable(SUPERVISE), home, logFile, ...run], { detached: true, stdio: ["ignore", fd, fd], cwd: t.project.root, env: process.env });
+    fs.closeSync(fd);
+    let exited = null;
+    child.on("exit", (code, signal) => { exited = code ?? (signal ? 1 : 0); });
+    // Ctrl-C while it starts stops the start too: nothing is left running that nobody asked for
+    const abort = () => { child.kill("SIGTERM"); };
+    process.on("SIGINT", abort);
+    // what it does, as a checklist (as `mason init` draws its own): the run's steps, drawn as they happen; under
+    // --json nothing until it is up (one document), the lines after the last step kept as a failure's why
+    const st = styleOut();
+    const line = (x) => { if (!o.json)
+        say(x); };
+    line(st.bold(`Starting Mason for ${t.project.config.name}`));
+    const steps = stepRenderer({ line, live: !o.json && process.stdout.isTTY ? { write: (x) => { process.stdout.write(x); } } : null, style: st });
+    let begun = false;
+    let offset = from;
+    let partial = "";
+    let postgres = null;
+    const since = []; // the run's lines after its last step: a failure's reasons
+    try {
+        for (;;) {
+            const size = fs.statSync(logFile).size;
+            if (size > offset) {
+                const buf = Buffer.alloc(size - offset);
+                const r = fs.openSync(logFile, "r");
+                try {
+                    fs.readSync(r, buf, 0, buf.length, offset);
+                }
+                finally {
+                    fs.closeSync(r);
+                }
+                offset = size;
+                const lines = (partial + buf.toString()).split("\n");
+                partial = lines.pop() ?? "";
+                for (const l of lines) {
+                    if (l.startsWith("--- mason start "))
+                        continue;
+                    if (l === "" && steps.open() === null && !begun)
+                        continue; // the log's spacing before the first step
+                    begun = true;
+                    if (l === READY) {
+                        child.unref();
+                        const next = NEXT_STEPS;
+                        // the run's pid, as it recorded it (the child is its supervisor), the one mason stop signals
+                        const pid = JSON.parse(fs.readFileSync(path.join(home, "config.json"), "utf8")).running?.pid ?? null;
+                        if (o.json)
+                            say(jsonText(DEV, { running: true, pid, postgres }, next));
+                        else
+                            say(endText({ next }, st));
+                        return 0;
+                    }
+                    // the run's steps (src/cli/dev.ts STEP_MARK) as a checklist; any other line as it came
+                    if (l.startsWith(STEP_MARK.begin)) {
+                        since.length = 0;
+                        steps.begin(l.slice(STEP_MARK.begin.length));
+                        continue;
+                    }
+                    if (l.startsWith(STEP_MARK.done)) {
+                        since.length = 0;
+                        steps.done(l.slice(STEP_MARK.done.length));
+                        continue;
+                    }
+                    if (l.startsWith(STEP_MARK.fail)) {
+                        since.length = 0;
+                        steps.fail(l.slice(STEP_MARK.fail.length));
+                        continue;
+                    }
+                    // the run's line (src/cli/dev.ts: "Postgres  <url>", the URL in its shown form, `withPlaceholders`: postgres://<user>:<password>@…)
+                    const pgLine = /^\s+Postgres\s+(postgres:\/\/<user>:<password>@\S+)/.exec(l);
+                    if (pgLine) {
+                        postgres = postgresLink(withoutPlaceholders(pgLine[1]));
+                        steps.print(`  ${st.dim("Postgres API")}  ${pgLine[1]}  ${st.dim("(mason user add <name> makes a user)")}`);
+                        continue;
+                    }
+                    if (/^\s+Web UI\s+mason ui\b/.test(l)) {
+                        steps.print(`  ${st.dim("Web UI".padEnd("Postgres API".length))}  ${st.cyan("mason ui")}  ${st.dim("(the status page and the users, in your browser)")}`);
+                        continue;
+                    }
+                    // a demo project's line (src/cli/dev.ts: "Demo  a new order lands every <n> s: …"), in the same column
+                    const demoLine = /^\s+Demo\s{2}(.+)$/.exec(l);
+                    if (demoLine) {
+                        steps.print(`  ${st.dim("Demo".padEnd("Postgres API".length))}  ${demoLine[1]}`);
+                        continue;
+                    }
+                    if (l.trim())
+                        since.push(l.trim().replace(/^mason start: /, ""));
+                    steps.print(l);
+                }
+            }
+            if (exited !== null) {
+                if (steps.open() !== null)
+                    steps.fail();
+                if (partial)
+                    since.push(partial.trim());
+                // the run's own last words are the reason (a wrong password), already shown line by line to a person
+                return failed("start", { message: `the run stopped before it was ready (exit ${exited})`, code: "failed", why: o.json && since.length ? since.join("\n") : undefined,
+                    fix: `the whole log: ${logFile}`, exit: exited === 0 ? 1 : exited }, { json: o.json });
+            }
+            await new Promise((r) => setTimeout(r, 150));
+        }
+    }
+    finally {
+        process.off("SIGINT", abort);
+    }
+}

package/dist/src/cli/command.js

@@ -0,0 +1,173 @@
+/**
+ * A `mason` COMMAND, DESCRIBED ONCE (every command, present and future, is and stays self-documenting, and that is
+ * checked). Each command is a `CommandSpec`: its name, the one line `mason --help` lists it with, its usage
+ * (what `mason <name> --help` prints), and the options its parser accepts — the SAME object the parser reads, so an
+ * option cannot exist without its spec. src/cli/main.ts builds the command table and the top-level help from the
+ * specs, and tests/cli-help.test.ts holds every one to the rules below, a command added later included:
+ *
+ *   - `mason <name> --help` and `mason help <name>` print its usage and exit 0;
+ *   - the usage starts `usage: mason <name>`, and shows at least one example (an indented `mason <name> …` line);
+ *   - every option the parser takes is in the usage, by its `--name` (and `-x` when it has one);
+ *   - `mason --help` lists it with its summary;
+ *   - a wrong option prints what is wrong, then the usage, and exits 2.
+ */
+import { parseArgs } from "node:util";
+import { err as styleErr, out as styleOut, PLAIN, wrap } from "./style.js";
+const HELP = { help: { type: "boolean", short: "h" } };
+/**
+ * A command line read by its spec: the values and positionals; or the exit code when it answered itself — 0 after
+ * printing the usage for `--help`, 2 after saying what is wrong with the line, then the usage.
+ */
+export function parseCommand(spec, argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options: { ...spec.options, ...HELP }, allowPositionals: true });
+    }
+    catch (e) {
+        return failed(spec.name, { message: e.message, code: "usage", usage: spec.usage, next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json: wantsJson(argv, spec) });
+    }
+    if (parsed.values.help) {
+        process.stdout.write(spec.usage);
+        return 0;
+    }
+    return { values: parsed.values, positionals: parsed.positionals };
+}
+/** The column a step's `what` starts in, after the two-space indent: wide enough for `mason add orders --columns …`. */
+const NEXT_WIDTH = 44;
+/**
+ * WHAT TO RUN NEXT, in one shape for every command (some commands showed Next as one line, some without the Next
+ * prefix and some as a kind of table; the table won): a blank line, `Next:`, then each command with what
+ * it does in a column, after everything else a command prints — a failure's way out included (failureText). With --json the
+ * same steps are the answer's `next` (nextJson). tests/conventions.test.ts refuses a `Next` or `Try` written any other way.
+ */
+export function nextBlock(steps, s = styleOut()) {
+    // on a terminal: `Next:` bold, each command cyan, what it does dim and wrapped under its own column (src/cli/style.ts)
+    const step = ([command, what]) => {
+        if (!what)
+            return `  ${s.cyan(command)}`;
+        const used = 2 + Math.max(command.length, NEXT_WIDTH) + 2;
+        return `  ${s.cyan(command.padEnd(NEXT_WIDTH))}  ${s.dim(wrap(what, s.width, 2 + NEXT_WIDTH + 2, used))}`;
+    };
+    return ["", s.bold("Next:"), ...steps.map(step)].join("\n");
+}
+export function reportText(r, s = styleOut()) {
+    const lines = [s.bold(r.headline)];
+    const w = Math.max(0, ...(r.details ?? []).map(([label]) => label.length));
+    for (const [label, value] of r.details ?? [])
+        lines.push(`  ${s.dim(label.padEnd(w))}   ${wrap(value, s.width, 2 + w + 3)}`);
+    return withEnd(lines.join("\n"), r, s);
+}
+/**
+ * The end of a command's output, to print on its own (out(endText(…))): its tips, then what to run next, each part after
+ * a blank line; "" when it has neither. withEnd puts it after text a command has not printed yet.
+ */
+export function endText(r, s = styleOut()) {
+    const tips = r.tips?.length ? `\n${r.tips.map((t) => s.dim(`Tip: ${wrap(t, s.width, 5)}`)).join("\n")}` : "";
+    const next = r.next?.length ? nextBlock(r.next, s) : "";
+    return tips && next ? `${tips}\n${next}` : tips || next;
+}
+export function withEnd(text, r, s = styleOut()) {
+    const end = endText(r, s);
+    return end ? `${text}\n${end}` : text;
+}
+export const STDIO = { out: (m) => { process.stdout.write(`${m}\n`); }, err: (m) => { process.stderr.write(`${m}\n`); } };
+/** The steps as a program reads them: `[{ command, what }]`, the same list the human output prints under Next. */
+export function nextJson(steps = []) {
+    return steps.map(([command, what]) => what ? { command, what } : { command });
+}
+/** Whether a command line asked for data: `--json` anywhere on it (read before the line is parsed, so a wrong line
+ *  is answered in JSON too) — never for a command whose stdout is a protocol's (`CommandSpec.stdout`), whose every
+ *  failure is said on stderr. */
+export const wantsJson = (argv, spec) => spec?.stdout !== "protocol" && argv.includes("--json");
+/**
+ * A COMMAND'S --json ANSWER (an agent wants clear, unambiguous context and a machine-readable format, and a person
+ * and an agent both want the next steps): one JSON object on stdout, always with `next` — the same steps the human
+ * output prints — and only the keys the command's spec declares (`CommandSpec.json`), so the help's shape and the answer
+ * cannot drift: a key the spec does not name is a bug here, said as one. A list is wrapped in an object for the same
+ * reason (`{ tables: […], next }`), never printed bare.
+ */
+export function jsonText(spec, value, next = []) {
+    const declared = spec.json;
+    if (declared === undefined)
+        throw new Error(`mason ${spec.name} prints JSON, and its spec declares no json keys (src/cli/command.ts CommandSpec.json)`);
+    const stray = Object.keys(value).filter((k) => !declared.includes(k));
+    if (stray.length)
+        throw new Error(`mason ${spec.name} --json: ${stray.join(", ")} ${stray.length === 1 ? "is" : "are"} not in its spec's json keys (${declared.join(", ")}): add ${stray.length === 1 ? "it" : "them"} there and to its usage`);
+    if (!declared.includes("next"))
+        throw new Error(`mason ${spec.name}: its json keys must end with next (every --json answer carries what to run next)`);
+    return JSON.stringify({ ...value, next: nextJson(next) }, null, 2);
+}
+/**
+ * THE CODES A FAILURE CARRIES, a closed set a program can branch on (`mason help agent` lists them).
+ */
+export const FAILURE_CODES = {
+    usage: "the command line is wrong: a flag, an argument, a value (exit 2; the usage follows for a person)",
+    no_project: "no Mason project here or above (mason init makes one)",
+    bad_config: "this folder is a Mason project whose .mason/config.json cannot be read: repair it, or move .mason/ aside and mason init",
+    bad_source: "the project's sources file (mason/sources/<name>.yml) is missing or names something wrong: the file, the key and the way out are said",
+    not_running: "Mason is not running for the project (mason start)",
+    unreachable: "Mason is running but does not answer (mason logs says why)",
+    not_found: "a name nothing has: a table, a column, a user",
+    nothing_yet: "nothing to work on yet: no table added (the next steps say what adds one)",
+    refused: "Mason refused what was asked, with the reason",
+    failed: "the command tried and could not finish: the reason, and what to do",
+    timeout: "ran out of time — mason wait; nothing stopped (exit 124)",
+};
+/** A failure thrown from deep in a command, for main.ts to print: the one way a failure leaves a command without a return code. */
+export class CommandFailed extends Error {
+    failure;
+    constructor(f) { const n = asFailure(f); super(n.message); this.failure = n; }
+}
+export const asFailure = (f) => "problem" in f ? { ...f, message: f.problem } : f;
+/** The failure as a person reads it (above): a red ✘ (wherever a step fails, as a green tick shows wherever one
+ *  succeeds — the checklist's own mark, ✗ where nothing is styled), the command's name and the
+ *  message in bold, then why and fix as rows, then Next, then a wrong line's usage. */
+export function failureText(cmd, f, s = styleErr()) {
+    const head = cmd ? `mason ${cmd}:` : "mason:";
+    // the checklist's marks: ✘ on a terminal (beside its ✔), ✗ in plain text (beside its ✓); a style that colours is one
+    const mark = s.red("x") === "x" ? "✗" : "✘";
+    const lines = [`${s.red(mark)} ${s.red(head)} ${s.bold(wrap(f.message, s.width, 2, mark.length + 1 + head.length + 1))}`];
+    const rows = [...(f.why ? [["why", f.why]] : []), ...(f.fix ? [["fix", f.fix]] : [])];
+    // a value of several lines (a list of failures, an entry to paste) keeps its lines, each under the first
+    for (const [label, value] of rows)
+        lines.push(`  ${s.dim(label)}   ${value.split("\n").map((l, i) => i ? `${" ".repeat(8)}${wrap(l, s.width, 8)}` : wrap(l, s.width, 8)).join("\n")}`);
+    let text = lines.join("\n");
+    if (f.next?.length)
+        text += `\n${nextBlock(f.next, s)}`;
+    if (f.usage)
+        text += `\n\n${f.usage.replace(/\n$/, "")}`;
+    return text;
+}
+/** A failure's `error` as --json carries it: on its own (failureJson), or beside a command's own keys when it did part of
+ *  its work (mason add: the tables added; mason wait: the tables' state). */
+export function errorJson(f) {
+    return { code: f.code, message: f.message, ...(f.why ? { why: f.why } : {}), ...(f.fix ? { fix: f.fix } : {}) };
+}
+/** The failure as a program reads it: `{"error": {code, message, why?, fix?}, "next": […]}`. */
+export function failureJson(f) {
+    return JSON.stringify({ error: errorJson(f), next: nextJson(f.next) }, null, 2);
+}
+/**
+ * SAY A FAILURE AND RETURN ITS EXIT CODE — the one way a command reports that it could not do what was asked: for a
+ * person on stderr (failureText), under --json as one JSON document on stdout (failureJson), so a program that asked for
+ * data never has to read prose. tests/conventions.test.ts refuses a `mason <cmd>: …` written to stderr any other way.
+ */
+export function failed(cmd, f, o) {
+    const n = asFailure(f);
+    const io = o.io ?? STDIO;
+    if (o.json)
+        io.out(failureJson(n));
+    else
+        io.err(failureText(cmd, n, o.style ?? failureStyle(io)));
+    return exitOf(n);
+}
+/** The style a failure is drawn in: stderr's own when it goes to stderr, plain for an io a test or a caller supplied.
+ *  By the STREAM, never by "was an io passed" (CLAUDE.md "Two readers, one interface"): mason init defaults its io to
+ *  STDIO and passed it on, and every failure it drew was plain — no red head, no dim labels — on a terminal. */
+export const failureStyle = (io) => io === STDIO ? styleErr() : PLAIN;
+/** A failure's exit code: its code's (2 a wrong command line; 124 anything that ran out of time, a wait or a query Mason
+ *  did not answer in time; else 1), unless it names one. The one place it is decided, so the same refusal exits the
+ *  same wherever it is found. */
+export function exitOf(f) {
+    return f.exit ?? (f.code === "usage" ? 2 : f.code === "timeout" ? 124 : 1);
+}