@mason-data/cli 0.9.0 → 0.10.0

package/dist/src/cli/replica.js

@@ -4,14 +4,52 @@ import { isFailure, serviceText, whoAmI } from "./hosted.js";
 export const REPLICA_PART = /^[a-z0-9][a-z0-9-]{0,62}$/;
 export const REPLICA_ENV = "MASON_REPLICA";
 export const replicaText = (r) => `${r.org}/${r.name}`;
-/** The replica the command means: `--replica`, else `MASON_REPLICA`; null when neither names one, a Failure when it is
- *  not `<org>/<name>` (never repeated beyond 200 characters, made printable). `usage`: the command's, said after a wrong
- *  `--replica`. */
-export function replicaOf(flag, usage, env = process.env) {
+/**
+ * THE REPLICA THE COMMAND MEANS, ONE RESOLVER FOR EVERY COMMAND THAT NAMES ONE (`mason deploy`, `mason user …
+ * --replica`, `mason token create`, `mason replica create | status`): the command's own argument where it takes one
+ * (`mason replica status acme/shop`), else `--replica`, else `MASON_REPLICA`; null when none names one, a Failure when
+ * it is not `<org>/<name>` (never repeated beyond 200 characters, made printable), or when the argument and `--replica`
+ * name two replicas. `usage`: the command's, said after a wrong line.
+ *
+ * WHEN THE ENVIRONMENT CHOSE THE TARGET IT IS SAID, on stderr (`say`): an agent inherits an environment it may never
+ * read, and `MASON_REPLICA` exported turns `mason user add` from this project's users to a replica's.
+ */
+export function replicaOf(flag, usage, env = process.env, o = {}) {
+    if (o.argument !== undefined) {
+        const r = replicaNamed(o.argument, "argument", usage);
+        if (flag === undefined || "message" in r)
+            return r;
+        const f = replicaNamed(flag, "--replica", usage);
+        if ("message" in f)
+            return f;
+        if (replicaText(f) === replicaText(r))
+            return r;
+        return { message: `the replica is named twice: ${replicaText(r)} and --replica ${replicaText(f)}`, code: "usage", fix: `name one: ${replicaText(r)}, or --replica ${replicaText(f)}`, usage };
+    }
     const from = flag !== undefined ? "--replica" : env[REPLICA_ENV] !== undefined ? REPLICA_ENV : null;
     if (from === null)
         return null;
-    return replicaNamed((from === "--replica" ? flag : env[REPLICA_ENV]) ?? "", from, usage);
+    const r = replicaNamed((from === "--replica" ? flag : env[REPLICA_ENV]) ?? "", from, usage);
+    if (!("message" in r) && r.from === REPLICA_ENV)
+        (o.say ?? sayStderr)(envChoseText(r));
+    return r;
+}
+/** What is said on stderr when `MASON_REPLICA` chose the replica (a name `REPLICA_PART` holds: safe to print). */
+export const envChoseText = (r) => `using ${REPLICA_ENV}=${replicaText(r)} (--replica names another; unset ${REPLICA_ENV} for none)`;
+const sayStderr = (line) => { process.stderr.write(`${line}\n`); };
+/** The organisation the command means: its own argument (`mason replica list acme`), else `--org`; null when neither
+ *  names one, a wrong line's Failure when one is not a slug or the two differ. */
+export function orgOf(flag, argument, usage) {
+    const named = [argument, flag].filter((x) => x !== undefined).map((x) => orgNamed(x, usage));
+    const bad = named.find((x) => typeof x !== "string");
+    if (bad !== undefined)
+        return bad;
+    const [a, b] = named;
+    if (a === undefined)
+        return null;
+    if (b !== undefined && a !== b)
+        return { message: `the organisation is named twice: ${a} and --org ${b}`, code: "usage", fix: `name one: ${a}, or --org ${b}`, usage };
+    return a;
 }
 /** `raw` as a replica's name, `<org>/<name>`, each part `REPLICA_PART`: the one grammar of `--replica`, `MASON_REPLICA`
  *  and a command's own argument (`mason replica status <org>/<name>`); a Failure otherwise, a wrong line's (`usage`)

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

@@ -165,6 +165,11 @@ export function dropStatements(o) {
     return `SELECT pg_drop_replication_slot('${o.slot}') FROM pg_replication_slots WHERE slot_name = '${o.slot}' AND NOT active;` +
         (o.owned ? ` DROP PUBLICATION IF EXISTS ${o.publication};` : "");
 }
+/** The statement that lists Mason's replication slots on a database (each named `mason_…`, `replicationNames`), for a
+ *  person to find the one to drop when its name is not known (a hosted replica's record of it could not be read). */
+export function listSlotsStatement() {
+    return "SELECT slot_name, database, active FROM pg_replication_slots WHERE left(slot_name, 6) = 'mason_';";
+}
 /**
  * WHAT THE RECORD NAMES THAT THIS START NO LONGER READS, to drop before the record names the new one (each holds what
  * Mason made on a database nothing would drop otherwise): a slot under another name (the sources file renamed) goes

package/dist/src/cli/request-filter.js

@@ -1,6 +1,7 @@
 import { OUTCOMES } from "../api/request-log.js";
 import { parseRequestCursor, requestCursor } from "../duck/requests.js";
 import { didYouMean } from "../lib/did-you-mean.js";
+import { parseDuration } from "../lib/table-sync.js";
 /** How many requests a read returns unless it says. */
 export const DEFAULT_REQUEST_LIMIT = 40;
 export const MAX_REQUEST_LIMIT = 10_000;
@@ -12,21 +13,30 @@ export const MAX_SEARCH = 200;
 /** How many sync events a read returns unless it says, and the most it may. */
 export const DEFAULT_EVENT_LIMIT = 40;
 export const MAX_EVENT_LIMIT = MAX_REQUEST_LIMIT;
-const AGE = /^(\d+)(s|m|h|d)$/;
-const AGE_MS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
 /** a date, or a date and time with its zone (a time without one would be read in this machine's zone: refused) */
 const ISO = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?(Z|[+-]\d{2}:?\d{2}))?$/;
