@mason-data/cli 0.9.0 → 0.11.0

package/README.md

@@ -106,7 +106,7 @@ again and remove `mason/models/`.
 | `mason wait [--timeout <s>]` | Waits until every added table is synced and served, showing every added table on a line of its own: 100% for the finished ones, in the order they finished, and a bar for each still syncing (rows, %, rate, time left) at the bottom. Exit 0 ready, 1 a first sync failed (printed, with what to do), 124 timed out (default 600 s). |
 | `mason user add\|list\|remove <name>` | The users of the Postgres API: a name and a password that does not expire, as a BI tool's datasource form asks for them or an app's `DATABASE_URL` carries them. `add` prints the password once with the URL; `remove` refuses the next connection at once and ends the sessions it holds at their next statement, without a restart. |
 | `mason mcp [--url <url>]` | An MCP server on stdio for Claude Code, Claude Desktop and other agents (below): the tables Mason serves with each one's rows and how current it is, a table's columns, a statement's rows with their Postgres types or Mason's refusal with its way out, and EXPLAIN — connected as a `mason user` (`MASON_URL`, else `--url`), beside `mason start` or a `mason serve` elsewhere. |
-| `mason ui` | Opens the running Mason's web page in your browser: the Overview (what `mason status` says), the Tables (add, remove or sync one), the Users of `mason user` (add one, its password shown once; disable, enable or remove one) and Observability (the statements, usage over time, the sync's events), refreshed while the tab is open. It prints the URL with the run's token, which the page trades for a cookie on the first visit; `--no-open` prints it only, `--json` is `{ url, port }`. `mason start`'s alone: `mason serve` serves no page. |
+| `mason ui` | Opens the running Mason's web page in your browser: the Overview (what `mason status` says), the Tables (add, remove or sync one), the Users of `mason user` (add one, its password shown once; disable, enable or remove one) and Observability (the statements, usage over time, the sync's events), refreshed while the tab is open. It prints the URL with the run's token, which the page trades for a cookie on the first visit, and opens it in a browser on a terminal; `--no-open` (or output that is not a terminal) prints it only, `--json` is `{ url, port }`. `mason start`'s alone: `mason serve` serves no page. |
 | `mason status` | What Mason is doing: the database and how its changes are read, the project folder, the synced data's file, the Postgres API and how it listens, each synced table, the statements of the last day and week (each outcome, the completed ones' average, p50 and p95 time, the rows and bytes sent), the ones answered slowly in the last day and the ones refused or failed, each with its reason. In replication mode, where the stream is. |
 | `mason sync <table>…` | Brings these synced tables up to date now, by one poll each: a table whose `sync:` is `off` is kept current only so (from cron, before a report), a polled one is polled now as well as at its interval. In replication mode the stream keeps every table current, and it says where the stream is. |
 | `mason logs [-n <lines>] [-f] [--start] [--requests [<filters>]] [--events [--failed]] [--running]` | Mason's log: every sync, poll and statement, with warnings and errors and their reasons; `-f` follows it, `--start` shows what `mason start` printed instead. `--requests` is the request log: every statement a tool sent, when, the outcome (ok, refused, failed, cancelled) and SQLSTATE, how long, the rows and bytes sent, the tool and the user; `--failed` only the ones not answered, `--outcome`, `--since` / `--until` (`2h`, `7d`, an ISO time), `--user` and `--client` narrow it, and `--before` reads the page before. `--events` is the sync's events: each first sync, poll, catch-up or stream that failed, the database out of reach, a table current again, each sync asked by hand (mason sync, the page's Sync now), and each restart of the run (`--failed` only the failures). `--running` lists the statements running now, by session. |
@@ -117,10 +117,12 @@ again and remove `mason/models/`.
 | `mason serve` | Mason for a server or a container: `mason start --attach` configured by the environment alone, its state in one folder (a volume), its log on stdout, `GET /healthz`, `GET /metrics` (Prometheus, numbers only), a clean stop on SIGTERM. `mason serve --help` lists every setting with its default; `MASON_PROJECT_READONLY=1`, for a project folder deployed as committed, refuses every edit of its files there (`mason add`, `mason remove`, the page's Add and Remove), with "edit the files and deploy them". |
 | `mason login` | Signs this machine in to a hosted Mason service (`MASON_CLOUD_URL`, else `https://app.masondata.ai`): it prints a page and a code (on stderr, at once, so a coding agent can pass them on), opens the page in a browser on a terminal, waits until the code is approved, then says who is signed in and their organisations. The login is kept in `~/.config/mason/credentials.json` (0600), never in a project; refused while `MASON_TOKEN` is set, which every command uses first. [`docs/HOSTED-API.md`](../docs/HOSTED-API.md) is the API. |
 | `mason logout` | Revokes this machine's login to that service and removes it. When the service cannot be reached, the login is still removed, and it says it was NOT revoked and how to revoke it. |
+| `mason replica create\|list\|status` | A hosted Mason service's replicas: `create <org>/<name> --region <region> --size <gb>` makes one for this project's database (its URL read by the variable the sources file names, never from the command line) and waits until it is ready; `list [<org>]` lists them; `status <org>/<name>` says how one is. [`docs/HOSTED-API.md`](../docs/HOSTED-API.md#replicas-mason-replica) is the API. |
+| `mason token create\|list\|revoke` | A hosted Mason service's CI tokens: `create --replica <org>/<name>` makes one for a replica, printed once, for a deploy from CI (`MASON_TOKEN`); `list [<org>]` lists them; `revoke <id>` revokes one. |
 | `mason deploy [--replica <org>/<name>] [--dry-run] [--timeout 10m]` | Sends this project's files (the YAML under `mason/`: never `.env` or `.mason/`) to a replica on the hosted service (`--replica`, else `MASON_REPLICA`), after checking the project as `mason start` does, without connecting to any database, then waits until the replica runs it (exit 0), Mason there refuses it (its failure printed as it came, exit 1), or the timeout (exit 124: the deploy goes on, its id said). `--dry-run` prints each file, its size and its sha256, and sends nothing. The login is `MASON_TOKEN`, else `mason login`'s. |
 
 Every command documents itself: `mason --help` lists them, and `mason <command> --help` (or `mason help <command>`) says
-how to use one, with examples. Every command but `help` and `mcp` (whose stdout is the MCP protocol's) takes `--json`. A command means the project of the folder it
+how to use one, with examples; `mason <command> --help --json` is its spec as data, and `mason help --json` every command's. Every command but `mcp` (whose stdout is the MCP protocol's) takes `--json`. A command means the project of the folder it
 runs in, or the nearest one above it.
 
 ## What `mason start` does
@@ -159,7 +161,7 @@ there (`mason status` lists them); `MASON_STORE_JSON_PATHS=off` turns that off.
 | Option | What it does |
 |---|---|
 | `--self-signed-tls` | The Postgres API requires TLS, from a certificate made for this project in `.mason/` (served again by every later start with the flag); clients connect with `sslmode=require`. |
-| `--port <n>` | The port the `mason` commands reach it on (default 4039, or the next free one). |
+| `--ui-port <n>` | The port of the web page and the `mason` commands, on 127.0.0.1 (default 4039, or the next free one); `MASON_UI_PORT` on a server. `--port` is gone: it answers with the line to run and exit 2. |
 | `--attach` | Stay in the foreground: the terminal shows Mason's progress, and Ctrl-C stops it. |
 
 `--replication`, `--poll` and `--publication` are gone: each answers with the line to write at the top of the sources
@@ -181,7 +183,7 @@ what changed is written. A different database is refused: `mason destroy`, then
 `mason help agent` is the page an agent reads first, offline: the commands in the order a project takes them, every
 answer's shape, the exit codes and the failure codes. In short:
 
-- Every command but `help` and `mcp` takes `--json` and answers with **one JSON object on stdout**, always with
+- Every command but `mcp` takes `--json` and answers with **one JSON object on stdout**, always with
   `next: [{ command, what }]` — the commands to run next, the same a person reads under `Next:`. The other keys are the
   command's own; `mason help <command>` names them on its `--json` line. Lists are wrapped (`{ tables: […], next }`).
 - A failure is `{ "error": { "code", "message", "why", "fix" }, "next": […] }` on stdout, and the **exit code** says it:

package/dist/src/api/error.js

@@ -19,3 +19,7 @@ export class ApiError extends Error {
 /** The code of a DISABLED `mason user`'s refused login or session (src/duck/users.ts): the listener answers it 28000, as
  *  Postgres answers a role without LOGIN, never 28P01 — its password was right. */
 export const USER_DISABLED = "user_disabled";
+/** The code of a `mason user`'s login or session refused for its ADDRESS (src/duck/users.ts `from`): the listener answers
+ *  it 28000 before any password is checked, in the same words whether the user exists or not, as Postgres answers a
+ *  connection no pg_hba.conf line takes. */
+export const ADDRESS_NOT_ALLOWED = "address_not_allowed";

package/dist/src/api/postgres/proxy.js

@@ -14,6 +14,8 @@
  * peer, a v4-mapped IPv6 address shown as IPv4 (`shownAddress`). The request log's `client_addr` and the session's log
  * line read it, never the socket.
  */
+import { ALL_END, cidrOf, covers, inRanges, ipv6Text, rangeOf, shownAddress, V4_END, V4_START } from "../../lib/cidr.js";
+export { shownAddress };
 /** the v2 header's first 12 bytes (section 2.2) */
 export const PROXY_V2_SIGNATURE = Buffer.from([0x0d, 0x0a, 0x0d, 0x0a, 0x00, 0x0d, 0x0a, 0x51, 0x55, 0x49, 0x54, 0x0a]);
 /** how a v1 (text) header begins */
@@ -87,166 +89,10 @@ export const startsProxyHeader = (first) => first === PROXY_V2_SIGNATURE[0] || f
 export function clientAddress(peer, header) {
     return header?.source?.address ?? shownAddress(peer);
 }
-/** An address as Mason shows it: IPv4 dotted, IPv6 in RFC 5952's form, a v4-mapped IPv6 one as IPv4; null when it is no
- *  address (undefined, a zone index, a name). */
-export function shownAddress(text) {
-    if (text === undefined)
-        return null;
-    const v4 = ipv4Bytes(text);
-    if (v4 !== null)
-        return Array.from(v4).join(".");
-    const v6 = ipv6Bytes(text);
-    return v6 === null ? null : ipv6Text(v6);
-}
-/** An IPv4 address's 4 bytes, from dotted decimal with no leading zero; null for anything else. */
-function ipv4Bytes(text) {
-    const parts = text.split(".");
-    if (parts.length !== 4 || !parts.every((p) => /^(?:0|[1-9]\d{0,2})$/.test(p) && Number(p) <= 255))
-        return null;
-    return Uint8Array.from(parts.map(Number));
-}
-/** An IPv6 address's 16 bytes (`::` once at most, an IPv4 tail); null for anything else, a zone index included. */
-function ipv6Bytes(text) {
-    if (!/^[0-9A-Fa-f:.]+$/.test(text))
-        return null;
-    const halves = text.split("::");
-    if (halves.length > 2 || (halves.length === 2 && halves[0].includes(".")))
-        return null;
-    const groups = (s) => {
-        if (s === "")
-            return [];
-        const out = [];
-        const parts = s.split(":");
-        for (const [i, p] of parts.entries()) {
-            if (i === parts.length - 1 && p.includes(".")) {
-                const v4 = ipv4Bytes(p);
-                if (v4 === null)
-                    return null;
-                out.push((v4[0] << 8) | v4[1], (v4[2] << 8) | v4[3]);
-            }
-            else if (/^[0-9A-Fa-f]{1,4}$/.test(p))
-                out.push(parseInt(p, 16));
-            else
-                return null;
-        }
-        return out;
-    };
-    const head = groups(halves[0]), tail = halves.length === 2 ? groups(halves[1]) : [];
-    if (head === null || tail === null)
-        return null;
-    const n = head.length + tail.length;
-    if (halves.length === 1 ? n !== 8 : n > 7)
-        return null;
-    const all = [...head, ...new Array(8 - n).fill(0), ...tail];
-    return Uint8Array.from(all.flatMap((g) => [g >> 8, g & 0xff]));
-}
-/** whether 16 bytes are an IPv4 address mapped into IPv6 (::ffff:a.b.c.d) */
-const v4Mapped = (b) => b.subarray(0, 10).every((x) => x === 0) && b[10] === 0xff && b[11] === 0xff;
-/** 16 bytes as Mason shows an IPv6 address: RFC 5952 (lower case, the longest run of two or more zero groups as `::`,
- *  the first of equal runs), and a v4-mapped one as its IPv4 address. */
-function ipv6Text(b) {
-    if (v4Mapped(b))
-        return Array.from(b.subarray(12, 16)).join(".");
-    const g = Array.from({ length: 8 }, (_, i) => (b[2 * i] << 8) | b[2 * i + 1]);
-    let at = -1, run = 0;
-    for (let i = 0; i < 8;) {
-        if (g[i] !== 0) {
-            i++;
-            continue;
-        }
-        let j = i;
-        while (j < 8 && g[j] === 0)
-            j++;
-        if (j - i > run) {
-            at = i;
-            run = j - i;
-        }
-        i = j;
-    }
-    const hex = g.map((x) => x.toString(16));
-    return run < 2 ? hex.join(":") : `${hex.slice(0, at).join(":")}::${hex.slice(at + run).join(":")}`;
-}
-/**
- * EVERY ADDRESS IN ONE SPACE, as Mason means one: IPv6's 128 bits, an IPv4 address at its v4-mapped place
- * (::ffff:a.b.c.d), since a v4-mapped peer or header source IS that IPv4 client (`shownAddress`). What an entry names and
- * what the list covers are both read here, never from how an entry is spelt: `0.0.0.0/1,128.0.0.0/1` is every IPv4
- * address, as `0.0.0.0/0` is, and `::/64` holds every v4-mapped address, so every IPv4 one too.
- */
-const V4_START = 0xffffn << 32n;
-const V4_END = V4_START + (1n << 32n) - 1n;
-const ALL_END = (1n << 128n) - 1n;
-const bigOf = (b) => b.reduce((n, x) => (n << 8n) | BigInt(x), 0n);
-/** an address's place (`V4_START`), or null when it is no address */
-function placeOf(address) {
-    const v4 = ipv4Bytes(address);
-    if (v4 !== null)
-        return V4_START | bigOf(v4);
-    const v6 = ipv6Bytes(address);
-    return v6 === null ? null : bigOf(v6);
-}
-/** the places an entry names */
-function rangeOf(c) {
-    const start = c.family === 4 ? V4_START | bigOf(c.bytes) : bigOf(c.bytes);
-    return { start, end: start + (1n << BigInt((c.family === 4 ? 32 : 128) - c.prefix)) - 1n };
-}
 /** Whether `address` (as `shownAddress` shows one, or in any spelling of the same address) is among those `from` names. */
-export function proxyNames(from, address) {
-    const at = placeOf(address);
-    return at !== null && from.ranges.some((r) => r.start <= at && at <= r.end);
-}
-/** whether `ranges` together hold every place from `lo` to `hi` */
-function covers(ranges, lo, hi) {
-    let next = lo;
-    for (const r of [...ranges].sort((a, b) => (a.start < b.start ? -1 : a.start > b.start ? 1 : 0))) {
-        if (r.start > next)
-            return false;
-        if (r.end >= next)
-            next = r.end + 1n;
-        if (next > hi)
-            return true;
-    }
-    return next > hi;
-}
-function prefixEqual(a, b, bits) {
-    for (let i = 0; i * 8 < bits; i++) {
-        const mask = bits - i * 8 >= 8 ? 0xff : (0xff << (8 - (bits - i * 8))) & 0xff;
-        if ((a[i] & mask) !== (b[i] & mask))
-            return false;
-    }
-    return true;
-}
-/** the network `bytes` / `prefix` names, its host bits cleared */
-function network(bytes, prefix) {
-    return bytes.map((x, i) => i * 8 >= prefix ? 0 : prefix - i * 8 >= 8 ? x : x & ((0xff << (8 - (prefix - i * 8))) & 0xff));
-}
-const text = (family, bytes) => family === 4 ? Array.from(bytes).join(".") : ipv6Text(bytes);
-/** One entry read, or what is wrong with it, with a did-you-mean where one is a fair guess: a guess is offered only
- *  once it is read as an entry itself, so it is never one that would be refused in turn. */
-function cidrOf(entry) {
-    const quoted = JSON.stringify(entry);
-    const m = /^([^/]*)(?:\/(\d{1,3}))?$/.exec(entry);
-    const v4 = m === null ? null : ipv4Bytes(m[1]), v6 = m === null || v4 !== null ? null : ipv6Bytes(m[1]);
-    if (m === null || (v4 === null && v6 === null)) {
-        return { problem: `${quoted} is not an address or a CIDR (10.0.0.0/16, 2001:db8::/32, or one address such as 10.0.4.7; a host name is not looked up)` };
-    }
-    const family = v4 !== null ? 4 : 6, bytes = (v4 ?? v6), max = family === 4 ? 32 : 128;
-    const prefix = m[2] === undefined ? max : Number(m[2]);
-    if (prefix > max)
-        return { problem: `${quoted}: an IPv${family} prefix is at most /${max}` };
-    if (family === 6 && v4Mapped(bytes) && prefix >= 96) {
-        const p4 = prefix - 96, net4 = network(bytes.subarray(12, 16), p4);
-        const meant = `${text(4, net4)}${p4 === 32 ? "" : `/${p4}`}`, read = cidrOf(meant);
-        return { problem: "problem" in read
-                ? `${quoted} is IPv4 written as IPv6, which Mason reads as ${meant}, and ${read.problem}`
-                : `${quoted} is IPv4 written as IPv6, which Mason reads as IPv4: did you mean ${meant}?` };
-    }
-    if (prefix === 0)
-        return { problem: `${quoted} names every address, so any client could claim to be any other: name the proxy's own addresses` };
-    const net = network(bytes, prefix);
-    if (!prefixEqual(net, bytes, max))
-        return { problem: `${quoted} has bits set past its prefix: did you mean ${text(family, net)}/${prefix}?` };
-    return { family, bytes: net, prefix };
-}
+export const proxyNames = (from, address) => inRanges(from.ranges, address);
+/** what a prefix of 0 is refused with: a header believed from every address lets any client claim to be any other */
+const EVERY = "so any client could claim to be any other: name the proxy's own addresses";
 /**
  * `MASON_PG_PROXY_FROM` read: null when it is unset or empty (no header is believed from anyone, as before), the
  * addresses it names, or why not: every entry that is not an address or a CIDR, each said with what is wrong, or a list
@@ -263,7 +109,7 @@ export function parseProxyFrom(value) {
             wrong.push("an empty entry between two commas");
             continue;
         }
-        const c = cidrOf(e);
+        const c = cidrOf(e, EVERY);
         if ("problem" in c)
             wrong.push(c.problem);
         else

package/dist/src/api/postgres/server.js

@@ -4,7 +4,7 @@ import * as crypto from "node:crypto";
 import * as net from "node:net";
 import * as tls from "node:tls";
 import { catalogRows } from "../../duck/analyze.js";
-import { ApiError, USER_DISABLED } from "../error.js";
+import { ADDRESS_NOT_ALLOWED, ApiError, USER_DISABLED } from "../error.js";
 import { hashCaller, outcomeOf, storedPayload } from "../request-log.js";
 import { gapRefusal, StatementError } from "../../duck/statement.js";
 import { canonicalZone } from "../../lib/timezone.js";
@@ -296,6 +296,8 @@ const aborted = () => new PgError({ code: "25P02", message: "current transaction
 const nameLength = (name) => name === undefined ? undefined : Buffer.from(name, "utf8").subarray(0, 63).toString("utf8");
 /** The hint a refused login is told on the run's own listener. */
 const USER_LOGIN_HINT = "a tool that keeps one password connects as a user: mason user add <name> prints its password and URL";
+/** What a connection refused for its address is told (ADDRESS_NOT_ALLOWED): the same whether the user exists or not. */
+const ADDRESS_HINT = "a user limited to address ranges connects only from them: mason user list shows each user's ranges, mason user from <name> changes them";
 /**
  * THE CONNECTIONS STILL LOGGING IN ON A PUBLIC SOCKET (`ShareDoor`): at most `limit`, each for at most `ms`, the oldest
  * making way for a new one. A limit that refused the NEW connection would hand the socket to whoever opened `limit`
@@ -775,10 +777,25 @@ class Session {
         }
         let token;
         try {
-            token = await this.door.authenticate(m.password, this.user);
+            token = await this.door.authenticate(m.password, this.user, this.clientAddr);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            // an address outside the user's ranges, judged before its password: refused as Postgres refuses a connection no
+            // pg_hba.conf line takes (28000), in words made of the name and the address alone, so a missing user and a
+            // limited one read the same; which it was is the log's (the ApiError's message)
+            if (err instanceof ApiError && err.code === ADDRESS_NOT_ALLOWED) {
+                this.server.log(`session ${this.id} refused: ${message}`);
+                const refused = new PgError({ code: "28000", message: `no entry for ${this.clientAddr === null ? "an address that could not be read" : `host "${this.clientAddr}"`}, user "${this.user}"`,
+                    hint: ADDRESS_HINT }, 401);
+                this.asked = { sql: "", method: "CONNECT", startedAt: Date.now(), sentAt: this.sentBytes };
+                const response = errorResponse({ ...refused.fields, severity: "FATAL" });
+                if (this.door.refused?.(this.user) !== false)
+                    this.recordRequest(refused, undefined, err.userName, [response]);
+                this.send(response);
+                this.end("authentication failed");
+                return;
+            }
             // a revocation record that could not be read is no wrong password: the server could not tell, said as such
             const unknown = err instanceof ApiError && err.status === 503;
             // a disabled user (`mason user disable`): its password was right, so it is no wrong password but a role that may
@@ -2446,7 +2463,7 @@ class Session {
             return null;
         try {
             // the user as the file has it NOW: its role given or taken since applies to this statement
-            const fresh = await recheck(this.token);
+            const fresh = await recheck(this.token, this.clientAddr);
             if (fresh !== undefined && this.token !== null)
                 this.token = fresh;
         }
@@ -2459,7 +2476,8 @@ class Session {
                 this.recordRefusal(asked.toUpperCase(), err);
             this.fatal("28000", `the session's user is no longer accepted: ${message}`, this.door.public ? this.door.loginHint : err instanceof ApiError && err.code === USER_DISABLED
                 ? `a disabled user's sessions end at their next statement; mason user enable ${user} lets it connect again, with the same password`
-                : `a removed user's sessions end at their next statement; mason user add ${user} makes it again, with a new password`);
+                : err instanceof ApiError && err.code === ADDRESS_NOT_ALLOWED ? `its address ranges changed: a session from outside them ends at its next statement (mason user list shows them; mason user from ${user} changes them)`
+                    : `a removed user's sessions end at their next statement; mason user add ${user} makes it again, with a new password`);
             return null;
         }
         this.verifiedAt = now;

package/dist/src/cli/command.js

@@ -7,12 +7,15 @@
  *
  *   - `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);
+ *   - it reads in the order a person needs it: the usage line, a short description, the examples, the flags (one
+ *     entry each); then the long prose, and a long --json shape last (`The --json answer: …`, its entry saying so);
  *   - 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";
+import { closest } from "../lib/did-you-mean.js";
 /**
  * A LINE THAT HOLDS A HOSTED SERVICE'S TEXT IS BROKEN BY THE CLI, NEVER BY THE TERMINAL, AT EVERY WIDTH (PR 481's
  * class rounds: a value sized to the terminal's width made the terminal start a visual line at column 0 with a forged
@@ -169,15 +172,20 @@ const fit = (text, s, indent, firstUsed = indent) => {
 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.
+ * printing the usage for `--help` (its spec as data for `--help --json`), 2 after saying what is wrong with the line,
+ * then the usage.
  */
 export function parseCommand(spec, argv) {
+    if (specAsked(spec, argv)) {
+        process.stdout.write(`${specAnswer(spec)}\n`);
+        return 0;
+    }
     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) });
+        return failed(spec.name, { ...parseProblem(spec, e), code: "usage", usage: synopsis(spec), next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json: wantsJson(argv, spec) });
     }
     if (parsed.values.help) {
         process.stdout.write(spec.usage);
@@ -185,6 +193,140 @@ export function parseCommand(spec, argv) {
     }
     return { values: parsed.values, positionals: parsed.positionals };
 }
+/** A LIST FLAG's value, one comma list however it was written (`multiple: true` in the spec): `--columns id,status`
+ *  and `--columns id --columns status` mean the same, `id,status`; undefined when it was not given. */
+export function listFlag(v) {
+    if (typeof v === "string")
+        return v;
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string").join(",") : undefined;
+}
+/** A command that takes no argument, given one (`mason stop myproject` stopped this folder's project, not that one):
+ *  a wrong line, its usage's synopsis. Null when there is none. */
+export function noArguments(spec, positionals, json) {
+    if (!positionals.length)
+        return null;
+    return failed(spec.name, { message: `it takes no argument (${positionals.join(" ")}): a project is its folder`, code: "usage",
+        fix: `run it in the project's folder: cd <folder> && mason ${spec.name}, or mason -C <folder> ${spec.name}`, usage: synopsis(spec),
+        next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json });
+}
+/** Whether a line asks for the command's spec as data: `--help` (or `-h`) and `--json` on a line that parses — every
+ *  command, whether or not it takes --json itself (mason help, mason mcp): the spec is what an agent reads first. A line
+ *  that does not parse is no such question: parseCommand's own parse says what is wrong with it. */
+function specAsked(spec, argv) {
+    if (!argv.includes("--json") || !(argv.includes("--help") || argv.includes("-h")))
+        return false;
+    try {
+        const options = { ...spec.options, ...HELP, json: { type: "boolean" } };
+        const p = parseArgs({ args: [...argv], options, allowPositionals: true });
+        return p.values["help"] === true && p.values["json"] === true;
+    }
+    catch (e) {
+        // not swallowed: the same line goes on to parseCommand's own parse, which says this error in the CLI's words
+        if (!(e instanceof TypeError))
+            throw e;
+        return false;
+    }
+}
+/** The keys of a command's spec as data (`mason <name> --help --json`, `mason help <name> --json`). */
+export const SPEC_ANSWER_KEYS = ["command", "next"];
+/** What follows a command's spec as data. */
+export const SPEC_NEXT = [["mason help --json", "every command's spec, the guides and the failure codes"]];
+/** A command's spec as its --json answer: `{ command: <spec>, next }`. */
+export const specAnswer = (spec) => jsonText({ ...spec, json: SPEC_ANSWER_KEYS }, { command: specJson(spec) }, SPEC_NEXT);
+/**
+ * THE EXIT CODES, a closed set (`mason help agent` lists them, and each command's spec as data names those it can
+ * exit with): 124 only for a command TIMEOUT_COMMANDS names.
+ */
+export const EXIT_CODES = {
+    0: "done",
+    1: "failed, with the reason",
+    2: "the command line is wrong (without --json the usage follows)",
+    124: "ran out of time (nothing stopped)",
+};
+/** Whether a command can run out of time (exit 124): TIMEOUT_COMMANDS names it. */
+const timesOut = (name) => new RegExp(`\\bmason ${name}\\b`).test(TIMEOUT_COMMANDS);
+export function specJson(spec) {
+    const lines = spec.usage.split("\n");
+    const end = lines.findIndex((l) => l.trim() === "");
+    const forms = lines.slice(0, end < 0 ? lines.length : end).map((l) => l.replace(/^usage:\s*/, "").trim());
+    const options = Object.entries({ ...spec.options, ...HELP }).map(([name, d]) => {
+        // the placeholder the synopsis writes after it, else the first the usage does
+        const placeholder = new RegExp(`--${name}[ =]([^\\s\\[\\]]+)`);
+        const value = d.type === "string" ? (forms.map((f) => placeholder.exec(f)?.[1]).find((v) => v !== undefined) ?? placeholder.exec(spec.usage)?.[1] ?? null) : null;
+        return { name: `--${name}`, short: d.short ? `-${d.short}` : null, type: d.type, multiple: d.multiple === true, default: d.default ?? null, value };
+    });
+    const exitCodes = Object.entries(EXIT_CODES).filter(([code]) => code !== "124" || timesOut(spec.name)).map(([code, meaning]) => ({ code: Number(code), meaning }));
+    return { name: spec.name, summary: spec.summary, usage: spec.usage, forms: forms.map((f) => ({ synopsis: f, positionals: positionalsOf(f, spec.name) })), options,
+        json: spec.json ? [...spec.json] : null, needs: spec.needs ?? null, stdout: spec.stdout ?? null, exitCodes };
+}
+/** The words of a synopsis form that are no option: split at the spaces outside brackets, `mason <name>` and every
+ *  option dropped — a bracketed group that starts with `-` (`[--json]`, `[-n <lines>]`), and a bare option with its
+ *  value (`--ssh <user@server>`). */
+function positionalsOf(form, name) {
+    const words = [];
+    let word = "", depth = 0;
+    for (const ch of form) {
+        if (ch === "[" || ch === "<")
+            depth++;
+        if (ch === "]" || ch === ">")
+            depth = Math.max(0, depth - 1);
+        if (ch === " " && depth === 0) {
+            if (word)
+                words.push(word);
+            word = "";
+            continue;
+        }
+        word += ch;
+    }
+    if (word)
+        words.push(word);
+    const rest = words[0] === "mason" && words[1] === name ? words.slice(2) : words;
+    const out = [];
+    for (let i = 0; i < rest.length; i++) {
+        const w = rest[i];
+        // an option is a dash and a letter (`[--json]`, `-n`); a lone `-` (`mason init -`, stdin) is a positional
+        if (/^\[--?[A-Za-z]/.test(w))
+            continue;
+        if (/^--?[A-Za-z]/.test(w)) {
+            if (rest[i + 1]?.startsWith("<"))
+                i++;
+            continue;
+        }
+        out.push(w);
+    }
+    // an alternative whose other side was an option (`<org>/<name> | --replica <org>/<name>`) leaves no `|` behind
+    return out.filter((w, i) => w !== "|" || (i > 0 && i < out.length - 1));
+}
+/** A command's synopsis: its usage's first lines, up to the first blank one (`usage: mason <name> …` and its other
+ *  forms), then where the rest is. What a wrong line is answered with: the whole usage is for `--help` (94 lines for
+ *  `mason status`, and the mistake scrolled away above it). */
+export function synopsis(spec) {
+    const lines = spec.usage.split("\n");
+    const end = lines.findIndex((l) => l.trim() === "");
+    return `${lines.slice(0, end < 0 ? lines.length : end).join("\n")}\n\nmason ${spec.name} --help for more\n`;
+}
+/** What is wrong with a line the parser refused, in the CLI's words (never Node's, whose advice about `--` misleads):
+ *  an option it does not take, with the closest it does (`didYouMean` over the spec's options and `--help`); one that
+ *  needs a value and has none; one that takes none and was given one. */
+function parseProblem(spec, e) {
+    const options = { ...spec.options, ...HELP };
+    const names = Object.keys(options).map((n) => `--${n}`);
+    const shorts = Object.entries(options).flatMap(([n, d]) => d.short ? [[`-${d.short}`, `--${n}`]] : []);
+    const said = /'(-[^'\s,]*)/.exec(e.message)?.[1];
+    const flag = said === undefined ? undefined : said.startsWith("--") ? said.replace(/=.*$/, "") : said;
+    if (e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" && flag !== undefined) {
+        const near = closest(flag, [...names, ...shorts.map(([s]) => s)]);
+        return { message: `there is no option ${flag}${near !== null ? ` — did you mean \`${near}\`?` : ""}`,
+            fix: `its options are ${names.join(", ")}` };
+    }
+    if (e.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE" && flag !== undefined) {
+        const long = shorts.find(([s]) => s === flag)?.[1] ?? flag;
+        const named = long === flag ? long : `${flag} (${long})`;
+        const takes = options[long.slice(2)]?.type === "string";
+        return takes ? { message: `${named} needs a value: ${flag} <value>` } : { message: `${named} takes no value: write ${flag} alone` };
+    }
+    return { message: e.message };
+}
 /** The column a step's `what` starts in, after the two-space indent: wide enough for `mason add orders --columns …`. */
 const NEXT_WIDTH = 44;
 /**
@@ -255,8 +397,11 @@ export function jsonText(spec, value, 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 commands that can run out of time, exit 124 (code `timeout`): the one list the codes and the agent's guide say. */
+export const TIMEOUT_COMMANDS = "mason wait, mason deploy, mason replica create, mason replica delete, mason login (its code expired), mason share and mason ui --ssh (no address or answer in time)";
 /**
- * THE CODES A FAILURE CARRIES, a closed set a program can branch on (`mason help agent` lists them).
+ * THE CODES A FAILURE CARRIES, a closed set a program can branch on (`mason help agent` lists them): `Failure.code` is
+ * one of them, so a code outside the set does not compile.
  */
 export const FAILURE_CODES = {
     usage: "the command line is wrong: a flag, an argument, a value (exit 2; the usage follows for a person)",
@@ -266,12 +411,16 @@ export const FAILURE_CODES = {
     bad_roles: "the project's roles file (mason/roles.yml) names something wrong: a table the sources file does not sync, a column the synced table lacks, a role with no table; 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_answering: "Mason's process is alive and does not answer its commands, hung: mason stop ends it (its synced data stays)",
     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, mason deploy, mason replica create; nothing stopped (exit 124)",
+    timeout: `ran out of time — ${TIMEOUT_COMMANDS}; nothing stopped (exit 124)`,
 };
+/** A code another process sent (the run's refusal, the server's Mason over ssh) as one of ours: its own when it is in
+ *  the set, else `otherwise` — a code outside it never reaches a program that branches on the set. */
+export const failureCode = (code, otherwise) => typeof code === "string" && Object.hasOwn(FAILURE_CODES, code) ? code : otherwise;
 /** 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;
@@ -312,7 +461,7 @@ export function failureJson(f) {
  * 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 n = usageWayOut(cmd, asFailure(f));
     const io = o.io ?? STDIO;
     if (o.json)
         io.out(failureJson(n));
@@ -320,6 +469,21 @@ export function failed(cmd, f, o) {
         io.err(failureText(cmd, n, o.style ?? failureStyle(io)));
     return exitOf(n);
 }
+/**
+ * A WRONG COMMAND LINE ALWAYS SAYS WHERE ITS USAGE IS, whatever raised it (the parse, or a command's own check, many of
+ * which answered with `next: []`): its next steps end with `mason <cmd> --help` (`mason --help` for no command), and it
+ * carries a fix, its own, else the way to its usage. Decided here, where every failure is said, so a usage failure added
+ * later cannot leave it out.
+ */
+export function usageWayOut(cmd, f) {
+    if (f.code !== "usage")
+        return f;
+    const help = cmd ? `mason ${cmd} --help` : "mason --help";
+    // `mason help <cmd>` is the same page, so a failure that names it already says where the usage is
+    const said = (c) => c === help || (cmd !== "" && c === `mason help ${cmd}`);
+    const next = f.next?.some(([c]) => said(c)) ? f.next : [...(f.next ?? []), [help, cmd ? "its usage, with every option" : "every command"]];
+    return { ...f, next, fix: f.fix ?? (cmd ? `write the line as its usage says (mason ${cmd} --help)` : "name a command mason --help lists") };
+}
 /** 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. */