@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/ui.js

@@ -1,42 +1,72 @@
 /**
- * `mason ui` — THE WEB PAGE OF THE RUNNING MASON, IN THE BROWSER (src/web/, docs/WEB-UI.md): what `mason status` says,
- * refreshed while the tab is seen, and the users of `mason user`. It prints the page's URL WITH the run's token (src/cli/security.ts: the first request trades it for an HttpOnly cookie and is redirected to a URL without
+ * `mason ui` — THE WEB PAGE OF THE RUNNING MASON, IN THE BROWSER (src/web/, docs/WEB-UI.md): the Overview (what `mason
+ * status` says), the Tables (`mason tables`, `add`, `remove`, `sync`), the Users (`mason user`) and Observability (`mason
+ * logs`, `mason usage`), refreshed while the tab is seen. It prints the page's URL WITH the run's token (src/cli/security.ts: the first request trades it for an HttpOnly cookie and is redirected to a URL without
  * it) and opens the browser. The reader is the person at this terminal, whom `mason user add` already shows a
  * password once; the token is never written anywhere else — not in `mason start`'s output (its log is a file), not in
  * `mason status`, which prints the URL without it.
  *
  * Before it prints anything it ASKS the page (`GET /` with the run's token as the commands send it), so a run that serves
- * none (`mason serve`'s, or one from before the page) is said, never a URL that answers 404.
+ * none (one from before the page) is said, never a URL that answers 404.
+ *
+ * `--ssh <user@server>` (src/cli/ui-ssh.ts, docs/WEB-UI.md "On a server") opens a server's page from this machine, through
+ * the machine's own ssh, and stays in the foreground until Ctrl-C, as `mason share` does; it needs no project here. Its
+ * URL carries a ticket for one use, never the run's token, which stays on the server. `--bridge` is what it runs there.
  */
 import { spawn } from "node:child_process";
 import { failed, jsonText, parseCommand, reportText } from "./command.js";
 import { reach } from "./state.js";
+import { bridge, openSshTunnel, targetProblem } from "./ui-ssh.js";
+import { version } from "./version.js";
 import { RunUnreachable } from "./control.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
+const say = (m) => { process.stderr.write(`${m}\n`); };
+const DEFAULT_TIMEOUT_S = 60;
 export const UI = {
     needs: "run",
     name: "ui",
-    summary: "the status page and the users, in your browser",
+    summary: "the status, tables, users and statements, in your browser",
     usage: `usage: mason ui [--no-open] [--json]
+       mason ui --ssh <user@server> [--mason <command>] [--timeout <seconds>] [--no-open] [--json]
 
-  Opens the running Mason's web page in your browser: what mason status says (the database, each table's copy and
-  its progress, the slow and refused statements, whether it is ready), refreshed every 2 s while the tab is open, and
-  the users of mason user — add one (its password shown once, with the URL to paste) or remove one.
+  Opens the running Mason's web page in your browser, refreshed while the tab is open: the Overview (what mason status
+  says: whether the synced data is ready, the database, the sync, the statements and the recent errors); the Tables (add,
+  remove or sync one, as mason add, remove and sync do); the Users of mason user (add one, its password shown once with
+  the URL to paste, or remove one); and Observability: the statements running and that ran (mason logs --requests,
+  cancel one), usage over time (mason usage), and the sync's events (mason logs --events).
 
   The URL carries this run's token: the page trades it for a cookie at once and drops it from the address
   bar. It is printed for you alone, like a user's password: paste it nowhere else. Every mason start makes a new
-  token, so after a restart run mason ui again. The page is mason start's: mason serve serves none (off this
-  machine it would need TLS and a login).
+  token, so after a restart run mason ui again.
+
+  --ssh opens a server's page (mason serve's) from this machine, with nothing public: it runs your ssh, so your
+  ~/.ssh/config, keys and SSO apply, starts mason there, and forwards a free local port to the page, which listens on the
+  server's loopback alone. It stays in the foreground: Ctrl-C closes the tunnel. It needs no project here. Its URL
+  carries a ticket for one use, never the run's token, which stays on the server. The server's Mason must be this
+  version or close to it, and must be a command ssh can run: --mason says how, for a container or a folder.
 
     mason ui
     mason ui --no-open        print the URL, open no browser
     mason ui --json
+    mason ui --ssh deploy@mason.example.com
+    mason ui --ssh deploy@mason.example.com --mason "docker exec -i mason-mason-1 mason"
+    mason ui --ssh deploy@mason.example.com --mason "cd /var/lib/mason && mason" --timeout 120 --no-open
+    mason ui --bridge --local-port 51000      what --ssh runs on the server; its stdout is a stream, not for reading
 
-  --no-open   print the URL only
-  --json      as data: { url (with this run's token), port }, next; it never opens a browser
+  --no-open            print the URL only
+  --ssh <target>       the server, as you give it to ssh: user@server, or a Host of your ssh config
+  --mason <command>    how to run mason on the server (default mason); a shell's text, kept to ssh's command line
+  --timeout <s>        how long ssh and the server have to answer (default ${DEFAULT_TIMEOUT_S}): a passphrase or a touch counts
+  --bridge             the server's end of --ssh, on stdin and stdout
+  --local-port <n>     the port the browser names, for --bridge: the laptop's
+  --json               as data: { url (with this run's token; with --ssh a ticket for one use; null when Ctrl-C came
+                       before the server answered, as port is, exit 0), port, server, project,
+                       version (with --ssh: the server's Mason, for what its answer may lack) }, next; it never opens a
+                       browser. With --ssh it then holds the tunnel: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
 `,
-    options: { "no-open": { type: "boolean", default: false }, json: { type: "boolean", default: false } },
-    json: ["url", "port", "next"],
+    options: { "no-open": { type: "boolean", default: false }, json: { type: "boolean", default: false }, ssh: { type: "string" }, mason: { type: "string" },
+        timeout: { type: "string" }, bridge: { type: "boolean", default: false }, "local-port": { type: "string" } },
+    json: ["url", "port", "server", "project", "version", "next"],
 };
 const NEXT = [["mason status", "the same, in this terminal"], ["mason user list", "the users"]];
 /** The command that opens a URL in the person's browser, by platform (macOS `open`, Windows `start`, else `xdg-open`). */
