@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/login.js

@@ -0,0 +1,289 @@
+/**
+ * `mason login` AND `mason logout` — THIS MACHINE SIGNED IN TO A HOSTED MASON SERVICE (docs/HOSTED-API.md). They need
+ * no project: a login is the person's, kept in their own config folder (src/cli/credentials.ts), never in a project.
+ *
+ * `mason login` is OAuth's device authorization grant (RFC 8628; src/cli/hosted.ts speaks it): it asks the service for
+ * a code, says where to approve it — at once, on stderr, in plain lines, so a person in a terminal and a coding agent
+ * relaying it both read it before the wait begins (a browser opens on a terminal, when one can) — polls at the
+ * service's interval (five seconds more at each `slow_down`) until the code is approved, denied or expires, then asks
+ * who signed in (`GET /v1/me`) and saves the token. Its answer is ONE report on stdout, or under `--json` ONE object,
+ * once, when it ends: what it prints while waiting is progress, on stderr.
+ *
+ * `mason logout` revokes the saved token (best effort: a service that cannot be reached is said, with the way to revoke
+ * it by hand) and removes the saved login either way.
+ *
+ * A TOKEN NEVER REACHES A COMMAND LINE, A LOG, THE OUTPUT OR `--json`: there is no flag that takes one; `MASON_TOKEN` is
+ * read from the environment and never printed; and everything printed from the service is masked (`serviceText`).
+ * `MASON_TOKEN` comes before a saved login (CI), so `mason login` with it set is refused, naming how to sign in anyway,
+ * and `mason logout` says it cannot remove an environment variable.
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+import { endText, failed, jsonText, parseCommand, reportText, serviceStyle, strict } from "./command.js";
+import { environmentToken, readLogins, TOKEN_ENV, writeLogins } from "./credentials.js";
+import { DEFAULT_SERVICE_URL, expired, isFailure, pollToken, revoke, serviceOf, serviceText, startDevice, whoAmI } from "./hosted.js";
+import { err as styleErr, out as styleOut, stepRenderer } from "./style.js";
+import { holdOutput } from "./output-gate.js";
+import { openBrowser } from "./ui.js";
+const out = (m) => { process.stdout.write(`${m}\n`); };
+/** Everything these commands print can hold the service's text, so it is drawn in serviceStyle (src/cli/command.ts):
+ *  on a terminal the CLI breaks every line itself, and a person never sees a line begin with what the service sent. */
+const outStyle = () => serviceStyle(styleOut());
+const errStyle = () => serviceStyle(styleErr());
+const fail = (cmd, f, o) => failed(cmd, f, { json: o.json, style: errStyle() });
+const say = (m) => { process.stderr.write(`${m}\n`); };
+export const LOGIN = {
+    name: "login",
+    summary: "sign this machine in to a hosted Mason service, by a code you approve in your browser",
+    usage: `usage: mason login [--json]
+
+  Signs this machine in to a hosted Mason service: it prints a page and a code, opens the page in your browser
+  when it runs in a terminal, and waits while you sign in there and approve the code (until the code expires, as
+  the service says; Ctrl-C stops it). It then says who is signed in and their organisations, and keeps the login in
+  ~/.config/mason/credentials.json ($XDG_CONFIG_HOME/mason/ when that is set), readable by you alone, never in a
+  project. Signing in again replaces this machine's login to that service, and revokes the one it replaces.
+
+  The page and the code are printed on stderr at once, as plain lines, so a coding agent can pass them on to you
+  before the wait ends; the answer is printed when it ends.
+
+  The service is ${DEFAULT_SERVICE_URL} unless MASON_CLOUD_URL names another (https://, or http:// for one on
+  this machine). With MASON_TOKEN set (CI), every command uses that token before a saved login, so mason login is
+  refused: run it without the variable (env -u MASON_TOKEN mason login) to sign in anyway.
+
+    mason login
+    MASON_CLOUD_URL=http://127.0.0.1:8080 mason login     a service on this machine
+
+  --json    as data, once signed in: { service (its address), email, name, orgs: [{ slug, name, role }], file (where
+            the login is kept), replaced (null, or the login it replaced: { email, revoked }), next }
+`,
+    options: { json: { type: "boolean", default: false } },
+    json: ["service", "email", "name", "orgs", "file", "replaced", "next"],
+};
+export const LOGOUT = {
+    name: "logout",
+    summary: "sign this machine out of a hosted Mason service: its login revoked and removed",
+    usage: `usage: mason logout [--json]
+
+  Signs this machine out of the hosted Mason service (MASON_CLOUD_URL, else ${DEFAULT_SERVICE_URL}): it revokes
+  the login on the service, then removes it from ~/.config/mason/credentials.json. When the service cannot be
+  reached the login is still removed here, and it says the login was NOT revoked and how to revoke it: sign in to
+  the service's web app and revoke it there. Logins to other services stay.
+
+  MASON_TOKEN in the environment is not a saved login: logout cannot remove it, and says so while it is set.
+
+    mason logout
+    MASON_CLOUD_URL=http://127.0.0.1:8080 mason logout    a service on this machine
+
+  --json    as data: { service, signedOut (a saved login was removed), email (its account, null when there was
+            none), revoked (true, false when the service did not take it, null when there was nothing to revoke),
+            revokeError (why not, else null), environmentToken (MASON_TOKEN is set, and still used), file, next }
+`,
+    options: { json: { type: "boolean", default: false } },
+    json: ["service", "signedOut", "email", "revoked", "revokeError", "environmentToken", "file", "next"],
+};
+/** Where a person may approve the code, for the browser to open: a plain https (or this machine's http) URL, and none
+ *  of the characters a shell or `cmd /c start` reads (the service's URL is not ours). */
+const OPENABLE = /^https?:\/\/[A-Za-z0-9.:[\]-]+(?:\/[A-Za-z0-9._~/?=+-]*)?$/;
+/** An organisation as a line: its slug, its name when it says more, the role. */
+const orgLine = (o) => `${o.slug}${o.name && o.name !== o.slug ? ` (${o.name})` : ""}, ${o.role}`;
+export async function login(argv) {
+    const f = parseCommand(LOGIN, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    if (f.positionals.length)
+        return fail("login", { message: "it takes no argument", code: "usage", why: "the service is MASON_CLOUD_URL's, else the default", usage: LOGIN.usage }, { json });
+    const service = serviceOf();
+    if (isFailure(service))
+        return fail("login", service, { json });
+    if (environmentToken() !== null) {
+        return fail("login", { message: `${TOKEN_ENV} is set in this environment, so a login would not be used`, code: "refused",
+            why: `every command sends ${TOKEN_ENV} before a saved login: a new login to ${service.base} would be shadowed by it`,
+            fix: `to sign in anyway, run it without the variable: env -u ${TOKEN_ENV} mason login (the login is used once ${TOKEN_ENV} is unset)`,
+            next: [[`env -u ${TOKEN_ENV} mason login`, "sign in, for when MASON_TOKEN is unset"]] }, { json });
+    }
+    // the file is checked BEFORE the person spends a minute approving a code: a folder others can read is said now
+    const before = readLogins();
+    if (isFailure(before))
+        return fail("login", before, { json });
+    // what this command holds that the service may echo before it sends a token: the login it replaces (src/cli/hosted.ts
+    // `carriesNoSecret`: an answer that carries it is refused whole)
+    const held = before.logins.logins[service.base] ? [before.logins.logins[service.base].token] : [];
+    // and from here every byte written is put to the exact test against what it holds (src/cli/output-gate.ts)
+    holdOutput({ command: "login", json, secrets: held });
+    const code = await startDevice(service, held);
+    if (isFailure(code))
+        return fail("login", code, { json });
+    const token = await approved(service, code, json, held);
+    if (isFailure(token))
+        return fail("login", token, { json });
+    holdOutput({ command: "login", json, secrets: [token] });
+    // FROM HERE THE SERVICE HAS GRANTED A TOKEN, which is kept only once it is saved: on every failure before that —
+    // one said, or one thrown (PR 645's review: a crash left a granted token live) — it is revoked, and a revoke that
+    // did not reach the service is said
+    let kept;
+    try {
+        kept = await keep(service, token, held);
+    }
+    catch (e) {
+        const notRevoked = await revoke(service, token);
+        if (notRevoked === null)
+            throw e;
+        throw new Error(`${e instanceof Error ? e.message : String(e)}; the token the service granted was NOT revoked (${notRevoked}): sign in to ${service.base} in a browser and revoke it there`, { cause: e });
+    }
+    if (isFailure(kept)) {
+        const notRevoked = await revoke(service, token);
+        return fail("login", notRevoked === null ? kept : { ...kept, why: `${kept.why ? `${kept.why}; ` : ""}the token the service granted was NOT revoked (${notRevoked}): sign in to ${service.base} in a browser and revoke it there` }, { json });
+    }
+    const { me, was, saved } = kept;
+    // the login it replaced is revoked, so this machine never leaves a token it no longer holds alive on the service
+    const replaced = was === null || was.token === token ? null : { email: serviceText(was.email, 320, [token, was.token]), revokeError: await revoke(service, was.token) };
+    // what the service said, as it may be shown, in the report and in --json alike: printable, bounded, no token in it
+    const secrets = [token, ...(was ? [was.token] : [])];
+    const email = serviceText(me.email, 320, secrets), name = serviceText(me.name, 300, secrets);
+    const orgs = me.orgs.map((o) => ({ slug: serviceText(o.slug, 200, secrets), name: serviceText(o.name, 200, secrets), role: serviceText(o.role, 32, secrets) }));
+    const next = [["mason logout", `sign this machine out of ${service.base}`]];
+    if (json) {
+        out(jsonText(LOGIN, { service: service.base, email, name, orgs, file: saved.file,
+            replaced: replaced === null ? null : { email: replaced.email, revoked: replaced.revokeError === null } }, next));
+        return 0;
+    }
+    out(reportText({
+        headline: `Signed in to ${service.base} as ${email}`,
+        details: [
+            ...(name ? [["name", name]] : []),
+            ...(orgs.length ? orgs.map((o, i) => [i === 0 ? "orgs" : "", orgLine(o)]) : [["orgs", "none yet"]]),
+            ["saved", saved.file],
+        ],
+        tips: replaced === null ? undefined : replaced.revokeError === null
+            ? [`This replaces the login of ${replaced.email}, which is revoked.`]
+            : [`This replaces the login of ${replaced.email}, which was NOT revoked (${replaced.revokeError}): sign in to ${service.base} in a browser and revoke it there.`],
+        next,
+    }, outStyle()));
+    return 0;
+}
+/**
+ * WHAT A GRANTED TOKEN NEEDS BEFORE IT IS KEPT: who signed in (a token the service will not say who it is is never
+ * kept), the logins read again just before the write (so a login another command saved meanwhile is kept), and the
+ * write. A Failure when any is not had; the caller revokes the token then.
+ */
+async function keep(service, token, held) {
+    const me = await whoAmI(service, token, held);
+    if (isFailure(me))
+        return me;
+    const now = readLogins();
+    if (isFailure(now))
+        return now;
+    const was = now.logins.logins[service.base] ?? null;
+    const logins = { version: 1, logins: { ...now.logins.logins, [service.base]: { token, email: me.email, savedAt: new Date().toISOString() } } };
+    const saved = writeLogins(logins);
+    if (isFailure(saved))
+        return saved;
+    return { me, was, saved };
+}
+/**
+ * The page and the code said, then the wait: a poll every `interval` seconds (five more at each slow_down, RFC 8628
+ * 3.5), until the token, a refusal, or the code's expiry. On a terminal a spinner turns beside the wait; elsewhere the
+ * wait is one line.
+ */
+async function approved(service, code, json, held) {
+    const page = code.verificationUriComplete ?? code.verificationUri;
+    const s = errStyle();
+    say(reportText({ headline: `To sign in to ${service.base}, open this page and approve the code:`,
+        details: [["page", page], ["code", code.verificationUriComplete ? `${code.userCode} (the page shows it: check they match)` : `${code.userCode} (enter it on the page)`]] }, s));
+    const terminal = !json && process.stderr.isTTY === true;
+    if (terminal) {
+        const couldNot = OPENABLE.test(page) ? await openBrowser(page) : "the page's address is not one Mason opens by itself";
+        if (couldNot !== null)
+            say(endText({ tips: [`Could not open a browser (${couldNot}): open the page yourself.`] }, s).replace(/^\n/, ""));
+    }
+    const minutes = Math.max(1, Math.round(code.expiresIn / 60));
+    const full = `Waiting for the code to be approved (it expires in ${minutes} min; Ctrl-C stops)`;
+    // a spinner's line is redrawn in place, so it must never reach the terminal's edge (src/cli/command.ts serviceStyle):
+    // the longest label that fits beside its frame, else no spinner and the wait said once, broken as any line
+    const room = (process.stderr.columns ?? 0) - 1 - 6;
+    const label = terminal ? [full, "Waiting for approval", "Waiting"].find((l) => l.length <= room) : undefined;
+    const live = label !== undefined;
+    const steps = stepRenderer({ line: (t) => say(strict(t, s)), live: live ? process.stderr : null, style: s });
+    if (live)
+        steps.begin(label);
+    else
+        say(strict(`${full} …`, s));
+    const deadline = Date.now() + code.expiresIn * 1000;
+    let interval = code.interval;
+    for (;;) {
+        if (Date.now() + interval * 1000 > deadline) {
+            if (live)
+                steps.fail();
+            return expired(code);
+        }
+        await sleep(interval * 1000);
+        const p = await pollToken(service, code, held);
+        if ("pending" in p)
+            continue;
+        if ("slowDown" in p) {
+            interval += 5;
+            continue;
+        }
+        if (isFailure(p)) {
+            if (live)
+                steps.fail();
+            return p;
+        }
+        if (live)
+            steps.done("Approved");
+        else
+            say("Approved");
+        return p.token;
+    }
+}
+export async function logout(argv) {
+    const f = parseCommand(LOGOUT, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    if (f.positionals.length)
+        return fail("logout", { message: "it takes no argument", code: "usage", why: "the service is MASON_CLOUD_URL's, else the default", usage: LOGOUT.usage }, { json });
+    const service = serviceOf();
+    if (isFailure(service))
+        return fail("logout", service, { json });
+    const fromEnv = environmentToken() !== null;
+    const envTip = fromEnv ? [`${TOKEN_ENV} is set in this environment, and every command still uses it: logout cannot remove an environment variable. Unset it (unset ${TOKEN_ENV}), and revoke it in the service's web app if it was shared.`] : [];
+    const read = readLogins();
+    if (isFailure(read))
+        return fail("logout", read, { json });
+    const entry = read.logins.logins[service.base];
+    const env = environmentToken();
+    if (entry !== undefined || env !== null)
+        holdOutput({ command: "logout", json, secrets: [...(entry ? [entry.token] : []), ...(env !== null ? [env] : [])] });
+    if (entry === undefined) {
+        const next = [["mason login", `sign this machine in to ${service.base}`]];
+        if (json) {
+            out(jsonText(LOGOUT, { service: service.base, signedOut: false, email: null, revoked: null, revokeError: null, environmentToken: fromEnv, file: read.file }, next));
+            return 0;
+        }
+        out(reportText({ headline: `This machine is not signed in to ${service.base}`, details: [["file", read.file]], tips: envTip, next }, outStyle()));
+        return 0;
+    }
+    const revokeError = await revoke(service, entry.token);
+    // removed whether or not the service took the revoke: a person who logs out means this machine to hold it no more
+    const rest = { ...read.logins.logins };
+    delete rest[service.base];
+    const written = writeLogins({ version: 1, logins: rest });
+    if (isFailure(written))
+        return fail("logout", written, { json });
+    const email = serviceText(entry.email, 320, [entry.token]);
+    const next = [["mason login", `sign in to ${service.base} again`]];
+    if (json) {
+        out(jsonText(LOGOUT, { service: service.base, signedOut: true, email, revoked: revokeError === null, revokeError, environmentToken: fromEnv, file: written.file }, next));
+        return 0;
+    }
+    const notRevoked = revokeError === null ? undefined
+        : `The login was NOT revoked (${revokeError}), so it still works on the service until it expires: sign in to ${service.base} in a browser and revoke this machine's login there.`;
+    out(reportText({
+        headline: revokeError === null ? `Signed out of ${service.base}` : `Signed out of ${service.base} on this machine, but the login was NOT revoked`,
+        details: [["account", email], ["revoked", revokeError === null ? "yes: the service takes this login no more" : "no"], ["removed from", written.file]],
+        tips: [...(notRevoked ? [notRevoked] : []), ...envTip],
+        next,
+    }, outStyle()));
+    return 0;
+}

package/dist/src/cli/machine.js

@@ -18,16 +18,16 @@ import { dropOwnReplication, dropStatements, madeReplication } from "./replicati
 import { sourceFileNames } from "./sources.js";
 export const DESTROY_USAGE = `usage: mason destroy [--json]
 
-  Removes this folder's project's copy of your data from this machine — its file — and Mason's state in its
+  Removes this folder's project's synced data from this machine — its file — and Mason's state in its
   .mason/ (the logs, the request log). Mason is stopped first if it runs. Your files (mason/sources/), .mason/config.json and
-  the users (mason user) stay: the next mason start copies the tables again, and every tool connects as before.
+  the users (mason user) stay: the next mason start syncs the tables again, and every tool connects as before.
 
     mason destroy                this folder's project
 
-  mason stop keeps the copy and the state, and the next mason start resumes in seconds; mason destroy frees the disk, and
+  mason stop keeps the synced data and the state, and the next mason start resumes in seconds; mason destroy frees the disk, and
   the next mason start begins again. In replication mode the slot (and Mason's own publication) are dropped from the
   database too: they hold its WAL for as long as they exist. A demo project's database (mason init demo, in .mason/demo/)
-  goes with the copy: the next mason start makes and seeds it again.
+  goes with the synced data: the next mason start makes and seeds it again.
 
   --json   as data: { removed: [{ name, removed: [what], error }], next }
 
@@ -36,7 +36,7 @@ export const DESTROY_USAGE = `usage: mason destroy [--json]
 export const DESTROY = {
     needs: "project",
     name: "destroy",
-    summary: "remove this project's copy of the data and Mason's state from this machine (your files and users stay)",
+    summary: "remove this project's synced data and Mason's state from this machine (your files and users stay)",
     usage: DESTROY_USAGE,
     options: { json: { type: "boolean" } },
     json: ["removed", "next"],
@@ -71,18 +71,19 @@ export async function removeProject(p, o = {}) {
         if (sup !== null)
             removed.push(`stopped its supervisor (pid ${sup}), which was about to start it again`);
     }
-    // REPLICATION MODE made a publication and a slot on the database (src/cli/replication-mode.ts): the slot holds its WAL
-    // for as long as it exists, so it goes with the copy — and when it cannot, the rest goes and the failure says how
+    // REPLICATION made a publication and a slot on the database (src/cli/replication-mode.ts), recorded by the start or
+    // the run that made them (an older start recorded its mode, `changes`): the slot holds its WAL for as long as it
+    // exists, so it goes with the copy — and when it cannot, the rest goes and the failure says how
     let replication = null;
     let objects = "publication and replication slot";
-    if (p.config.changes === "replication") {
+    if ((p.config.replication ?? null) !== null || p.config.changes === "replication") {
         // the slot, and the publication only when it is Mason's own: one the operator named is its owner's, left as it is
         const src = projectSource(p);
         // what the start that made them recorded (madeReplication); a project with no record names them by its one sources file
         const own = madeReplication(p.config, "message" in src ? (sourceFileNames(p.folder)[0] ?? "app.yml").replace(/\.ya?ml$/, "") : src.name);
         if (!own.owned)
             objects = "replication slot";
-        const parsed = "message" in src ? { problem: `the database's URL cannot be read: ${src.message}` } : parseSource(src.resolved);
+        const parsed = "message" in src ? { problem: `the database's URL cannot be read: ${src.message}` } : parseSource(src.resolved, src.from);
         try {
             if ("problem" in parsed)
                 throw new Error(parsed.problem);
@@ -90,7 +91,7 @@ export async function removeProject(p, o = {}) {
             // and the real slot goes on holding its WAL (the review of the sources file)
             const from = p.config.sourceServer ?? null;
             if (from !== null && from.database !== parsed.source.database) {
-                throw new Error(`the sources file names ${parsed.source.database} now, and the copy came from ${from.database}, where the slot is: ` +
+                throw new Error(`the sources file names ${parsed.source.database} now, and the synced data came from ${from.database}, where the slot is: ` +
                     `put that database's URL back in the sources file and run mason destroy again, or drop them on ${from.database} by hand`);
             }
             for (const d of await (o.dropReplication ?? dropOwnReplication)(parsed.source, own, from))
@@ -145,7 +146,7 @@ export async function destroy(argv, deps = {}) {
     catch (e) {
         result = { name, removed: [], error: e.message };
     }
-    const next = result.error ? [] : [["mason start", "copies the tables again"]];
+    const next = result.error ? [] : [["mason start", "syncs the tables again"]];
     if (json) {
         out(jsonText(DESTROY, { removed: [result] }, next));
         return result.error ? 1 : 0;
@@ -156,7 +157,7 @@ export async function destroy(argv, deps = {}) {
         headline: result.removed.length ? `Removed ${name}` : `Nothing was left of ${name} to remove`,
         details: [...(result.removed.length ? [["removed", result.removed.join(", ")]] : []), ["kept", `your files in ${t.project.folder}, .mason/config.json and the users` +
                     // the demo database is state like the copy (src/cli/demo.ts): it goes, and config.demo stays to make it again
-                    (t.project.config.demo === true ? ` — not the demo database, which went with the copy: the next mason start seeds it again` : "")]],
+                    (t.project.config.demo === true ? ` — not the demo database, which went with the synced data: the next mason start seeds it again` : "")]],
     }), { next }));
     return 0;
 }

package/dist/src/cli/main.js

@@ -10,12 +10,15 @@
  * project of the folder they run in. Every command is in src/cli/registry.ts, described once (src/cli/command.ts).
  * Apache-2.0: it runs the stack (CLAUDE.md "Licensing").
  */
+// FIRST: it sizes libuv's pool, which nothing below may have started (src/cli/pool-size.cjs)
+import "./pool-size.cjs";
 import { COMMANDS, orientation, topUsage, version } from "./registry.js";
 import { didYouMean } from "../lib/did-you-mean.js";
 import { spinUntilOutput } from "./style.js";
 import { CommandFailed, failed, wantsJson } from "./command.js";
 import { RunUnreachable } from "./control.js";
 import { exitWhenWritten } from "../lib/exit-when-written.js";
+import { gatedExit, installOutputGate } from "./output-gate.js";
 async function main(argv) {
     const [command, ...args] = argv;
     // mason alone: where you are and the next command; mason help / --help: every command
@@ -38,11 +41,11 @@ async function main(argv) {
         dev: { message: "mason dev is now mason start", next: [["mason init <postgres url>", "once, in your app's folder"], ["mason start", "Mason in the background"]] },
         docs: { message: "mason docs is now mason help", next: [["mason help agent", "driving Mason from a coding agent"], ["mason help production", "running Mason on a server"]] },
         // named for what it does to the copy, never for the mechanism
-        poll: { message: "mason poll is now mason sync", next: [["mason sync <table>", "make the copy of a table current now"], ["mason status", "each table's copy, and which the sync leaves out"]] },
-        purge: { message: "mason purge is now mason destroy", next: [["mason destroy", "this folder's project: its copy and state, never its files"]] },
+        poll: { message: "mason poll is now mason sync", next: [["mason sync <table>", "bring a synced table up to date now"], ["mason status", "each synced table, and which the sync leaves out"]] },
+        purge: { message: "mason purge is now mason destroy", next: [["mason destroy", "this folder's project: its synced data and state, never its files"]] },
         // mason rm read as the opposite of mason add: it removed a project's copy and state, never a table;
         // the opposite of mason add is mason remove, so both are offered
-        rm: { message: "mason rm is gone: mason remove takes a table out of the project, mason destroy removes the project's copy", next: [["mason remove <table>", "a table, and its copy"], ["mason destroy", "this folder's project: its copy and state, never its files"]] },
+        rm: { message: "mason rm is gone: mason remove takes a table out of the project, mason destroy removes the project's synced data", next: [["mason remove <table>", "a table, and its synced data"], ["mason destroy", "this folder's project: its synced data and state, never its files"]] },
         // a user's password does not expire, so mason user is enough and mason connect was dropped
         connect: { message: "mason connect is gone: mason user add <name> makes a user whose password does not expire, and prints the URL to paste", next: [["mason user add <name>", "a user for a BI tool or your app"], ["mason status", "where the Postgres API listens"]] },
         // a project is its folder (mason list was dropped): nothing on the machine lists them
@@ -70,7 +73,10 @@ async function main(argv) {
         stop();
     }
 }
-main(process.argv.slice(2)).then(exitWhenWritten, (e) => {
+// every byte written passes the output's gate, which a hosted command arms with the secrets it holds (src/cli/output-gate.ts):
+// installed before anything else wraps the streams (the spinner, below), and its refusal is the exit's (`gatedExit`)
+installOutputGate();
+main(process.argv.slice(2)).then((code) => exitWhenWritten(gatedExit(code)), (e) => {
     // an error no command said in its own words: its message, never a stack trace (CLAUDE.md: a message that needs a
     // stack to be understood is a bug — mason query orders printed one when Mason's API was not up yet).
     // MASON_DEBUG=1 prints where it happened, for the bug report it deserves. The same shape as every failure, JSON under --json.
@@ -79,5 +85,5 @@ main(process.argv.slice(2)).then(exitWhenWritten, (e) => {
     const code = failed(command ?? "", { message, code: "failed", fix: process.env.MASON_DEBUG ? undefined : "this is a bug in mason: MASON_DEBUG=1 prints where it happened, for the report" }, { json: wantsJson(args, COMMANDS.find((c) => c.name === command)) });
     if (process.env.MASON_DEBUG)
         process.stderr.write(`${e.stack ?? ""}\n`);
-    exitWhenWritten(code);
+    exitWhenWritten(gatedExit(code));
 });

package/dist/src/cli/mason.cjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * THE `mason` COMMAND'S ENTRY (the published `bin`, the image's `mason`, the run src/cli/background.ts starts): sets the
+ * pool's size, then loads the command. CommonJS because on Node 22, which the package allows, loading an ES module
+ * reads its files through libuv's pool, so the pool has started with four threads before an ES entry's first line
+ * runs: measured on 22.13, where a CommonJS entry alone got 16 threads of 16. Node 24 and 26 read those files
+ * synchronously, which is why main.ts's first import is enough in a checkout. Nothing here may use the pool.
+ */
+"use strict";
+require("./pool-size.cjs");
+const fs = require("node:fs");
+const path = require("node:path");
+const { pathToFileURL } = require("node:url");
+
+// the .ts in a checkout and the image, the .js in the package (src/lib/runnable.ts, which this file cannot import yet)
+const ts = path.join(__dirname, "main.ts");
+import(pathToFileURL(fs.existsSync(ts) ? ts : path.join(__dirname, "main.js")).href);

package/dist/src/cli/mcp.js

@@ -9,7 +9,7 @@
  * `--url`, else `MASON_URL`), so it works the same beside `mason start` and against a `mason serve` elsewhere, and every
  * statement is a row of the request log under `application_name` `mason-mcp/<client>`. Everything it reads comes over
  * that wire: the tables and columns from the catalog (a real Postgres), the rows and how current each copy is from
- * EXPLAIN (FORMAT JSON)'s `Mason.Copies` — the sync's own words, the same line `mason status` prints.
+ * EXPLAIN (FORMAT JSON)'s `Mason.Tables` — the sync's own words, the same line `mason status` prints.
  *
  * STDOUT IS THE PROTOCOL'S: newline-delimited JSON-RPC 2.0 frames and nothing else (`CommandSpec.stdout`: no --json,
  * every failure on stderr); what it says goes to stderr. A tool's failure is Mason's refusal (SQLSTATE, message,
@@ -29,15 +29,15 @@ import { PgConnection, PgError, pgIdent, pgLiteral, socketErrorText } from "../c
 import { qualifiedName } from "../duck/explain.js";
 import { didYouMean } from "../lib/did-you-mean.js";
 /** The URL a client is shown in the help: a user's, as mason user add prints it. */
-const EXAMPLE_URL = "postgres://claude:<password>@127.0.0.1:5433/shop";
+const EXAMPLE_URL = "postgres://claude:<password>@127.0.0.1:5433/mason";
 export const MCP = {
     name: "mcp",
-    summary: "an MCP server on stdio, for Claude Code, Claude Desktop and other agents: the copy's tables, queries, refusals",
+    summary: "an MCP server on stdio, for Claude Code, Claude Desktop and other agents: the synced tables, queries, refusals",
     usage: `usage: mason mcp [--url <postgres://user:password@host:port/database>]
 
   An MCP (Model Context Protocol) server on stdin and stdout, for Claude Code, Claude Desktop and any MCP client.
   Its tools say what an agent would otherwise guess: the tables Mason serves, each one's columns, rows and how
-  current its copy is, and each statement's answer with its Postgres types — or Mason's refusal, with what to write
+  current each is, and each statement's answer with its Postgres types — or Mason's refusal, with what to write
   instead. It connects to the Postgres API as a mason user, by the URL mason user add printed (MASON_URL, else
   --url), so it works beside mason start or against a mason serve elsewhere, and every statement it runs is in
   the request log under application_name mason-mcp/<the client's name>. It serves until the client closes stdin.
@@ -103,9 +103,9 @@ async function theUrl(given, cwd) {
 }
 /** The URL read as a connection: the CLI's own reading (src/cli/preflight.ts parseSource, TLS as the URL's sslmode). */
 function theSource(url, from) {
-    const p = parseSource(url);
+    const p = parseSource(url, from);
     if ("problem" in p)
-        return { message: `${from} is not a Postgres URL: ${p.problem}`, code: "usage", fix: `the URL mason user add printed: ${EXAMPLE_URL}`, next: [HELP_STEP] };
+        return { message: p.problem, code: "usage", fix: `the URL mason user add printed: ${EXAMPLE_URL}`, next: [HELP_STEP] };
     return p.source;
 }
 /** application_name's client part: the MCP client's own name, in letters, digits, `.`, `_` and `-` (Postgres keeps 63 bytes). */
@@ -121,7 +121,7 @@ function connect(s, applicationName) {
         applicationName, connectTimeoutMs: 10_000, textForms: [] });
 }
 /** Why a connection failed, in the failure shape: nothing listening, a password refused, a database it does not serve. */
-function connectFailure(e, s) {
+export function connectFailure(e, s) {
     const where = `${s.host}:${s.port}`;
     if (e instanceof PgError) {
         const hint = e.fields.H;
@@ -131,7 +131,9 @@ function connectFailure(e, s) {
                 next: [["mason user list", "the users, beside the run"], ADD_STEP] };
         }
         return { message: `${where} refused the connection: ${e.fields.M ?? e.message}${e.code ? ` (${e.code})` : ""}`, code: "refused", why: hint ?? e.detail,
-            fix: "the URL mason user add printed: its database is the project's", next: [HELP_STEP] };
+            // a URL from before the name moved is the likely one: the hint is the listener's, and says the right name
+            fix: e.code === "3D000" ? "the last part of the URL is the database: change it to the one the hint names, or use the URL mason user add printed"
+                : "the URL mason user add printed", next: [HELP_STEP] };
     }
     const reason = e instanceof Error ? socketErrorText(e) : String(e);
     const said = /ECONNREFUSED/.test(reason) ? `nothing is listening on ${where}` : reason.replace(/^connecting to \S+: /, "");
@@ -224,8 +226,9 @@ export const TOOLS = [
     {
         name: "tables",
         title: "The tables Mason serves",
-        description: "The tables Mason serves, each a copy of a table of the application's Postgres database: about how many rows each holds, " +
-            "and how its copy is kept current (polled, streamed by logical replication, or not current, with when it last was). " +
+        description: "The tables Mason serves, each synced from a table of the application's Postgres database: about how many rows each holds, " +
+            "and how it is kept current and when it was last synced (sync: off — read again only when someone runs mason sync — or polled " +
+            "every so often, or streamed by logical replication). A table last synced days ago answers as of then: say so with the answer. " +
             "Start here: a statement can read only these, named as listed.",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
         annotations: { readOnlyHint: true, openWorldHint: false },
@@ -233,7 +236,8 @@ export const TOOLS = [
     {
         name: "describe",
         title: "One table's columns",
-        description: "One table's columns with their Postgres types, its primary key and foreign keys, about how many rows it holds and how its copy is kept current.",
+        description: "One table's columns with their Postgres types, its primary key and foreign keys, about how many rows it holds, how it is kept current " +
+            "and when it was last synced.",
         inputSchema: { type: "object", properties: { table: { type: "string", description: "the table as tables lists it (public.orders), or a bare name in public (orders)" } },
             required: ["table"], additionalProperties: false },
         annotations: { readOnlyHint: true, openWorldHint: false },
@@ -254,8 +258,9 @@ export const TOOLS = [
     {
         name: "explain",
         title: "How Mason answers a statement",
-        description: "How Mason answers one statement, as its EXPLAIN prints it: each copy the statement reads with its rows and how current it is, " +
-            "the SQL Mason runs for it, and the plan. analyze: true runs the statement too and adds each step's rows and time.",
+        description: "How Mason answers one statement, as its EXPLAIN prints it: each synced table the statement reads with its rows and how current it is, " +
+            "the SQL Mason runs for it, and the plan. analyze: true runs the statement too and adds each step's rows and time. " +
+            "For a statement that reads a table your role filters: no plan and no row counts, and analyze is refused.",
         inputSchema: { type: "object", properties: {
                 sql: { type: "string", description: "one statement, in Postgres's SQL (without EXPLAIN)" },
                 analyze: { type: "boolean", default: false, description: "run it, and say each step's rows and time" },
@@ -269,13 +274,14 @@ export const RESOURCES = [
     { uri: "mason://help/agent", name: "agent", title: "Driving Mason from an agent", description: "mason help agent: the commands in order, their --json shapes, exit codes and failures", mimeType: "text/plain" },
     { uri: "mason://help/mcp", name: "mcp", title: "mason mcp", description: "mason help mcp: this server's tools, and how to add it to a client", mimeType: "text/plain" },
 ];
-const INSTRUCTIONS = "Mason serves read-only copies of tables of an application's Postgres database, for analytical SQL (scans and aggregates). " +
-    "Call tables first, describe a table before querying it, and write Postgres's SQL. Each table says how current its copy is. " +
+const INSTRUCTIONS = "Mason serves read-only tables synced from an application's Postgres database, for analytical SQL (scans and aggregates). " +
+    "Call tables first, describe a table before querying it, and write Postgres's SQL. Each table says how current it is. " +
     "When a statement is refused, its hint says what to write instead.";
 /** The relations Mason serves, as the catalog lists them (a catalog read: no row of the request log). */
 async function relations(pg) {
     const r = await pg.query(`SELECT n.nspname, c.relname, c.relkind FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
-    WHERE c.relkind IN ('r', 'p', 'v', 'm') AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg\\_%' ORDER BY 1, 2`);
+    WHERE c.relkind IN ('r', 'p', 'v', 'm') AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg\\_%'
+      AND (pg_catalog.has_table_privilege(c.oid, 'SELECT') OR pg_catalog.has_any_column_privilege(c.oid, 'SELECT')) ORDER BY 1, 2`);
     return r.rows.map(([schema, name, kind]) => ({ schema: schema, name: name, kind: kind === "v" || kind === "m" ? "view" : "table" }));
 }
 class McpServer {
@@ -494,7 +500,7 @@ class McpServer {
         return { tables: all.map((t) => t.kind === "view" ? { table: qualifiedName(t), kind: "view" } : { table: qualifiedName(t), kind: "table", ...copyFacts(copies.get(qualifiedName(t))) }) };
     }
     /**
-     * HOW EACH COPY IS KEPT CURRENT, and its rows: EXPLAIN (FORMAT JSON)'s `Mason.Copies`, the sync's own words (what
+     * HOW EACH COPY IS KEPT CURRENT, and its rows: EXPLAIN (FORMAT JSON)'s `Mason.Tables`, the sync's own words (what
      * `mason status` prints), read over the wire so a remote mason serve answers as a local run does. One EXPLAIN a table
      * (a union of them all failed whole for one table it could not plan, and left a refusal in the request log the agent
      * never sent), several at once on connections of this call's. In a run the catalog lists only the tables copied
@@ -523,7 +529,7 @@ class McpServer {
             catch (e) {
                 throw new BadAnswer(`EXPLAIN (FORMAT JSON) of ${key} is not JSON (${e.message}): ${text.slice(0, 200)}`);
             }
-            const copy = doc[0]?.Mason?.Copies?.find((c) => c.Table === key);
+            const copy = doc[0]?.Mason?.Tables?.find((c) => c.Table === key);
             if (copy !== undefined)
                 out.set(key, copy);
         };
@@ -556,7 +562,8 @@ class McpServer {
         const rel = `${pgLiteral(qualifiedName(found))}::regclass`;
         // pg_catalog.format_type, written out: these are the catalog's own OIDs (mason_wire_type names the wire's)
         const columns = await pg.query(`SELECT a.attname, pg_catalog.format_type(a.atttypid, a.atttypmod), a.attnotnull, pg_catalog.col_description(a.attrelid, a.attnum)
-      FROM pg_catalog.pg_attribute a WHERE a.attrelid = ${rel} AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`);
+      FROM pg_catalog.pg_attribute a WHERE a.attrelid = ${rel} AND a.attnum > 0 AND NOT a.attisdropped
+        AND pg_catalog.has_column_privilege(a.attrelid, a.attnum, 'SELECT') ORDER BY a.attnum`);
         const key = await pg.query(`SELECT a.attname FROM pg_catalog.pg_index i JOIN pg_catalog.pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY (i.indkey)
       WHERE i.indrelid = ${rel} AND i.indisprimary ORDER BY array_position(i.indkey::int2[], a.attnum)`);
         const foreign = await pg.query(`SELECT pg_catalog.pg_get_constraintdef(oid) FROM pg_catalog.pg_constraint WHERE conrelid = ${rel} AND contype = 'f' ORDER BY conname`);
@@ -666,13 +673,15 @@ class ToolAnswerError extends ToolError {
 }
 /** A JSON-RPC error answer. */
 function rpcError(id, code, message) { return { jsonrpc: "2.0", id, error: { code, message } }; }
-/** A copy's facts as the tools say them: about how many rows, how it is kept current, and what keeps it current now. */
+/** A copy's facts as the tools say them: about how many rows, how it is kept current, what keeps it current now, and —
+ *  polled or off — its sync and when it was last synced (a copy's age is never hidden: issue 33). */
 function copyFacts(c) {
     if (c === undefined)
-        return { rows_about: null, kept: "how it is kept current is unknown: Mason has no copy of it" };
+        return { rows_about: null, kept: "how it is kept current is unknown: Mason has not synced it" };
     if ("error" in c)
         return { rows_about: null, kept: `how it is kept current could not be read: ${c.error}` };
-    return { rows_about: c["Estimated Rows"], kept: c["Kept Current"], kept_current_by: c["Kept Current By"] };
+    return { rows_about: c["Estimated Rows"] ?? null, kept: c["Kept Current"], kept_current_by: c["Kept Current By"],
+        ...(c.Sync !== undefined ? { sync: c.Sync, last_synced: c["Last Synced"] ?? null } : {}) };
 }
 /** A refusal as the model reads it: Postgres's fields, as psql prints them, and the same as structured content.
  *  `shift`: the characters this server put before the statement (EXPLAIN's), taken off its position. */