@mason-data/cli 0.9.0 → 0.11.0

package/dist/src/cli/serve.js

@@ -19,6 +19,10 @@
  *
  *   - ITS WEB PAGE ON LOOPBACK ALONE (src/cli/run-server.ts `listenOnLoopback`): the run's server, MASON_UI_PORT, reached
  *     from a developer's machine with `mason ui --ssh`, never published. No setting moves it to another address.
+ *     MASON_UI_SOCKET serves it on a Unix socket too, for a process on this machine (src/cli/ui-socket.ts): mode 0600, in
+ *     a folder only Mason's user can write, behind the same guard as `mason ui --ssh`'s requests. MASON_UI_RUN_FILE
+ *     writes the page's port and the run's token to a file for a supervisor on this machine (src/cli/ui-run-file.ts),
+ *     held to the same bar, once the run answers; /healthz says from the start where the page is served (`PageServed`).
  *
  * The commands beside it work as on a laptop, in the data folder: `docker compose exec mason mason add orders`.
  */
@@ -36,7 +40,10 @@ import { connectDatabase, DATABASE_SETTING, databaseNameProblem } from "../lib/d
 import { appEnvValue } from "../lib/dotenv.js";
 import { imagePinProblem, PIN_FILE } from "../lib/project-version.js";
 import { commandPinProblem } from "./pin.js";
+import { listenOnUiSocket, prepareUiSocket, uiSocketSetting } from "./ui-socket.js";
+import { prepareUiRunFile, uiRunFileSetting, UI_RUN_FILE_SETTING, writeUiRunFile } from "./ui-run-file.js";
 import { recordRefusal } from "./replication-mode.js";
+import { UI_READ_ONLY_SETTING, uiReadOnlySetting } from "./ui-read-only.js";
 import { changesRetiredText, pollMsRetiredText } from "../lib/table-sync.js";
 import { historyDaysSetting, historyDaysWrongText } from "../duck/history.js";
 import { DEFAULT_MEMORY_RULE, memoryProblems, memoryProblemText, memorySize, MEMORY_FLOOR_BYTES } from "../duck/store.js";
@@ -59,6 +66,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
@@ -79,6 +88,18 @@ export const SERVE = {
     MASON_UI_PORT           the web page's and the commands' port, on 127.0.0.1 alone: no setting moves the address, and
                             mason ui --ssh <user@server> opens the page from your machine (default ${DEFAULT_UI_PORT}, or the next
                             free one; a port named here is that port, or the start is refused)
+    MASON_UI_SOCKET         a Unix socket the web page is served on too, for a process on this machine (a supervisor,
+                            a local reverse proxy): made mode 0600 in a folder only Mason's user can write (else the
+                            start is refused), a stale one replaced, removed on exit; a request on it passes the same
+                            guard as mason ui --ssh's (default unset: none)
+    MASON_UI_RUN_FILE       a file Mason writes once it answers, for a process on this machine that supervises it:
+                            { "port", "token" }, the web page's port and the run's token, which grants what the token
+                            grants — the commands' writes (mason add, mason sync, mason user) as well as a tunnel to
+                            the page; written whole, mode 0600, in a folder only Mason's user can write (else the
+                            start is refused), a stale one replaced, removed on exit (default unset: none)
+    MASON_UI_READ_ONLY      1 when the web page should only show: it offers no control that changes anything, and
+                            refuses every change it is sent, through mason ui --ssh or the socket alike; the mason
+                            commands beside it are unchanged (default 0)
     MASON_PG_HOST, MASON_PG_PORT   the Postgres API's address (default 127.0.0.1:5433)
     MASON_PG_TLS_CERT, MASON_PG_TLS_KEY   its certificate, required off loopback; or MASON_PG_SELF_SIGNED_TLS=1
                             for one made in .mason/, or MASON_PG_PLAIN=1 behind a TLS proxy of your own