@@ -49,7 +79,7 @@ export function openCommand(platform, url) {
     return ["xdg-open", [url]];
 }
 /** Open `url` in the browser: null once the opener started, else why it could not (the URL is printed either way). */
-function openBrowser(url) {
+export function openBrowser(url) {
     const [command, args] = openCommand(process.platform, url);
     return new Promise((resolve) => {
         const child = spawn(command, args, { detached: true, stdio: "ignore" });
@@ -69,21 +99,98 @@ async function servesPage(run) {
     await res.arrayBuffer();
     return res.status === 200 && /^text\/html/.test(res.headers.get("content-type") ?? "");
 }
+/**
+ * THE PAGE OF A SERVER (the header): the tunnel, the URL once, and held until Ctrl-C or until it drops. As `mason share`:
+ * what `--json` prints is one object, once, and everything after it is on stderr, so stdout stays one document. The
+ * signals are heard before ssh starts: a Ctrl-C at a passphrase ends both.
+ */
+async function overSsh(target, mason, timeoutMs, open, json) {
+    let signalled = null;
+    const signal = new Promise((resolve) => {
+        const heard = (s) => { signalled = s; resolve(s); };
+        process.once("SIGINT", heard);
+        process.once("SIGTERM", heard);
+    });
+    const t = await openSshTunnel({ target, mason, timeoutMs, interactive: !json && process.stdin.isTTY === true, stopped: signal });
+    const next = [[`mason ui --ssh ${target}`, "again, once this one is closed: a new port and a new ticket"]];
+    if ("message" in t) {
+        if (signalled === null)
+            return failed("ui", t, { json });
+        // stopped on purpose, exit 0: under --json still the one object every answer is, its url null as nothing opened
+        if (json)
+            out(jsonText(UI, { url: null, port: null, server: target }, next));
+        else
+            say(`stopped before ${target} answered: nothing was left open`);
+        return 0;
+    }
+    if (json)
+        out(jsonText(UI, { url: t.url, port: t.port, server: target, project: t.project, version: t.serverVersion }, next));
+    else {
+        const couldNot = open ? await openBrowser(t.url) : null;
+        out(reportText({
+            headline: open && couldNot === null ? `${t.project} on ${target}, opened in your browser` : `${t.project} on ${target}`,
+            details: [["url", t.url], ["server", target], ["project", t.project], ["version", t.serverVersion]],
+            tips: [
+                ...(couldNot !== null ? [`Could not open a browser (${couldNot}): open the URL yourself.`] : []),
+                ...(t.serverVersion !== version() ? [`This machine's Mason is ${version()}: the page is the server's.`] : []),
+                "The URL carries a ticket for one use, and works for 5 minutes. Ctrl-C closes the tunnel.",
+            ],
+            next,
+        }));
+    }
+    const how = await Promise.race([signal.then((s) => ({ signal: s })), t.ended.then((why) => ({ why }))]);
+    if ("signal" in how) {
+        await t.stop();
+        say(`the tunnel to ${target} is closed`);
+        return 0;
+    }
+    return failed("ui", { message: `the tunnel to ${target} dropped`, code: "failed", why: how.why, fix: "is the server up, and this machine online? The page in your browser stops answering until a new tunnel opens one", next }, { json: false });
+}
 export async function ui(argv) {
     const f = parseCommand(UI, argv);
     if (typeof f === "number")
         return f;
     const json = f.values.json === true;
+    const v = f.values;
+    const wrong = (message) => failed("ui", { message, code: "usage", usage: UI.usage }, { json });
     if (f.positionals.length)
-        return failed("ui", { message: `mason ui takes no argument: ${f.positionals.join(" ")}`, code: "usage", usage: UI.usage }, { json });
+        return wrong(`mason ui takes no argument: ${f.positionals.join(" ")}`);
+    if (v.bridge) {
+        if (v.ssh !== undefined || v.mason !== undefined || v.timeout !== undefined || json)
+            return wrong("--bridge is mason ui --ssh's own end on the server: it goes with --local-port alone");
+        const port = Number(v["local-port"]);
+        if (!Number.isInteger(port) || port < 1 || port > 65_535)
+            return wrong(`--bridge needs --local-port, a port number, not ${JSON.stringify(v["local-port"] ?? "")}`);
+        return bridge(port);
+    }
+    if (v["local-port"] !== undefined)
+        return wrong("--local-port goes with --bridge");
+    if (v.ssh === undefined && (v.mason !== undefined || v.timeout !== undefined))
+        return wrong(`${v.mason !== undefined ? "--mason" : "--timeout"} goes with --ssh <user@server>`);
+    if (v.ssh !== undefined) {
+        const problem = targetProblem(v.ssh);
+        if (problem !== null)
+            return wrong(`--ssh: ${problem}`);
+        if (v.mason !== undefined && (v.mason.trim() === "" || /[\r\n]/.test(v.mason)))
+            return wrong("--mason is one line of shell that runs mason on the server");
+        const seconds = v.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(v.timeout);
+        if (!Number.isFinite(seconds) || seconds <= 0)
+            return wrong(`--timeout is a number of seconds, not ${JSON.stringify(v.timeout)}`);
+        return overSsh(v.ssh, v.mason ?? "mason", seconds * 1000, !v["no-open"], json);
+    }
     const w = await reach(UI, json);
     if (w === null || w.state !== "up")
         return 1;
     const run = w.run;
+    if (w.project.config.served === true) {
+        return failed("ui", { message: `Mason for ${run.name} runs on this server: its page is opened from your own machine`, code: "refused",
+            why: "the page listens on this machine's loopback alone, and a browser on a server has no one in front of it",
+            fix: "on your machine, mason ui --ssh <user@server> (mason ui --help: for a container, --mason)", next: [["mason status", "what it is doing, in this terminal"]] }, { json });
+    }
     if (!await servesPage(run)) {
         return failed("ui", { message: `Mason for ${run.name} serves no web page`, code: "refused",
-            why: "the page is mason start's: this is mason serve's run, or a run started by a Mason from before the page",
-            fix: "on your machine, mason stop && mason start runs it with the page; a server's Mason is read with mason status",
+            why: "this run was started by a Mason from before the page",
+            fix: "mason stop && mason start runs it with the page",
             next: [["mason status", "what it is doing, in this terminal"]] }, { json });
     }
     const url = `${run.control.url}/?token=${encodeURIComponent(run.control.token)}`;

package/dist/src/cli/usage.js

@@ -0,0 +1,128 @@
+/**
+ * `mason usage`: what the run was and did over time — a sample a minute (src/duck/usage.ts) of the copy's size and
+ * rows, the copies failed, how old the stalest copy is, the statements and their duration, the stream's lag and the
+ * memory — and each copy's own size. The run's `GET /api/usage` (src/cli/run-server.ts) answers it; `--json` prints that
+ * answer as it is, so an agent and a chart read the same samples a person reads here.
+ */
+import { failed, jsonText, parseCommand, endText } from "./command.js";
+import { out as styleOut } from "./style.js";
+import { callRun } from "./control.js";
+import { reach } from "./state.js";
+import { fileSize, guarded, runFailure } from "./commands.js";
+import { timeOf } from "./request-filter.js";
+import { duration, msText } from "./readiness.js";
+import { SIZE_EVERY_MS } from "../duck/usage.js";
+const out = (m) => { process.stdout.write(`${m}\n`); };
+const n = (x) => x.toLocaleString("en-US");
+export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>] [--step <span>] [--json]
+
+  What Mason was and did over time, from a sample it takes every minute and keeps MASON_HISTORY_DAYS days
+  (default 7): a line each span — the statements of the Postgres API (how many, how many were refused, failed or
+  cancelled — the errors column —, the completed ones' p95 duration, the rows sent), the synced data's size and rows, the
+  tables whose sync is failing, how old the stalest table was, the stream's lag (a table under sync: replication), and
+  the memory of the process and of the engine against its limit (MASON_DUCKDB_MEMORY). Then each synced table's own size, measured every
+  10 minutes. A span sums its statements and shows each level at its highest. Read through the running Mason.
+
+    mason usage                        the last hour, 5 minutes a line
+    mason usage --since 7d --step 1h   the last week, an hour a line
+    mason usage --since 2026-10-28T09:00:00Z --until 2026-10-28T10:00:00Z --step 0
+
+  --since <when>   from when: an age (90s, 30m, 6h, 7d) or an ISO 8601 date or time with its zone; default 1h
+  --until <when>   until when, the same way; default now
+  --step <span>    a line per span (1m to the days kept; default 5m), or 0 for every sample as it was taken
+  --json           as data: { since, until, stepSeconds (null: every sample), sampleSeconds, keptDays, samples: [{ at
+                   (with a step, the span's start), seconds, copyBytes, copyRows, tablesAdded, tablesCopied,
+                   tablesFailed, oldestSyncSeconds, statements, statementsRefused, statementsFailed, statementsCancelled,
+                   rowsSent, bytesSent, durationP50Ms, durationP95Ms, streamLagBytes, streamLagSeconds, rssBytes,
+                   heapUsedBytes, copyMemoryBytes, copyMemoryLimitBytes, slotWalHeldBytes (replication: the WAL the
+                   slot holds on the database), diskFreeBytes (free where the synced data is; with a step, the lowest),
+                   sessionsOpen (the Postgres API's sessions logged in) }],
+                   copySizes: [{ table, bytes, at }], next }
+`;
+export const USAGE = {
+    needs: "run",
+    name: "usage",
+    summary: "what Mason did over time: statements, the synced data's size and age, memory (a sample a minute; --since 7d --step 1h)",
+    usage: USAGE_USAGE,
+    options: { since: { type: "string" }, until: { type: "string" }, step: { type: "string" }, json: { type: "boolean" } },
+    json: ["since", "until", "stepSeconds", "sampleSeconds", "keptDays", "samples", "copySizes", "next"],
+};
+const UNIT = { s: 1, m: 60, h: 3600, d: 86_400 };
+/** A span as the options write it (90s, 30m, 6h, 7d; 0), in seconds, or null when it is not one. */
+export function spanSeconds(text) {
+    if (text.trim() === "0")
+        return 0;
+    const m = /^\s*(\d+)\s*([smhd])\s*$/.exec(text);
+    return m ? Number(m[1]) * UNIT[m[2]] : null;
+}
+/** One sample on one line: the time, the statements, those refused, failed or cancelled, p95, rows sent, the copy, its rows, the stalest copy, the lag, the memory. */
+export function sampleLine(s, withLag) {
+    const time = s.at.slice(0, 16).replace("T", " ");
+    const p95 = s.durationP95Ms === null ? "–" : msText(s.durationP95Ms);
+    const bad = s.statementsRefused + s.statementsFailed + s.statementsCancelled;
+    const age = s.oldestSyncSeconds === null ? "–" : duration(s.oldestSyncSeconds);
+    const lag = !withLag ? "" : `  ${(s.streamLagSeconds === null ? "–" : duration(s.streamLagSeconds)).padStart(9)}`;
+    const memory = `${fileSize(s.rssBytes)}${s.copyMemoryBytes === null ? "" : ` (engine ${fileSize(s.copyMemoryBytes)} of ${fileSize(s.copyMemoryLimitBytes)})`}`;
+    return `${time}  ${n(s.statements).padStart(10)}  ${(bad === 0 ? "" : n(bad)).padStart(7)}  ${p95.padStart(10)}  ${n(s.rowsSent).padStart(11)}  ` +
+        `${(s.copyBytes === null ? "–" : fileSize(s.copyBytes)).padStart(10)}  ${n(s.copyRows).padStart(13)}  ${(s.tablesFailed === 0 ? "" : n(s.tablesFailed)).padStart(7)}  ` +
+        `${age.padStart(10)}${lag}  ${memory}`;
+}
+/** The heading over `sampleLine`'s columns. */
+export function sampleHeading(withLag) {
+    return `${"time (UTC)".padEnd(16)}  ${"statements".padStart(10)}  ${"errors".padStart(7)}  ${"p95".padStart(10)}  ${"rows sent".padStart(11)}  ` +
+        `${"size".padStart(10)}  ${"rows".padStart(13)}  ${"failing".padStart(7)}  ${"oldest".padStart(10)}${withLag ? `  ${"lag".padStart(9)}` : ""}  memory`;
+}
+export async function usage(argv, now = Date.now()) {
+    const f = parseCommand(USAGE, argv);
+    if (typeof f === "number")
+        return f;
+    const v = f.values;
+    const json = v.json === true;
+    if (f.positionals.length)
+        return failed("usage", { message: `it takes no ${f.positionals.length === 1 ? "argument" : "arguments"}: ${f.positionals.join(" ")}`, code: "usage", usage: USAGE_USAGE }, { json });
+    // the one time grammar (src/cli/request-filter.ts timeOf): an age, or an ISO 8601 date or time WITH its zone
+    const since = timeOf("--since", v.since ?? "1h", now), until = v.until === undefined ? new Date(now).toISOString() : timeOf("--until", v.until, now);
+    for (const t of [since, until])
+        if (typeof t !== "string")
+            return failed("usage", { ...t, usage: USAGE_USAGE }, { json });
+    const step = spanSeconds(v.step ?? "5m");
+    if (step === null)
+        return failed("usage", { message: `--step is a span (1m, 5m, 1h, 1d) or 0 for every sample, not ${JSON.stringify(v.step)}`, code: "usage", usage: USAGE_USAGE }, { json });
+    const w = await reach(USAGE, json);
+    if (w === null || !("run" in w))
+        return 1;
+    const run = w.run;
+    return guarded("usage", json, async () => {
+        const q = new URLSearchParams({ since: since, until: until, ...(step === 0 ? {} : { step: String(step) }) });
+        const r = await callRun(run, "GET", `/api/usage?${q}`);
+        // the run's refusal (a step past the days kept, a since after until) in its own words and code
+        if (r.status !== 200)
+            return failed("usage", runFailure(r, [["mason usage --help", "the spans and times it takes"], ["mason logs", "the run's log"]]), { json });
+        const b = r.body;
+        const next = [["mason usage --since 7d --step 1h", "the week, an hour a line"], ["mason status", "where everything is now"]];
+        if (json) {
+            out(jsonText(USAGE, b, next));
+            return 0;
+        }
+        const st = styleOut();
+        const span = b.stepSeconds === null ? "every sample" : `${duration(b.stepSeconds)} a line`;
+        out(st.bold(`Usage from ${b.since.slice(0, 16).replace("T", " ")} to ${b.until.slice(0, 16).replace("T", " ")} UTC, ${span} (a sample every ${duration(b.sampleSeconds)}, kept ${b.keptDays} day${b.keptDays === 1 ? "" : "s"}):`));
+        if (!b.samples.length)
+            out(st.dim("  no sample in this time: Mason takes the first a minute after it starts"));
+        else {
+            const withLag = b.samples.some((s) => s.streamLagBytes !== null || s.streamLagSeconds !== null);
+            out(st.dim(sampleHeading(withLag)));
+            for (const s of b.samples)
+                out(sampleLine(s, withLag));
+        }
+        if (b.copySizes.length) {
+            out("");
+            out(st.bold(`Each synced table's own size (measured every ${duration(SIZE_EVERY_MS / 1000)}):`));
+            const wide = Math.max(...b.copySizes.map((c) => c.table.length));
+            for (const c of b.copySizes)
+                out(`  ${c.table.padEnd(wide)}  ${fileSize(c.bytes).padStart(10)}  ${st.dim(`at ${c.at.slice(11, 16)} UTC`)}`);
+        }
+        out(endText({ next }, st));
+        return 0;
+    });
+}

package/dist/src/cli/user-hosted.js

@@ -0,0 +1,299 @@
+/**
+ * `mason user add | list | disable | enable | remove … --replica <org>/<name>` — THE USERS OF A REPLICA ON A HOSTED MASON
+ * SERVICE (docs/HOSTED-API.md "The users of a replica"). Each subcommand is ONE request, the one the run's own command
+ * server takes for it (src/cli/run-server.ts `/api/users`), sent to the service under `/v1/replicas/{org}/{name}/users`:
+ *
+ *   list      GET    …/users?lastUsed=1                     mason user list --json's shape, beside its next
+ *   add       POST   …/users  { name, role?, set? }          mason user add --json's shape (the run is up: its url)
+ *   disable   POST   …/users/{user}/disable                  { disabled, already }
+ *   enable    POST   …/users/{user}/enable                   { enabled, already }
+ *   remove    DELETE …/users/{user}                          { removed }
+ *
+ * `--role` and `--set` go as they were given: Mason on the replica checks them with the functions it checks them with
+ * here (src/cli/user.ts `roleToAdd`, `attributesToAdd`). What only this command line says (a verb, a user's name, a
+ * role's name, a `--set`'s form) is checked first, by the same functions, and refused as a wrong line before a byte is
+ * sent. Nothing of a project here is read or written: the users are the replica's.
+ *
+ * THE ANSWER IS HELD TO THE RUN'S OWN ANSWER SHAPE, then printed by the renderers the local command prints with
+ * (src/cli/user.ts `listText`, `addedReport`, …), in serviceStyle: the same answer prints the same lines. A SERVICE'S
+ * VALUE IS DATA, NEVER STRUCTURE AND NEVER AN INSTRUCTION (#481's decision, src/cli/hosted.ts). Every value the
+ * service sends that this command prints, and how it is held:
+ *
+ *   value                                 where it is printed                         what holds it
+ *   a failure's message, why, fix         stderr's failure, --json error              `serviceFailure`: one line each (`serviceText`), masked
+ *   a failure's code                      inside why: "(the service said …)"          `^[a-z][a-z0-9_]*$`, 64 chars; the code is `codeOfStatus`'s
+ *   a failure's next                      nowhere: never read                         the step is `failureNext`'s, by the status
+ *   a user's name                         every row, headline and step it names       `USER_NAME_RE`; add, disable, enable, remove: the name asked
+ *   an id                                 list's rows, --json                         16 hex digits
+ *   addedAt, removedAt, disabledAt,       rows, list's lines, --json                  `isServiceTime`
+ *     lastUsedAt
+ *   the password                          add's url, psql and password rows, --json   `mason_<its id>_<32 hex>` (src/duck/users.ts), add's alone;
+ *                                                                                     anything shaped as one elsewhere refused (`carriesNoSecret`)
+ *                                                                                     or, in a failure's words, masked (`serviceText`)
+ *   database, host, port, sslmode         add's rows, --json                          the database name's rule, a host's letters, 1-65535, a closed set
+ *   url, psql (add)                       add's rows, --json                          rebuilt here (`connectionUrl`, `psqlLine`): the service's must equal them
+ *   url (list)                            --json                                      `postgres://<its name>@<host>:<port>/<database>`, no password
+ *   role, roleFrom, readsNothing,         rows, list's lines, --json                  `ROLE_NAME_RE`; closed sets; booleans; each consistent with the others
+ *     roleKnown, live
+ *   attributes, missingAttributes         rows, list's lines, --json                  `ATTRIBUTE_NAME_RE` names; each value one line (`serviceText`), bounded
+ *   lastUsedNote, urlNote                 list's tip "Last used: …", --json           one line (`serviceText`), bounded
+ *   requestLogDays                        list's lines, --json                        a whole number, 1 to 36500
+ *   already                               the headline chosen, --json                 a boolean
+ *   an HTTP status                        a failure's why                             a number
+ *
+ * BEFORE ANY OF THESE, every string of the answer, its keys included, is put to the exact test (src/cli/hosted.ts
+ * `carriesNoSecret`, `carriesSecret` on each: an echo of the held token, `ECHO_RUN` of its body in a row in one string; a
+ * token's or a password's shape — add's own password, url and psql for the token alone): an answer that carries one
+ * anywhere is refused whole, so no grammar is ever the only thing between a secret and the output, and an honest answer
+ * is refused with a probability under 1 in a million whatever its size. A failure's code, printed inside why, is put to
+ * the same test (`failureShape`). The free text (the notes, a refusal's words) is masked too, by #591's quarter rule.
+ *
+ * An answer any of which does not hold is outside the contract: said by the request and its status, never its body.
+ * What to run next is the CLI's own (`onReplica`: the local command's steps, each `mason user …` naming the replica).
+ */
+import { failed, jsonText, serviceStyle } from "./command.js";
+import { call, carriesNoSecret, isFailure, isServiceTime, serviceFailure, serviceNext, serviceOf, serviceText, unexpected } from "./hosted.js";
+import { replicaText, tokenFor } from "./replica.js";
+import { holdOutput } from "./output-gate.js";
+import { err as styleErr, out as styleOut } from "./style.js";
+import { connectionUrl, psqlLine } from "./pg-url.js";
+import { USER_NAME_RE } from "../duck/users.js";
+import { ROLE_NAME_RE } from "./roles.js";
+import { ATTRIBUTE_NAME_RE } from "../duck/row-filter.js";
+import { databaseNameProblem } from "../lib/database-name.js";
+import { NO_ROLES } from "../duck/grants.js";
+import { addedNext, addedReport, disabledNext, disabledReport, enabledNext, enabledReport, listNext, listText, REMOVED_NEXT, removedReport, USER } from "./user.js";
+/** The bound of a list's answer (a replica's users, a row each), and of the number of users in it; every other answer
+ *  is `call`'s own 64 KiB. */
+export const MAX_LIST_BYTES = 1024 * 1024;
+export const MAX_USERS = 2000;
+const out = (m) => { process.stdout.write(`${m}\n`); };
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const ID = /^[0-9a-f]{16}$/;
+const HOST = /^(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,62})(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,62}))*\.?|[0-9A-Fa-f:.]{2,45})$/;
+const ROLE_FROM = ["file", "default", "none"];
+/** The local command's next steps, as a replica's: each `mason user …` names the replica, so it runs against it. */
+export const onReplica = (steps, r) => steps.map(([command, ...what]) => [command.startsWith("mason user ") ? `${command} --replica ${replicaText(r)}` : command, ...what]);
+/** What to run after the service refused a request about a replica's users: the CLI's own, by the status (never the
+ *  service's `next`): sign in again for a 401 or 403, else the replica's users. */
+export const failureNext = (status, r) => status === 401 || status === 403 ? serviceNext(status) : [[`mason user list --replica ${replicaText(r)}`, "the replica's users"]];
+/** The request a subcommand is: the run's own `/api/users` request, under the replica's path. */
+export function requestOf(r, o) {
+    const base = `/v1/replicas/${r.org}/${r.name}/users`;
+    // a user's name is USER_NAME_RE's (checked before this): letters, digits, `_`, `.` and `-`, safe in a path as it is
+    switch (o.verb) {
+        case "list": return { method: "GET", path: `${base}?lastUsed=1` };
+        case "add": return { method: "POST", path: base, json: { name: o.name, ...(o.role !== undefined ? { role: o.role } : {}), ...(o.sets.length ? { set: [...o.sets] } : {}) } };
+        case "disable":
+        case "enable": return { method: "POST", path: `${base}/${o.name}/${o.verb}` };
+        case "remove": return { method: "DELETE", path: `${base}/${o.name}` };
+    }
+}
+// ------------------------------------------------------------------ the answers, held to the run's own shapes
+/** A string the service sends, as one line: null when it is not a string. */
+const line = (v, max, secrets) => typeof v === "string" ? serviceText(v, max, secrets) : null;
+/** A user's role fields, each consistent with the others (src/cli/roles.ts userRole): a role for `file` and `default`,
+ *  none for `none`, `readsNothing` only where there is none. */
+function roleOf(u) {
+    if (typeof u.roleFrom !== "string" || !ROLE_FROM.includes(u.roleFrom))
+        return null;
+    const roleFrom = u.roleFrom;
+    if (u.role !== undefined && (typeof u.role !== "string" || !ROLE_NAME_RE.test(u.role)))
+        return null;
+    if ((roleFrom === "none") !== (u.role === undefined))
+        return null;
+    if (u.readsNothing !== undefined && (u.readsNothing !== true || roleFrom !== "none"))
+        return null;
+    return { ...(typeof u.role === "string" ? { role: u.role } : {}), roleFrom, ...(u.readsNothing === true ? { readsNothing: true } : {}) };
+}
+/** A user's attributes: at most 64 names, each a value (one line, bounded) or a list of 1 to 100 of them. A value is a
+ *  value (a tenant's id), put to the exact test with every string (`carriesNoSecret`), so it is made one line here
+ *  without the quarter rule of free text, which a thousand random ids would trip by chance (PR 609's review). */
+function attributesOf(v) {
+    if (!obj(v) || Object.keys(v).length > 64)
+        return null;
+    const outv = {};
+    for (const [k, x] of Object.entries(v)) {
+        if (!ATTRIBUTE_NAME_RE.test(k))
+            return null;
+        if (typeof x === "string")
+            outv[k] = serviceText(x, 1000);
+        else if (Array.isArray(x) && x.length >= 1 && x.length <= 100 && x.every((y) => typeof y === "string"))
+            outv[k] = x.map((y) => serviceText(y, 1000));
+        else
+            return null;
+    }
+    return outv;
+}
+const names = (v) => Array.isArray(v) && v.length >= 1 && v.length <= 64 && v.every((x) => typeof x === "string" && ATTRIBUTE_NAME_RE.test(x));
+const timeOrNull = (v) => v === null || isServiceTime(v);
+/** One row of a list, as `listUsers` makes it (src/cli/user.ts `UserRow`); null when it is not that shape. */
+function rowOf(v) {
+    if (!obj(v))
+        return null;
+    const u = v;
+    if (typeof u.name !== "string" || !USER_NAME_RE.test(u.name) || typeof u.id !== "string" || !ID.test(u.id) || !isServiceTime(u.addedAt)
+        || !timeOrNull(u.removedAt) || !timeOrNull(u.disabledAt) || !timeOrNull(u.lastUsedAt) || typeof u.live !== "boolean")
+        return null;
+    // the URL a tool pastes, WITHOUT the password: its own name, then where the replica listens
+    if (u.url !== null && !(typeof u.url === "string" && u.url.length <= 600 && u.url.startsWith(`postgres://${u.name}@`)
+        && /^postgres:\/\/[a-z0-9_.-]+@(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\]):\d{1,5}\/[A-Za-z0-9%._~!*'()-]+(?:\?sslmode=require)?$/.test(u.url)))
+        return null;
+    const role = roleOf(u);
+    if (role === null)
+        return null;
+    const attributes = u.attributes === undefined ? undefined : attributesOf(u.attributes);
+    if (attributes === null)
+        return null;
+    if (u.missingAttributes !== undefined && !names(u.missingAttributes))
+        return null;
+    if (u.roleKnown !== undefined && (typeof u.roleKnown !== "boolean" || role.roleFrom !== "file"))
+        return null;
+    return { name: u.name, id: u.id, addedAt: u.addedAt, removedAt: u.removedAt, disabledAt: u.disabledAt, live: u.live, lastUsedAt: u.lastUsedAt,
+        url: u.url, ...role, ...(attributes !== undefined ? { attributes } : {}),
+        ...(u.missingAttributes !== undefined ? { missingAttributes: u.missingAttributes } : {}),
+        ...(typeof u.roleKnown === "boolean" ? { roleKnown: u.roleKnown } : {}) };
+}
+/** `GET …/users?lastUsed=1`'s answer: mason user list --json's shape (its `next` never read); null when it is not it. */
+export function heldList(json, secrets) {
+    if (!obj(json) || !Array.isArray(json.users) || json.users.length > MAX_USERS || !carriesNoSecret(json, secrets))
+        return null;
+    const users = [];
+    for (const v of json.users) {
+        const u = rowOf(v);
+        if (u === null)
+            return null;
+        users.push(u);
+    }
+    const note = (v) => v === null ? null : line(v, 500, secrets) ?? undefined;
+    const lastUsedNote = note(json.lastUsedNote), urlNote = note(json.urlNote);
+    const days = json.requestLogDays;
+    if (lastUsedNote === undefined || urlNote === undefined || !(days === null || (Number.isInteger(days) && days >= 1 && days <= 36500)))
+        return null;
+    return { users, lastUsedNote, urlNote, requestLogDays: days };
+}
+/** `POST …/users`'s answer: mason user add --json's shape with Mason up — where it listens, the URL rebuilt here by the
+ *  one builder and equal to the service's —, for the name asked; null when it is not it. */
+export function heldAdded(json, asked, secrets) {
+    if (!obj(json) || !carriesNoSecret(json, secrets, ["password", "url", "psql"]))
+        return null;
+    const a = json;
+    if (a.user !== asked || typeof a.id !== "string" || !ID.test(a.id) || !isServiceTime(a.addedAt))
+        return null;
+    // the password is the user's, by its one grammar: its id, then its MAC
+    if (typeof a.password !== "string" || !new RegExp(`^mason_${a.id}_[0-9a-f]{32}$`).test(a.password))
+        return null;
+    if (typeof a.database !== "string" || databaseNameProblem(a.database) !== null || serviceText(a.database, 63) !== a.database)
+        return null;
+    if (typeof a.host !== "string" || !HOST.test(a.host) || !Number.isInteger(a.port) || a.port < 1 || a.port > 65535)
+        return null;
+    if (a.sslmode !== "require" && a.sslmode !== "disable")
+        return null;
+    const url = connectionUrl({ url: "", host: a.host, port: a.port, database: a.database, ...(a.sslmode === "require" ? { sslmode: "require" } : {}) }, asked, a.password);
+    if (a.url !== url || a.psql !== psqlLine(url))
+        return null;
+    const role = roleOf(a);
+    if (role === null)
+        return null;
+    const attributes = a.attributes === undefined ? undefined : attributesOf(a.attributes);
+    if (attributes === null)
+        return null;
+    return { user: asked, id: a.id, addedAt: a.addedAt, password: a.password, database: a.database, url, psql: psqlLine(url), host: a.host, port: a.port, sslmode: a.sslmode,
+        ...role, ...(attributes !== undefined ? { attributes } : {}) };
+}
+/** A user as disable, enable and remove name it: the name asked, its id, when it was added, and `more` times. */
+function userOf(v, asked, more) {
+    if (!obj(v) || v.name !== asked || typeof v.id !== "string" || !ID.test(v.id) || !isServiceTime(v.addedAt) || !more.every((k) => isServiceTime(v[k])))
+        return null;
+    return { name: asked, id: v.id, addedAt: v.addedAt, ...Object.fromEntries(more.map((k) => [k, v[k]])) };
+}
+export function heldDisabled(json, asked, secrets) {
+    if (!obj(json) || typeof json.already !== "boolean" || !carriesNoSecret(json, secrets))
+        return null;
+    const d = userOf(json.disabled, asked, ["disabledAt"]);
+    return d === null ? null : { disabled: d, already: json.already };
+}
+export function heldEnabled(json, asked, secrets) {
+    if (!obj(json) || typeof json.already !== "boolean" || !carriesNoSecret(json, secrets))
+        return null;
+    const e = userOf(json.enabled, asked, []);
+    return e === null ? null : { enabled: e, already: json.already };
+}
+export function heldRemoved(json, asked, secrets) {
+    if (!obj(json) || !carriesNoSecret(json, secrets))
+        return null;
+    const r = userOf(json.removed, asked, ["removedAt"]);
+    return r === null ? null : { removed: r };
+}
+// ------------------------------------------------------------------ the command
+/** What each subcommand asked, in the words of a failure outside the contract (`unexpected`). */
+const STEP = { list: "the replica's users were asked for", add: "a user was added", disable: "a user was disabled", enable: "a user was enabled", remove: "a user was removed" };
+/** `mason user <verb> … --replica <org>/<name>`: one request, its answer held and printed as the local command prints it. */
+export async function hostedUser(r, o) {
+    const outStyle = serviceStyle(styleOut());
+    const fail = (f) => failed("user", f, { json: o.json, style: serviceStyle(styleErr()) });
+    const service = serviceOf();
+    if (isFailure(service))
+        return fail(service);
+    const token = tokenFor(service, { asked: "a replica's users are asked for", again: `mason user ${o.verb}` });
+    if (isFailure(token))
+        return fail(token);
+    // from here every byte written is put to the exact test against the token (src/cli/output-gate.ts); add prints the
+    // password it made, so a password's shape is its answer's there
+    holdOutput({ command: "user", json: o.json, secrets: [token], passwords: o.verb !== "add" });
+    const secrets = [token];
+    const req = requestOf(r, o);
+    const a = await call(service, req.method, req.path, { token, ...(req.json !== undefined ? { json: req.json } : {}), ...(o.verb === "list" ? { maxBytes: MAX_LIST_BYTES } : {}) });
+    if (isFailure(a))
+        return fail(a);
+    const refused = (x) => serviceFailure(x, secrets, (status) => failureNext(status, r)) ?? unexpected(service, x, STEP[o.verb]);
+    if (a.status !== 200)
+        return fail(refused(a));
+    const outside = () => fail(unexpected(service, a, STEP[o.verb]));
+    const print = (value, next, text) => {
+        out(o.json ? jsonText(USER, value, next) : text());
+        return 0;
+    };
+    switch (o.verb) {
+        case "list": {
+            const l = heldList(a.json, secrets);
+            if (l === null)
+                return outside();
+            const next = onReplica(listNext(l.users), r);
+            return print({ ...l }, next, () => listText(replicaText(r), l, NO_ROLES, next, outStyle));
+        }
+        case "add": {
+            const added = heldAdded(a.json, o.name, secrets);
+            // the service answered 200: the replica may have made the user, whose password nobody has now been shown
+            if (added === null) {
+                const f = unexpected(service, a, STEP[o.verb]);
+                return fail({ ...f, why: `${f.why}; the replica may have added ${o.name} all the same, and its password was not shown`,
+                    fix: `mason user list --replica ${replicaText(r)} says whether it did; if so, mason user remove ${o.name} --replica ${replicaText(r)}, then add it again`,
+                    next: [[`mason user list --replica ${replicaText(r)}`, "the replica's users"]] });
+            }
+            const next = onReplica(addedNext(added.user, true), r);
+            return print({ ...added }, next, () => addedReport(added, { roles: NO_ROLES, listener: null, next }, outStyle));
+        }
+        case "disable": {
+            const d = heldDisabled(a.json, o.name, secrets);
+            if (d === null)
+                return outside();
+            const next = onReplica(disabledNext(d.disabled.name), r);
+            return print({ ...d }, next, () => disabledReport(d, true, next, outStyle));
+        }
+        case "enable": {
+            const e = heldEnabled(a.json, o.name, secrets);
+            if (e === null)
+                return outside();
+            const next = onReplica(enabledNext(e.enabled.name), r);
+            return print({ ...e }, next, () => enabledReport(e, next, outStyle));
+        }
+        case "remove": {
+            const x = heldRemoved(a.json, o.name, secrets);
+            if (x === null)
+                return outside();
+            const next = onReplica(REMOVED_NEXT, r);
+            return print({ ...x }, next, () => removedReport(x, true, next, outStyle));
+        }
+    }
+}