+/** The furthest a JavaScript Date reaches from 1970, either way (ECMA-262 21.4.1.1). */
+const MAX_TIME_MS = 8.64e15;
 const usage = (message, fix) => ({ message, code: "usage", ...(fix !== undefined ? { fix } : {}) });
 export const QUERY_NAMES = (k) => k;
 /**
  * THE TIME GRAMMAR, ONE FOR EVERY ENTRANCE (`--since` / `--until` of mason logs and mason usage, and the run's `since` and
  * `until` of /api/requests, /api/events, /api/usage and /api/logs): an ISO 8601 date or time with its zone, or an age
- * before `now` (30s, 30m, 2h, 7d), as an ISO time; a time with no zone is refused, as is anything else.
+ * before `now` (30s, 30m, 2h, 7d, 2 hours), read by the command line's one duration grammar (src/lib/table-sync.ts
+ * `parseDuration`) with its unit written, as an ISO time; a time with no zone is refused, as is anything else. A bare
+ * number is refused here, as it always was: as a TIME it reads as well as a Unix timestamp as an age in seconds.
  */
 export function timeOf(name, text, now) {
-    const age = AGE.exec(text.trim());
-    if (age !== null)
-        return new Date(now - Number(age[1]) * AGE_MS[age[2]]).toISOString();
+    const age = Number.isFinite(Number(text.trim())) ? null : parseDuration(text, { zero: true });
+    if (age !== null && !("problem" in age)) {
+        // an age past what a time can hold (Date's ±8.64e15 ms) is the command line's mistake, refused as one: never a throw,
+        // which the run's API would answer 500
+        const at = now - age.seconds * 1000;
+        if (!Number.isFinite(at) || Math.abs(at) > MAX_TIME_MS) {
+            return usage(`${name} ${JSON.stringify(text)} is further back than a time reaches`, "a shorter age (30m, 2h, 7d), or an ISO 8601 date or time with its zone (2026-10-28, 2026-10-28T09:00:00Z)");
+        }
+        return new Date(at).toISOString();
+    }
     const t = ISO.test(text.trim()) ? Date.parse(text.trim()) : NaN;
     if (Number.isNaN(t)) {
         return usage(`${name} ${JSON.stringify(text)} is not a time`, "an age (30m, 2h, 7d) or an ISO 8601 date or time with its zone (2026-10-28, 2026-10-28T09:00:00Z)");

package/dist/src/cli/run-server.js

@@ -34,7 +34,7 @@ import { phaseCounts, readiness, syncTotals, tableSync } from "./readiness.js";
 import { restartsFact } from "./supervise.js";
 import { withRestarts } from "../duck/events.js";
 import { NO_ROLES } from "../duck/grants.js";
-import { addedNext, addUser, attributesToAdd, disabledNext, disableUser, enabledNext, enableUser, listUsers, removeUser, REMOVED_NEXT, roleToAdd, withLastUsed } from "./user.js";
+import { addedNext, addUser, attributesToAdd, disabledNext, disableUser, enabledNext, enableUser, fromNext, listUsers, rangesText, removeUser, REMOVED_NEXT, roleToAdd, setUserFrom, withLastUsed } from "./user.js";
 import { userRole } from "./roles.js";
 import { postgresFacts, postgresLink } from "./pg-url.js";
 import { catalogTable, parseSourceText, shownPath } from "./sources.js";
@@ -776,6 +776,8 @@ export function createRunServer(ctx) {
                         throw new Refusal(400, "send { name, role }: the role's name, a string");
                     if (body.set !== undefined && !(Array.isArray(body.set) && body.set.every((x) => typeof x === "string")))
                         throw new Refusal(400, "send { name, role, set }: set is a list of \"attribute=value\" strings, as mason user add --set takes them");
+                    if (body.from !== undefined && !(Array.isArray(body.from) && body.from.every((x) => typeof x === "string")))
+                        throw new Refusal(400, "send { name, from }: from is a list of address ranges (\"10.0.0.0/16\"), as mason user add --from takes them");
                     // the role must be one the roles file names NOW (src/cli/user.ts roleToAdd): refused before anything is written
                     const roleProblem = body.role === undefined ? null : roleToAdd(body.role, ctx.roles?.() ?? NO_ROLES);
                     if (roleProblem !== null) {
@@ -791,7 +793,7 @@ export function createRunServer(ctx) {
                     }
                     // mason user add --json's shape: its password, once, and the URL to paste (this run is up, so it has one)
                     const r = addUser(ctx.users.file, ctx.users.apiKey, body.name, { link: postgresLink(ctx.users.postgresUrl), database: ctx.users.database, roles: ctx.roles?.() ?? NO_ROLES,
-                        ...(typeof body.role === "string" ? { role: body.role } : {}), attributes: attributes.values });
+                        ...(typeof body.role === "string" ? { role: body.role } : {}), attributes: attributes.values, ...(Array.isArray(body.from) ? { from: body.from } : {}) });
                     if ("message" in r) {
                         sendFailure(res, statusOf(r), r);
                         return;
@@ -800,6 +802,27 @@ export function createRunServer(ctx) {
                     ctx.log(`user ${added.user} added${replaced ? " (in place of one the API key's rotation had removed)" : ""}`);
                     sendJson(res, 200, { ...added, next: nextJson(addedNext(added.user, true)) });
                 }
+                else if (req.method === "POST" && /^\/api\/users\/[^/]+\/from$/.test(url.pathname)) {
+                    // mason user from --json's shape, through its own function: the user's address ranges replaced (null: any address)
+                    let name;
+                    try {
+                        name = decodeURIComponent(url.pathname.split("/")[3]);
+                    }
+                    catch {
+                        throw new Refusal(400, `${url.pathname} does not name a user: POST /api/users/<name>/from`);
+                    }
+                    const body = JSON.parse(await readBody(req, 64 * 1024));
+                    if (!(body.from === null || (Array.isArray(body.from) && body.from.every((x) => typeof x === "string"))))
+                        throw new Refusal(400, "send { from }: a list of address ranges (\"10.0.0.0/16\"), or null for any address");
+                    const r = setUserFrom(ctx.users.file, name, body.from);
+                    if ("message" in r) {
+                        sendFailure(res, statusOf(r), r);
+                        return;
+                    }
+                    if (!r.already)
+                        ctx.log(`user ${r.changed.name} connects from ${rangesText(r.changed.from)}`);
+                    sendJson(res, 200, { ...r, next: nextJson(fromNext(r.changed.name, r.changed.from)) });
+                }
                 else if (req.method === "POST" && /^\/api\/users\/[^/]+\/(disable|enable)$/.test(url.pathname)) {
                     // mason user disable|enable --json's shape, through its own functions: kept, its password unchanged
                     const [, , , encoded, verb] = url.pathname.split("/");

package/dist/src/cli/secret-input.js

@@ -0,0 +1,193 @@
+/**
+ * A SECRET READ FROM THE PERSON OR THE PIPE, NEVER FROM A FLAG, AN ARGUMENT OR A FILE (`mason replica create`'s database
+ * URL, issue 720): on a terminal a hidden prompt, otherwise stdin read whole. Node's own TTY handling, no dependency.
+ *
+ *   - THE PROMPT (stdin a terminal): the question on stderr, stdin in raw mode, so the terminal echoes nothing and keeps
+ *     no line of it; each key is read here. Enter ends it; Ctrl-C, or Ctrl-D or Enter on an empty line, cancels; Backspace
+ *     and Ctrl-U edit; a terminal's escape sequences (a bracketed paste's markers, an arrow) are dropped. The terminal is
+ *     put back as it was on EVERY way out — the answer, a cancel, an error of the stream, its end, a signal (SIGINT,
+ *     SIGTERM, SIGHUP while raw mode keeps Ctrl-C from being one), and the process's exit.
+ *   - THE PIPE (stdin not a terminal): read whole, bounded at `max` bytes and by a time limit (a pipe left open and
+ *     silent never holds the command), one trailing newline (`\n` or `\r\n`) trimmed; more than one line is refused.
+ *
+ * Nothing read is ever written anywhere by this module: what went wrong is said by kind, never by value.
+ */
+import { StringDecoder } from "node:string_decoder";
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+/**
+ * THE HIDDEN PROMPT: `question` on `output` (stderr), a line read from `input` (a terminal) in raw mode, echoing nothing.
+ * At most `max` characters are kept; a longer line is read to its end (so nothing of it is left for the shell to echo)
+ * and refused.
+ */
+export function readHidden(input, output, question, max, signals = process) {
+    return new Promise((resolve, reject) => {
+        const wasRaw = input.isRaw === true;
+        const decoder = new StringDecoder("utf8");
+        let line = [];
+        let tooLong = false;
+        let escape = "";
+        let ended = false;
+        const restore = () => { if (!wasRaw)
+            input.setRawMode?.(false); };
+        const finish = (r) => {
+            if (ended)
+                return;
+            ended = true;
+            input.removeListener("data", onData);
+            input.removeListener("end", onEnd);
+            input.removeListener("close", onEnd);
+            input.removeListener("error", onError);
+            for (const s of SIGNALS)
+                signals.removeListener(s, onSignal);
+            signals.removeListener("exit", restore);
+            try {
+                restore();
+            }
+            finally {
+                input.pause();
+                // the person's Enter was not echoed: the next line starts on a line of its own
+                output.write("\n");
+                line = [];
+                if (r instanceof Error)
+                    reject(r);
+                else
+                    resolve(r);
+            }
+        };
+        const onSignal = () => finish({ none: "cancelled" });
+        const onEnd = () => finish({ none: line.length ? "closed" : "cancelled" });
+        const onError = (e) => finish(e);
+        const onData = (chunk) => {
+            const text = typeof chunk === "string" ? chunk : decoder.write(chunk);
+            for (const c of text) {
+                if (ended)
+                    return;
+                // a terminal's escape sequence (an arrow, a bracketed paste's markers, a title report): dropped whole
+                if (escape === "esc") {
+                    escape = c === "[" ? "csi" : c === "]" ? "osc" : "";
+                    continue;
+                }
+                if (escape === "csi") {
+                    if (c >= "@" && c <= "~")
+                        escape = "";
+                    continue;
+                }
+                if (escape === "osc") {
+                    if (c === "\x07" || c === "\x1b")
+                        escape = "";
+                    continue;
+                }
+                if (c === "\x1b") {
+                    escape = "esc";
+                    continue;
+                }
+                if (c === "\r" || c === "\n") {
+                    finish(tooLong ? { none: "too_long" } : line.length === 0 ? { none: "empty" } : { value: line.join("") });
+                    return;
+                }
+                if (c === "\x03") {
+                    finish({ none: "cancelled" });
+                    return;
+                }
+                if (c === "\x04") {
+                    if (line.length === 0 && !tooLong) {
+                        finish({ none: "cancelled" });
+                        return;
+                    }
+                    continue;
+                }
+                if (c === "\x7f" || c === "\b") {
+                    line.pop();
+                    continue;
+                }
+                if (c === "\x15") {
+                    line = [];
+                    tooLong = false;
+                    continue;
+                }
+                if (c < " ")
+                    continue;
+                if (line.length >= max) {
+                    tooLong = true;
+                    continue;
+                }
+                line.push(c);
+            }
+        };
+        try {
+            if (input.setRawMode === undefined)
+                throw new Error("stdin is a terminal that cannot turn its echo off");
+            // the question first, then echo off: nothing typed before it is shown as asked
+            output.write(question);
+            input.setRawMode(true);
+            for (const s of SIGNALS)
+                signals.on(s, onSignal);
+            signals.on("exit", restore);
+            input.on("data", onData);
+            input.on("end", onEnd);
+            input.on("close", onEnd);
+            input.on("error", onError);
+            input.resume();
+        }
+        catch (e) {
+            finish(e instanceof Error ? e : new Error(String(e)));
+        }
+    });
+}
+/**
+ * THE PIPE: `input` read whole, at most `max` bytes after one trailing newline is trimmed, within `timeoutMs`. Empty,
+ * more than one line, longer than `max`, or nothing by the time limit, each said by kind.
+ */
+export function readPiped(input, max, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let bytes = 0;
+        let ended = false;
+        const finish = (r) => {
+            if (ended)
+                return;
+            ended = true;
+            clearTimeout(timer);
+            input.removeListener("data", onData);
+            input.removeListener("end", onEnd);
+            input.removeListener("error", onError);
+            input.pause();
+            if (r instanceof Error)
+                reject(r);
+            else
+                resolve(r);
+        };
+        const timer = setTimeout(() => finish({ none: "timeout" }), timeoutMs);
+        // the newline a shell's echo or a file ends with is not the URL's: room for it, then the bound
+        const most = max + 2;
+        const onData = (chunk) => {
+            const b = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+            bytes += b.length;
+            if (bytes > most) {
+                finish({ none: "too_long" });
+                return;
+            }
+            chunks.push(b);
+        };
+        const onEnd = () => {
+            let text = Buffer.concat(chunks).toString("utf8");
+            chunks.length = 0;
+            if (text.endsWith("\r\n"))
+                text = text.slice(0, -2);
+            else if (text.endsWith("\n"))
+                text = text.slice(0, -1);
+            if (text === "")
+                return finish({ none: "empty" });
+            if (/[\r\n]/.test(text))
+                return finish({ none: "lines" });
+            if (Buffer.byteLength(text, "utf8") > max)
+                return finish({ none: "too_long" });
+            finish({ value: text });
+        };
+        const onError = (e) => finish(e);
+        input.on("data", onData);
+        input.on("end", onEnd);
+        input.on("error", onError);
+        input.resume();
+    });
+}

package/dist/src/cli/serve.js

@@ -59,6 +59,8 @@ export const SERVE = {
     DATABASE_URL=postgres://mason:…@db.internal:5432/app MASON_API_KEY=… mason serve
     docker compose exec mason mason add public.orders     beside it, in its container
 
+  --json   a refusal to start as data: { error, next }; once it serves, its output is its log
+
   Settings (the environment):
     DATABASE_URL            the database to sync from, as the sources file's url: \${DATABASE_URL} names it (the variable
                             the file names is required); read-only: SELECTs, or a replication slot
@@ -98,8 +100,6 @@ export const SERVE = {
     UV_THREADPOOL_SIZE      threads for running statements, one each, 1 to 1024 (default 32, lowered to fit a limit
                             on threads; one that does not fit, or is no such number, refuses the start)
 
-  --json   a refusal to start as data: { error, next }; once it serves, its output is its log
-
   Exit status: 0 stopped by SIGTERM or SIGINT; 1 it could not start (said); 2 a wrong command line.
 `,
     options: { json: { type: "boolean", default: false } },

package/dist/src/cli/share.js

@@ -25,6 +25,7 @@ import { alive } from "./runs.js";
 import { appEnvValue } from "../lib/dotenv.js";
 import { newSharePassword, shareSecret } from "./share-run.js";
 import { probeShare, startTunnel, sweepTunnelFiles, TOKEN_RE, TUNNELS, tunnelPlan } from "./tunnel.js";
+import { parseDuration } from "../lib/table-sync.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const say = (m) => { process.stderr.write(`${m}\n`); };
 const DEFAULT_TIMEOUT_S = 30;
@@ -35,12 +36,22 @@ export const SHARE = {
     needs: "run",
     name: "share",
     summary: "share the synced data with a tool outside this machine: a temporary address, TLS end to end, a password for this run",
-    usage: `usage: mason share [--role <role>] [--via pinggy|bore] [--timeout <seconds>] [--json]
+    usage: `usage: mason share [--role <role>] [--via pinggy|bore] [--timeout <duration>] [--json]
 
   For a BI tool in the cloud, which cannot reach 127.0.0.1: opens a temporary public address for this project's Postgres
   API, through a free tunnel service, and prints what to type into the tool. It stays in the foreground: Ctrl-C ends
   the share. Your local tools notice nothing: the share has a socket of its own, and no session is dropped.
 
+    mason share
+    mason share --role sales
+    mason share --via bore
+
+  --role <role>       what it reads: a role of mason/roles.yml
+  --via <tunnel>      pinggy (default) or bore
+  --timeout <duration>  how long the tunnel has to give its address (default ${DEFAULT_TIMEOUT_S}s; a bare number is
+                      seconds; 30s, 2m); past it, exit 124
+  --json              as data: its shape is at the end
+
   The socket requires TLS of every connection, so a service that forwards bytes cannot read them. The certificate is
   self-signed (the tool connects with sslmode=require, and checks no certificate), so a malicious service could sit in
   the middle of the handshake: this is for trying Mason, on data you may send that way. mason serve on a host is the
@@ -56,17 +67,10 @@ export const SHARE = {
   line is visible to every user of the machine), a paid Pinggy token, keeps the address, so a tunnel that drops is opened
   again by itself, the password unchanged. --via bore needs bore (cargo install bore-cli).
 
-    mason share
-    mason share --role sales
-    mason share --via bore
-
-  --role <role>       what it reads: a role of mason/roles.yml
-  --via <tunnel>      pinggy (default) or bore
-  --timeout <s>       how long the tunnel has to give its address (default ${DEFAULT_TIMEOUT_S})
-  --json              as data, once the address is known: { share: { host, port, database, user, password, sslmode,
-                      fingerprint, role, reads, via, endsAt (ISO 8601, or null), verified (the address answered with this
-                      share's certificate; false: it could not be reached from this machine) }, next }; the command
-                      then holds the share: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
+  The --json answer, once the address is known: { share: { host, port, database, user, password, sslmode,
+    fingerprint, role, reads, via, endsAt (ISO 8601, or null), verified (the address answered with this
+    share's certificate; false: it could not be reached from this machine) }, next }; the command
+    then holds the share: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
 `,
     options: { role: { type: "string" }, via: { type: "string" }, timeout: { type: "string" }, json: { type: "boolean", default: false } },
     json: ["share", "next"],
@@ -135,9 +139,10 @@ export async function share(argv) {
     const via = (v.via ?? "pinggy");
     if (!TUNNELS.includes(via))
         return failed("share", { message: `--via must be ${TUNNELS.join(" or ")}, not ${JSON.stringify(v.via)}`, code: "usage", usage: SHARE.usage }, { json });
-    const timeoutS = v.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(v.timeout);
-    if (!Number.isFinite(timeoutS) || timeoutS <= 0)
-        return failed("share", { message: `--timeout is a number of seconds, not ${JSON.stringify(v.timeout)}`, code: "usage" }, { json });
+    const read = parseDuration(v.timeout ?? String(DEFAULT_TIMEOUT_S));
+    if ("problem" in read)
+        return failed("share", { message: `--timeout ${read.problem}`, code: "usage", usage: SHARE.usage }, { json });
+    const timeoutS = read.seconds;
     const w = await reach(SHARE, json);
     if (w === null || !("run" in w))
         return 1;

package/dist/src/cli/source-role.js

@@ -187,29 +187,28 @@ function via(x) {
         view: ` (a view that writes ${x.entry})`, rule: ` (its rules write ${x.entry})` };
     return said[x.kind];
 }
-const WHY = "Mason only reads, so a role that may write lets a Mason bug or a stolen URL change your database";
+const WHY = "Mason only reads, but, for security reasons, we recommend using a role that only reads";
 /** The checks of the role, from its facts: one warning per code that applies, else one line saying it only reads. */
 export function roleChecks(f, ask) {
     const fix = readOnlyFix(f, ask);
-    const warn = (code, detail) => ({ name: "role", ok: true, warn: true, code, detail: `${detail}. ${WHY}: sync as a role that only reads`, fix });
+    const warn = (code, detail) => ({ name: "role", ok: true, warn: true, code, detail: `${detail}. ${WHY}`, fix });
     const out = [];
     const supers = f.roles.filter((r) => r.superuser);
     if (supers.length) {
         // a superuser may do everything: what else it holds follows from it, and is not said again
         const self = supers.some((r) => r.self);
-        out.push(warn("role_superuser", self ? `${f.user} is a superuser: it may write to, alter or drop anything on this database`
-            : `${f.user} is a member of ${list(supers.map((r) => r.name))}, a superuser: it may SET ROLE to it and write to, alter or drop anything on this database`));
+        out.push(warn("role_superuser", self ? `${f.user} is a superuser`
+            : `${f.user} is a member of ${list(supers.map((r) => r.name))}, a superuser`));
         return out;
     }
     const bypass = f.roles.filter((r) => r.bypassrls);
     if (bypass.length) {
-        out.push(warn("role_bypassrls", `${f.user} has BYPASSRLS${route(bypass.filter((r) => !r.self).map((r) => r.name))}: row-level security does not apply to it, on any table`));
+        out.push(warn("role_bypassrls", `${f.user} has BYPASSRLS${route(bypass.filter((r) => !r.self).map((r) => r.name))}`));
     }
     const owned = f.relations.filter((x) => x.owned);
     if (owned.length) {
         const others = [...new Set(owned.map((x) => x.owner).filter((o) => o !== f.user))];
-        out.push(warn("role_owns_table", `${f.user} owns ${list(owned.map((x) => `${x.name}${via(x)}`))}${route(others)}: ` +
-            "an owner may write to, alter or drop a table whatever is granted"));
+        out.push(warn("role_owns_table", `${f.user} owns ${list(owned.map((x) => `${x.name}${via(x)}`))}${route(others)}`));
     }
     // an owner holds every privilege on its table: the owner's line said it
     const writable = f.relations.filter((x) => !x.owned && x.privileges.length > 0);
@@ -223,18 +222,18 @@ export function roleChecks(f, ask) {
     }
     const creates = f.schemas.filter((s) => s.create.length > 0 || s.publicCreate);
     if (creates.length) {
-        const held = creates.map((s) => `CREATE in schema ${s.name}${s.owned ? ` (${s.owner === f.user ? "it owns the schema" : `${s.owner}, which owns the schema`}: it may drop what is in it too)` : route([...s.create.filter((r) => r !== f.user), ...(s.publicCreate ? ["PUBLIC"] : [])])}`);
-        out.push(warn("role_creates_in_schema", `${f.user} may ${held.join("; ")}: it may make tables and functions beside the synced ones`));
+        const held = creates.map((s) => `CREATE in schema ${s.name}${s.owned ? ` (${s.owner === f.user ? "it owns the schema" : `${s.owner}, which owns the schema`})` : route([...s.create.filter((r) => r !== f.user), ...(s.publicCreate ? ["PUBLIC"] : [])])}`);
+        out.push(warn("role_creates_in_schema", `${f.user} may ${held.join("; ")}`));
     }
     if (f.foreignTables.length || f.mappedServers.length) {
         const held = [...(f.foreignTables.length ? [`may write the foreign table(s) ${list(f.foreignTables)}`] : []),
-            ...(f.mappedServers.length ? [`has a user mapping (its own or PUBLIC's) on ${list(f.mappedServers)}, which it may use`] : [])];
-        out.push(warn("role_reaches_foreign_server", `${f.user} ${held.join(", and ")}: what it sends there runs as the mapping's user, and the server may be this very database`));
+            ...(f.mappedServers.length ? [`has a user mapping (its own or PUBLIC's) on ${list(f.mappedServers)}`] : [])];
+        out.push(warn("role_reaches_foreign_server", `${f.user} ${held.join(", and ")}`));
     }
     if (f.adminOf.length || f.createRole || f.serverRoles.length) {
-        const held = [...(f.adminOf.length ? [`has ADMIN OPTION on ${list(f.adminOf)}: it may grant itself that role and its privileges`] : []),
-            ...(f.createRole ? ["has CREATEROLE, which before Postgres 16 lets it grant itself any role but a superuser"] : []),
-            ...(f.serverRoles.length ? [`holds ${list(f.serverRoles)}: the server's programs or files, as its operating-system user`] : [])];
+        const held = [...(f.adminOf.length ? [`has ADMIN OPTION on ${list(f.adminOf)}`] : []),
+            ...(f.createRole ? ["has CREATEROLE"] : []),
+            ...(f.serverRoles.length ? [`holds ${list(f.serverRoles)}`] : [])];
         out.push(warn("role_may_become_another", `${f.user} ${held.join("; ")}`));
     }
     // SECURITY DEFINER code: what it writes is in its body, which the catalog does not say, so it is LISTED for a person
@@ -263,7 +262,7 @@ function definerLine(f) {
         return `${d.name} runs as ${d.owner}${d.ownerSuperuser ? ", a superuser" : ", which may write the synced tables"}: ${how.join("; ")}`;
     });
     return `may run ${f.definers.length} SECURITY DEFINER function(s) of roles that may write the synced tables — ${each.join("; ")}. ` +
-        "What they write is not known (it is in their bodies, which the catalog does not read): review each, whether it writes a synced table and who may reach it";
+        "We recommend reviewing each: whether it writes a synced table, and who may call it";
 }
 /** The line a check is when the role could not be asked: said, never taken for "only reads". */
 export function roleUnknown(why) {

package/dist/src/cli/sources.js

@@ -42,6 +42,15 @@ export const SOURCES_DIR = "sources";
 const KEYS = ["kind", "url", "database", "sync", "publication", "tables"];
 const ENTRY_KEYS = ["columns", "exclude", "key", "sync"];
 const ENV_REF = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/**
+ * A `${NAME}` naming one of Mason's own settings (`MASON_*`, such as `MASON_API_KEY`): refused where the file is read,
+ * before anything resolves it, because a project may be someone else's and the value would be printed or sent as the
+ * publication's name (issue 718). `url:` keeps `${MASON_DATABASE_URL}`, the source's URL `mason init` reads and writes.
+ */
+const ownSetting = (name, key) => !/^MASON_/i.test(name) || (key === "url" && name === "MASON_DATABASE_URL") ? null :
+    `${key}: \${${name}} names one of Mason's own settings (MASON_*), which a sources file may not read — ` +
+        (key === "url" ? "write url: ${DATABASE_URL} (or ${MASON_DATABASE_URL}), or a postgres:// URL" :
+            "write publication: ${PG_PUBLICATION}, the publication's name, or publication: null and Mason makes its own");
 /** The tables a file keeps current by replication, by their effective sync (`effectiveSync`): what streams. */
 export function replicatedEntries(src) {
     return src.tables.filter((e) => effectiveSync(src, e).sync.mode === "replication");
@@ -176,7 +185,10 @@ export function parseSourceText(text, name, file) {
     else {
         const m = ENV_REF.exec(v.url.trim());
         const bare = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(v.url.trim());
-        if (m)
+        const own = m ? ownSetting(m[1], "url") : null;
+        if (own !== null)
+            problems.push(own);
+        else if (m)
             url = { env: m[1] };
         else if (bare)
             problems.push(`url: $${bare[1]} — write \${${bare[1]}}: a variable is named in braces`);
@@ -201,8 +213,13 @@ export function parseSourceText(text, name, file) {
         const m = ENV_REF.exec(p);
         if (p === "")
             problems.push("publication: write publication: ${PG_PUBLICATION}, or a publication's name (publication: null and Mason makes its own)");
-        else if (m)
-            publication = { env: m[1] };
+        else if (m) {
+            const own = ownSetting(m[1], "publication");
+            if (own !== null)
+                problems.push(own);
+            else
+                publication = { env: m[1] };
+        }
         else if (p.includes("$"))
             problems.push(`publication: ${JSON.stringify(p)} — write \${NAME} alone, like \${PG_PUBLICATION}, or the publication's name`);
         else

package/dist/src/cli/style.js

@@ -158,6 +158,20 @@ export function stepRenderer(o) {
         done(text) { end(`${s.green(live ? "✔" : "✓")} ${text ?? label ?? ""}`); },
         fail(text) { end(`${s.red(live ? "✘" : "✗")} ${text ?? label ?? ""}`); },
         print(text) { clear(); o.line(text); draw(); },
+        /** the step still turning, said in new words (a count that moves: how long it has waited); a step begun if none is */
+        relabel(text) {
+            if (label === null) {
+                label = text;
+                if (live) {
+                    draw();
+                    timer = setInterval(draw, 80);
+                    timer.unref();
+                }
+                return;
+            }
+            label = text;
+            draw();
+        },
         /** a step still turning: its label (null when none) */
         open: () => label,
     };