@@ -98,8 +119,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 } },
@@ -164,6 +183,19 @@ export function serveSettings(env, cwd) {
     else if (env.MASON_UI_PORT && uiPort === pgPortOf(env))
         wrong.push(`MASON_UI_PORT=${uiText} is the Postgres API's port too (MASON_PG_PORT): two ports`);
     // a host would only be believed: the page has no address but loopback, and running on while one is asked for would hide that
+    const socket = uiSocketSetting(env, cwd);
+    if (socket !== null && typeof socket !== "string")
+        wrong.push(socket.problem);
+    // the run's file (src/cli/ui-run-file.ts): never the socket's own path
+    const runFile = uiRunFileSetting(env, cwd);
+    if (runFile !== null && typeof runFile !== "string")
+        wrong.push(runFile.problem);
+    else if (runFile !== null && runFile === socket)
+        wrong.push(`${UI_RUN_FILE_SETTING} names the path MASON_UI_SOCKET names: two paths`);
+    // the read-only page (src/cli/ui-read-only.ts): 1 or 0, anything else refused here, never read as off
+    const pageReadOnly = uiReadOnlySetting(env);
+    if (typeof pageReadOnly !== "boolean")
+        wrong.push(pageReadOnly.problem);
     if (env.MASON_UI_HOST)
         wrong.push("MASON_UI_HOST is set, and the web page has no address but 127.0.0.1: remove it (mason ui --ssh <user@server> opens the page from your machine)");
     if (wrong.length) {
@@ -176,7 +208,7 @@ export function serveSettings(env, cwd) {
         name, apiKey, selfSignedTls: selfSigned === "1",
         project, data,
         health: { host: env.MASON_HEALTH_HOST || "0.0.0.0", port },
-        ui: { port: uiPort, named: !!env.MASON_UI_PORT },
+        ui: { port: uiPort, named: !!env.MASON_UI_PORT, socket: typeof socket === "string" ? socket : null, runFile: typeof runFile === "string" ? runFile : null },
     };
 }
 /**
@@ -331,6 +363,7 @@ export function serveRecordRefusal(s, existing, env) {
         return null;
     return recordRefusal(existing.config, file, env, sourcesTop(path.dirname(s.project), s.project).shown, "mason serve");
 }
+export const NO_PAGE_SERVED = { socket: null, readOnly: false };
 /** seconds since the serve started: /healthz's `uptimeSeconds` and /metrics' `mason_uptime_seconds`, one number */
 const uptimeSeconds = (startedAt, now) => Math.floor((now - startedAt) / 1000);
 /**
@@ -338,8 +371,8 @@ const uptimeSeconds = (startedAt, now) => Math.floor((now - startedAt) / 1000);
  * leaves the rest served: the counts say it); 503 while it starts and stops. Counts only, never a table's name: the
  * endpoint takes no credential.
  */
-export function healthBody(state, startedAt, now = Date.now()) {
-    const base = { status: state.phase, version: version(), uptimeSeconds: uptimeSeconds(startedAt, now) };
+export function healthBody(state, startedAt, now = Date.now(), page = NO_PAGE_SERVED) {
+    const base = { status: state.phase, version: version(), uptimeSeconds: uptimeSeconds(startedAt, now), page: { socket: page.socket, readOnly: page.readOnly } };
     if (state.phase !== "ready")
         return { status: 503, body: base };
     return { status: 200, body: { ...base, tables: phaseCounts(state.tables()) } };
@@ -355,7 +388,7 @@ export async function metricsBody(state, startedAt, now = Date.now()) {
     return metricsText({ version: version(), run: { ...run, uptimeSeconds: uptimeSeconds(startedAt, now) } });
 }
 /** The health server: GET /healthz and GET /metrics, nothing else. `log` says a scrape whose numbers could not be read. */
-export function healthServer(state, startedAt, log = say) {
+export function healthServer(state, startedAt, log = say, page = NO_PAGE_SERVED) {
     return http.createServer((req, res) => {
         const url = new URL(req.url ?? "/", "http://health");
         if (url.pathname !== "/healthz" && url.pathname !== "/metrics") {
@@ -381,7 +414,7 @@ export function healthServer(state, startedAt, log = say) {
             });
             return;
         }
-        const h = healthBody(state(), startedAt);
+        const h = healthBody(state(), startedAt, Date.now(), page);
         res.writeHead(h.status, { "content-type": "application/json", "cache-control": "no-store" }).end(`${JSON.stringify(h.body)}\n`);
     });
 }
@@ -421,14 +454,57 @@ export async function serve(argv) {
     const held = s.ui.named ? await portHolder(s.ui.port) : null;
     if (held !== null)
         return failed("serve", { message: `MASON_UI_PORT: ${heldText(s.ui.port, held)}`, code: "refused", fix: "name another port, or leave MASON_UI_PORT unset for the next free one" }, { json });
+    // the page's socket, before anything listens: its folder and its path held to the bar, a stale one replaced, then made
+    let page = null;
+    // what making it says, under the start's heading below
+    const socketSaid = [];
+    if (s.ui.socket !== null) {
+        const prepared = await prepareUiSocket(s.ui.socket, (l) => socketSaid.push(l));
+        if (prepared !== null)
+            return failed("serve", prepared, { json });
+        const opened = await listenOnUiSocket(s.ui.socket, (l) => say(`  ${l}`));
+        if ("message" in opened)
+            return failed("serve", opened, { json });
+        page = opened;
+    }
+    // the run's file: written once the run answers (asserted wide: they are set in the run's hooks, which the compiler
+    // does not follow)
+    let runFile = null;
+    let runFileFailed = null;
+    // a SIGTERM before the run has its own stop (the run file's check, the run still connecting) ends the process by its
+    // default action, which runs no finally: the socket is removed first, then the signal raised again as it was
+    const early = (signal) => {
+        if (process.listenerCount(signal) > 1)
+            return; // the run's stop is in place: it stops, and the finally removes it
+        page?.close();
+        runFile?.remove();
+        unhookEarly();
+        process.kill(process.pid, signal);
+    };
+    const unhookEarly = () => { process.removeListener("SIGTERM", early); process.removeListener("SIGINT", early); };
+    if (page !== null) {
+        process.on("SIGTERM", early);
+        process.on("SIGINT", early);
+    }
+    // its folder and its path held to the bar now, a stale one removed (its run asked, up to 2 s: the handler is in place)
+    if (s.ui.runFile !== null) {
+        const prepared = await prepareUiRunFile(s.ui.runFile, (l) => socketSaid.push(l));
+        if (prepared !== null) {
+            page?.close();
+            unhookEarly();
+            return failed("serve", prepared, { json });
+        }
+    }
     const startedAt = Date.now();
     let state = { phase: "starting" };
-    const health = healthServer(() => state, startedAt);
+    const health = healthServer(() => state, startedAt, say, { socket: page?.file ?? null, readOnly: uiReadOnlySetting(process.env) === true });
     const listening = await new Promise((resolve) => {
         health.once("error", resolve);
         health.listen(s.health.port, s.health.host, () => resolve(null));
     });
     if (listening !== null) {
+        page?.close();
+        unhookEarly();
         return failed("serve", { message: `the health endpoint cannot listen on ${s.health.host}:${s.health.port}: ${listening.message}`, code: "refused",
             fix: "MASON_HEALTH_PORT names a port free on this machine" }, { json });
     }
@@ -440,18 +516,52 @@ export async function serve(argv) {
     say(`  database  ${made.database}, what a tool connects with`);
     say(`  health    http://${s.health.host}:${s.health.port}/healthz`);
     say(`  metrics   http://${s.health.host}:${s.health.port}/metrics`);
+    for (const l of socketSaid)
+        say(`  ${l}`);
+    if (s.ui.runFile !== null)
+        say(`  run file  ${s.ui.runFile}: written once Mason answers (mode 0600; it holds the run's token)`);
+    if (page !== null)
+        say(`  web page  ${page.file} (a Unix socket, mode 0600: a request on it passes the same guard as mason ui --ssh's)`);
+    if (uiReadOnlySetting(process.env) === true)
+        say(`  web page  read-only (${UI_READ_ONLY_SETTING}=1): it refuses every change it is sent; the mason commands beside it are unchanged`);
     // the run reads the project of the folder it runs in (src/cli/project.ts): the data folder's
     process.chdir(s.data);
     let code;
     try {
         code = await dev({ port: s.ui.port, exactPort: s.ui.named, version: version(), selfSignedTls: s.selfSignedTls,
-            serve: { log: say, ready: (run) => { state = { phase: "ready", tables: run.tables, metrics: run.metrics }; }, stopping: () => { state = { phase: "stopping" }; } } });
+            serve: { log: say,
+                ready: (run) => {
+                    // the run's file before /healthz says ready: a supervisor that sees ready finds it
+                    if (s.ui.runFile !== null) {
+                        const w = writeUiRunFile(s.ui.runFile, run.page, (l) => say(`  ${l}`));
+                        if ("message" in w) {
+                            // fail closed: a supervisor would wait on a file that never comes, so the run stops, never says it is
+                            // ready, records why, and the serve exits 1
+                            runFileFailed = w;
+                            say(`  ${w.message}: Mason stops (${w.fix})`);
+                            state = { phase: "stopping" };
+                            return `stopped: the run file (${UI_RUN_FILE_SETTING}) could not be written: ${w.message.slice(`${UI_RUN_FILE_SETTING}=`.length)}`;
+                        }
+                        runFile = w;
+                        say(`  run file  ${w.file} (the web page's port and the run's token, mode 0600)`);
+                    }
+                    state = { phase: "ready", tables: run.tables, metrics: run.metrics };
+                    return null;
+                },
+                stopping: () => { state = { phase: "stopping" }; page?.close(); runFile?.remove(); },
+                ...(page !== null ? { page: page.attach, socket: page.file } : {}) } });
     }
     finally {
+        // removed whatever ended the run: a stop, a crash of the engine's thread, or a start that failed
+        page?.close();
+        runFile?.remove();
+        unhookEarly();
         // a platform's health check may hold a keep-alive connection open, which close() alone would wait for
         health.closeAllConnections();
         await new Promise((resolve) => health.close(() => resolve()));
     }
+    if (runFileFailed !== null)
+        return failed("serve", runFileFailed, { json: false });
     if (code !== 0)
         return failed("serve", { message: "Mason did not start: what stopped it is said above", code: "failed",
             fix: "fix what it says, then start it again (a platform restarts it by itself)" }, { json: 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,
     };

package/dist/src/cli/sync.js

@@ -6,7 +6,7 @@
  * polled: its answer is where the stream is, beside the polled ones'. The run's `POST /api/sync` (src/cli/run-server.ts) answers it, through the sync's own
  * poll (`Sync.pollNow`).
  */
-import { failed, jsonText, parseCommand, reportText } from "./command.js";
+import { failed, failureCode, jsonText, parseCommand, reportText } from "./command.js";
 import { out as styleOut } from "./style.js";
 import { callRun } from "./control.js";
 import { reach } from "./state.js";
@@ -15,7 +15,7 @@ import { didYouMean } from "../lib/did-you-mean.js";
 import { syncedText, syncWords } from "../lib/table-sync.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const n = (x) => x.toLocaleString("en-US");
-export const SYNC_USAGE = `usage: mason sync <table>… [--json]
+export const SYNC_USAGE = `usage: mason sync (<table>… | --all) [--json]
 
   Brings these synced tables up to date now: it reads what changed in your database since Mason last read them —
   the rows inserted or updated, and the ones deleted — in one transaction, as a poll does (each one scans its table
@@ -27,7 +27,9 @@ export const SYNC_USAGE = `usage: mason sync <table>… [--json]
 
     mason sync orders
     mason sync orders public.events
+    mason sync --all               every table the sources file names (each one a scan of its table)
 
+  --all    every table the sources file names, instead of naming them
   --json   as data: { syncedAt, tables: [{ table, changed, deleted, rows, ms }] (the tables polled), streamed (the
            tables whose sync: is replication, not polled: [{ table, position, state, why }]), next }
 `;
@@ -36,7 +38,7 @@ export const SYNC = {
     name: "sync",
     summary: "bring these synced tables up to date now: mason sync orders (a table whose sync is off is read again only so)",
     usage: SYNC_USAGE,
-    options: { json: { type: "boolean" } },
+    options: { json: { type: "boolean" }, all: { type: "boolean" } },
     json: ["syncedAt", "tables", "streamed", "next"],
 };
 /**
@@ -67,8 +69,11 @@ export async function sync(argv) {
         return f;
     const json = f.values.json === true;
     const names = [...new Set(f.positionals)];
-    if (!names.length)
-        return failed("sync", { message: "name a table: mason sync orders (mason status lists the added ones)", code: "usage", usage: SYNC_USAGE }, { json });
+    const all = f.values.all === true;
+    if (all && names.length)
+        return failed("sync", { message: `--all syncs every added table: name tables (${names.join(" ")}) or --all, not both`, code: "usage", usage: SYNC_USAGE }, { json });
+    if (!names.length && !all)
+        return failed("sync", { message: "name a table: mason sync orders (mason status lists the added ones), or mason sync --all", code: "usage", usage: SYNC_USAGE }, { json });
     const w = await reach(SYNC, json);
     if (w === null || !("run" in w))
         return 1;
@@ -76,7 +81,11 @@ export async function sync(argv) {
     return guarded("sync", json, async () => {
         const s = await readState(run);
         const added = s.tables.filter((t) => t.added);
-        const picked = [];
+        // --all: every table the sources file names, as the run read it
+        const picked = all ? added.map((t) => t.table) : [];
+        if (all && !picked.length) {
+            return failed("sync", { message: "no table is added yet, so there is nothing to sync", code: "nothing_yet", next: [["mason tables", "the database's tables"], ["mason add <table>", "add one to the sources file"]] }, { json });
+        }
         for (const name of names) {
             const t = findTable(added, name);
             if (!("message" in t)) {
@@ -97,12 +106,12 @@ export async function sync(argv) {
         // a sync scans each table whole on the database (and waits for a copy under way): minutes, not the commands' 30 s
         const r = await callRun(run, "POST", "/api/sync", { tables: picked }, 60 * 60_000);
         if (r.status !== 200) {
-            const code = typeof r.body.code === "string" ? r.body.code : r.status === 404 ? "not_found" : "failed";
+            const code = failureCode(r.body.code, r.status === 404 ? "not_found" : "failed");
             return failed("sync", { message: `${picked.join(", ")} ${picked.length === 1 ? "was" : "were"} not synced`, code, why: String(r.body.error),
                 next: [["mason status", "each synced table"], ["mason logs", "the run's log"]] }, { json });
         }
         const b = r.body;
-        const next = [[`mason sync ${names.join(" ")}`, "sync again, whenever you need it current"], ["mason status", "how each table is kept current, and when it was last synced"]];
+        const next = [[all ? "mason sync --all" : `mason sync ${names.join(" ")}`, "sync again, whenever you need it current"], ["mason status", "how each table is kept current, and when it was last synced"]];
         if (json) {
             out(jsonText(SYNC, { syncedAt: b.at, tables: b.tables, ...(b.streamed ? { streamed: b.streamed } : {}) }, next));
             return 0;

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

@@ -28,9 +28,9 @@
  *   createdAt, expiresAt, lastUsedAt   rows, --json                         `isServiceTime` (lastUsedAt or null)
  *   more                               a tip, --json                        a boolean
  */
-import { endText, failed, jsonText, parseCommand, reportText, serviceStyle, strict } from "./command.js";
+import { endText, failed, jsonText, listFlag, parseCommand, reportText, serviceStyle, strict } from "./command.js";
 import { call, carriesNoSecret, echoesSecret, isFailure, isServiceTime, serviceFailure, serviceOf, serviceText, unexpected } from "./hosted.js";
-import { loginOrgs, orgNamed, REPLICA_PART, replicaOf, tokenFor } from "./replica.js";
+import { loginOrgs, orgNamed, orgOf, REPLICA_PART, replicaOf, tokenFor } from "./replica.js";
 import { refusedNext } from "./replica-hosted.js";
 import { holdOutput } from "./output-gate.js";
 import { didYouMean } from "../lib/did-you-mean.js";
@@ -53,7 +53,7 @@ export const TOKEN = {
     name: "token",
     summary: "a hosted Mason service's CI tokens: make one for a replica (printed once), list them, revoke one",
     usage: `usage: mason token create --replica <org>/<name> [--scope deploy|users …] [--name <name>] [--days <n>] [--json]
-       mason token list [<org>] [--json]
+       mason token list [<org> | --org <org>] [--json]
        mason token revoke <id> [--org <org>] [--json]
 
   A CI token lets CI act on ONE replica of a hosted Mason service, for the scopes it was made with (deploy: mason
@@ -61,6 +61,19 @@ export const TOKEN = {
   an owner of the organisation makes, lists and revokes them, signed in as a person (mason login): a CI token
   makes none.
 
+    mason token create --replica acme/shop --name github-actions
+    mason token create --replica acme/shop --scope deploy --scope users --days 30 --json
+    mason token list acme
+    mason token revoke 3f1c9a2e --org acme
+
+  --replica <org>/<name>   create: the replica it acts on (else MASON_REPLICA)
+  --scope <scope,…>        create: what it may do, deploy or users; both: --scope deploy,users or the flag twice
+                           (default deploy)
+  --name <name>            create: what the list calls it, 1 to 64 characters (default ${DEFAULT_NAME})
+  --days <n>               create: the days it acts, 1 to ${MAX_DAYS} (default ${DEFAULT_DAYS})
+  --org <org>              list: the organisation, in place of the argument; revoke: the organisation it is of
+  --json                   as data: its shape is at the end
+
   create makes one and prints it ONCE: the service does not keep it, and nothing shows it again, so store it at once
   (as MASON_TOKEN in CI's secrets). It is alone on the first line printed, never broken, or, with --json, in the
   one field token.value of the document, so a setup step can pipe it straight into a secret store. Nothing else
@@ -72,27 +85,18 @@ export const TOKEN = {
 
   The login is MASON_TOKEN, else this machine's (mason login); the service is MASON_CLOUD_URL, else the default.
 
-    mason token create --replica acme/shop --name github-actions
-    mason token create --replica acme/shop --scope deploy --scope users --days 30 --json
-    mason token list acme
-    mason token revoke 3f1c9a2e --org acme
-
-  --replica <org>/<name>   create: the replica it acts on (else MASON_REPLICA)
-  --scope <scope>          create: what it may do, deploy or users; repeat it for both (default deploy)
-  --name <name>            create: what the list calls it, 1 to 64 characters (default ${DEFAULT_NAME})
-  --days <n>               create: the days it acts, 1 to ${MAX_DAYS} (default ${DEFAULT_DAYS})
-  --org <org>              revoke: the organisation it is of
-  --json                   as data: { token (create: { id, value (the token itself, this once), name,
-                           replica, scopes, createdAt, expiresAt }), tokens (list: [{ id, name, replica, scopes,
-                           madeBy, createdAt, lastUsedAt (null: never used), expiresAt }]), more (list: true when an
-                           organisation has more than the service lists), revoked (revoke: { org, id, name }), next }
-
   Exit status: 0 done; 1 not signed in, refused by the service (its words printed as they came, the code the
   CLI's own), or the service answered outside its contract; 2 a wrong command line.
+
+  The --json answer: { token (create: { id, value (the token itself, this once), name,
+    replica, scopes, createdAt, expiresAt }), tokens (list: [{ id, name, replica, scopes,
+    madeBy, createdAt, lastUsedAt (null: never used), expiresAt }]), more (list: true when an
+    organisation has more than the service lists), revokedToken (revoke: { org, id,
+    name }), revoked (revoke: the same, kept until 1.0), next }
 `,
     options: { replica: { type: "string" }, scope: { type: "string", multiple: true }, name: { type: "string" }, days: { type: "string" }, org: { type: "string" },
         json: { type: "boolean", default: false } },
-    json: ["token", "tokens", "more", "revoked", "next"],
+    json: ["token", "tokens", "more", "revokedToken", "revoked", "next"],
 };
 const outStyle = () => serviceStyle(styleOut());
 const errStyle = () => serviceStyle(styleErr());
@@ -176,10 +180,10 @@ export async function token(argv) {
     for (const k of ["replica", "scope", "name", "days"])
         if (verb !== "create" && f.values[k] !== undefined)
             return usage(`--${k} goes with mason token create`);
-    if (verb !== "revoke" && f.values.org !== undefined)
-        return usage("--org goes with mason token revoke", verb === "list" ? "name the organisation: mason token list <org>" : "create names it: --replica <org>/<name>");
+    if (verb === "create" && f.values.org !== undefined)
+        return usage("--org goes with mason token list and revoke", "create names it: --replica <org>/<name>");
     if (verb === "list") {
-        const org = arg === undefined ? null : orgNamed(arg, TOKEN.usage);
+        const org = orgOf(typeof f.values.org === "string" ? f.values.org : undefined, arg, TOKEN.usage);
         if (org !== null && isFailure(org))
             return fail(org, json);
         return list(org, json);
@@ -197,7 +201,9 @@ export async function token(argv) {
         return usage("mason token create names the replica it acts on", "--replica <org>/<name>, or MASON_REPLICA=<org>/<name>");
     if (isFailure(r))
         return fail(r, json);
-    const asked = Array.isArray(f.values.scope) ? f.values.scope.filter((x) => typeof x === "string") : [];
+    // a comma list or the flag repeated, the same (src/cli/command.ts listFlag)
+    const listed = listFlag(f.values.scope);
+    const asked = listed === undefined ? [] : listed.split(",");
     for (const s of asked)
         if (!SCOPES.includes(s))
             return usage(`--scope ${JSON.stringify(serviceText(s, 100))} is not a scope${didYouMean(s, SCOPES)}`, `a CI token's scopes are ${SCOPES.join(" and ")}`);
@@ -329,7 +335,7 @@ async function revoke(id, named, json) {
     const revoked = { org, id, name: serviceText(j.revoked.name, 64, secrets) };
     const next = [listStep(org)];
     if (json) {
-        out(jsonText(TOKEN, { revoked }, next));
+        out(jsonText(TOKEN, { revokedToken: revoked, revoked }, next));
         return 0;
     }
     out(reportText({ headline: `Revoked the CI token ${id} of ${org}: it acts no more`, details: [["name", revoked.name]], next }, outStyle()));