@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/machine.js

@@ -9,37 +9,44 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { STDIO, failed, jsonText, parseCommand, reportText, withEnd } from "./command.js";
 import { alive, END_GRACE_MS, runState } from "./runs.js";
-import { stopSupervisor } from "./supervise.js";
+import { stopSupervisor, supervisorOf } from "./supervise.js";
 import { STATE_DIR, isProject, projectSource, readProject, theProject, writeConfig } from "./project.js";
 import { parseSource } from "./preflight.js";
 import { USERS_FILE } from "../duck/users.js";
 import { SELF_SIGNED_FILES } from "./pg-tls.js";
 import { dropOwnReplication, dropStatements, madeReplication } from "./replication-mode.js";
 import { sourceFileNames } from "./sources.js";
-export const DESTROY_USAGE = `usage: mason destroy [--json]
+export const DESTROY_USAGE = `usage: mason destroy [--dry-run] [--json]
 
   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 syncs the tables again, and every tool connects as before.
 
     mason destroy                this folder's project
+    mason destroy --dry-run      what it would remove, changing nothing
+
+  --dry-run  list what would go — Mason stopped, the replication slot and Mason's own publication on the database, the
+             synced data and state in .mason/ — and change nothing: it stops nothing and never connects to the
+             database (the slot and publication are named from what the start that made them recorded)
+  --json     as data: { dryRun, destroyed: { project, removedItems: [what, in words], replication (null: nothing on
+             the database; else { database, slot, publication (null: one the operator named, never dropped) }), error },
+             removed (the same as [{ name, removed: [what], error }], kept until 1.0; not on a dry run), next }
 
   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 synced data: the next mason start makes and seeds it again.
 
-  --json   as data: { removed: [{ name, removed: [what], error }], next }
-
-  Exit status: 0 removed (or nothing to remove); 1 something could not be removed (said); 2 a wrong command line.
+  Exit status: 0 removed (or nothing to remove, or a dry run that found nothing in the way); 1 something could not be
+  removed, or on a dry run would not be (said); 2 a wrong command line.
 `;
 export const DESTROY = {
     needs: "project",
     name: "destroy",
     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"],
+    options: { json: { type: "boolean" }, "dry-run": { type: "boolean" } },
+    json: ["dryRun", "destroyed", "removed", "next"],
 };
 /** Wait for `pid` to exit after SIGTERM; throws when it does not within 90 s. */
 async function stopPid(pid, what, isAlive, kill = (p) => process.kill(p, "SIGTERM")) {
@@ -75,39 +82,20 @@ export async function removeProject(p, o = {}) {
     // 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.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 target = replicationTarget(p);
+    if (target !== null) {
         try {
-            if ("problem" in parsed)
-                throw new Error(parsed.problem);
-            // the slot is on the database the copy came from: a url: edited since names another, where dropping finds nothing
-            // 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 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))
-                removed.push(`${d} from ${parsed.source.database}`);
+            if ("problem" in target.on)
+                throw new Error(target.on.problem);
+            const source = target.on.source;
+            for (const d of await (o.dropReplication ?? dropOwnReplication)(source, target.own, target.from))
+                removed.push(`${d} from ${source.database}`);
         }
         catch (e) {
-            replication = `${e.message}. They hold the database's WAL while they exist: drop them by hand — ${dropStatements(own)}`;
+            replication = `${e.message}. They hold the database's WAL while they exist: drop them by hand — ${dropStatements(target.own)}`;
         }
     }
-    // the users (src/duck/users.ts) are logins a BI tool keeps, like the API key their passwords are made with, and the
-    // self-signed certificate is the fingerprint a tool pinned (the review of the cut: a new one at the next
-    // start, and config.selfSignedTls stale): the next start copies again, and every tool connects as before. A demo
-    // project's database (`.mason/demo/`, src/cli/demo.ts) is state like the copy: it goes, and config.demo stays, so the
-    // next start makes and seeds it again
-    const kept = new Set(["config.json", USERS_FILE, SELF_SIGNED_FILES.cert, SELF_SIGNED_FILES.key]);
-    const gone = fs.existsSync(p.dir) ? fs.readdirSync(p.dir).filter((x) => !kept.has(x)) : [];
+    const gone = stateEntries(p);
     for (const x of gone)
         fs.rmSync(path.join(p.dir, x), { recursive: true, force: true });
     if (gone.length)
@@ -123,9 +111,84 @@ export async function removeProject(p, o = {}) {
         writeConfig(p.dir, fresh.config);
     }
     if (replication)
-        throw new Error(`removed ${removed.join(", ")}; but not its ${objects}: ${replication}`);
+        throw new Error(`removed ${removed.join(", ")}; but not its ${target.objects}: ${replication}`);
     return removed;
 }
+/**
+ * WHAT REPLICATION MADE ON THE DATABASE, AND WHERE IT IS — read from the config and the sources file alone, never by
+ * connecting (`mason destroy --dry-run` says it; `removeProject` drops it): null when the project made none. `on` is the
+ * database to drop them on, or why it cannot be named.
+ */
+export function replicationTarget(p) {
+    if ((p.config.replication ?? null) === null && p.config.changes !== "replication")
+        return null;
+    // 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);
+    const objects = own.owned ? "publication and replication slot" : "replication slot";
+    const from = p.config.sourceServer ?? null;
+    const parsed = "message" in src ? { problem: `the database's URL cannot be read: ${src.message}` } : parseSource(src.resolved, src.from);
+    if ("problem" in parsed)
+        return { own, objects, from, on: { problem: parsed.problem } };
+    // the slot is on the database the copy came from: a url: edited since names another, where dropping finds nothing
+    // and the real slot goes on holding its WAL (the review of the sources file)
+    if (from !== null && from.database !== parsed.source.database) {
+        return { own, objects, from, on: { problem: `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` } };
+    }
+    return { own, objects, from, on: { source: parsed.source } };
+}
+/**
+ * WHAT `.mason/` HOLDS THAT DESTROY REMOVES. The users (src/duck/users.ts) are logins a BI tool keeps, like the API key
+ * their passwords are made with, and the self-signed certificate is the fingerprint a tool pinned (the review of the
+ * cut: a new one at the next start, and config.selfSignedTls stale): the next start copies again, and every tool
+ * connects as before. A demo project's database (`.mason/demo/`, src/cli/demo.ts) is state like the copy: it goes, and
+ * config.demo stays, so the next start makes and seeds it again.
+ */
+function stateEntries(p) {
+    const kept = new Set(["config.json", USERS_FILE, SELF_SIGNED_FILES.cert, SELF_SIGNED_FILES.key]);
+    return fs.existsSync(p.dir) ? fs.readdirSync(p.dir).filter((x) => !kept.has(x)).sort() : [];
+}
+/** What replication made, as `--json` names it: the database it is on (the one the synced data came from when the
+ *  sources file cannot say it; null when neither can), the slot, and the publication when it is Mason's own. */
+function replicationFacts(t) {
+    return { database: "source" in t.on ? t.on.source.database : t.from?.database ?? null, slot: t.own.slot, publication: t.own.owned ? t.own.publication : null };
+}
+/**
+ * `mason destroy --dry-run`: WHAT WOULD GO, CHANGING NOTHING. It reads the run's state (`/api/ping`, which changes nothing),
+ * the supervisor's record, the config, the sources file and `.mason/`'s names — never the database: what replication
+ * made there is named from the config's record, exactly what `removeProject` would drop.
+ */
+export async function destroyPlan(p, o = {}) {
+    const st = await (o.state ?? runState)(p);
+    if (st.kind === "hung") {
+        return { items: [], replication: null, error: `Mason for ${p.config.name} is running (pid ${st.run.pid}) but does not answer its commands, so mason destroy would remove nothing: mason stop ends it (SIGKILL after ${END_GRACE_MS / 1000} s), then mason destroy` };
+    }
+    const items = [];
+    if (st.run)
+        items.push(`Mason (pid ${st.run.pid}), stopped first`);
+    else {
+        const sup = (o.supervisor ?? supervisorOf)(p.dir);
+        if (sup !== null)
+            items.push(`its supervisor (pid ${sup}), stopped first: it is about to start Mason again`);
+    }
+    let replication = null, error = null;
+    const target = replicationTarget(p);
+    if (target !== null) {
+        replication = replicationFacts(target);
+        const on = replication.database === null ? "" : ` on ${replication.database}`;
+        items.push(`replication slot ${target.own.slot}${on}`);
+        if (target.own.owned)
+            items.push(`publication ${target.own.publication}${on}`);
+        if ("problem" in target.on)
+            error = `the rest would go, but not its ${target.objects}: ${target.on.problem}`;
+    }
+    const gone = stateEntries(p);
+    if (gone.length)
+        items.push(`${path.join(p.root, STATE_DIR)}/ (${gone.join(", ")})`);
+    return { items, replication, error };
+}
 export async function destroy(argv, deps = {}) {
     const io = deps.io ?? STDIO;
     const { out } = io;
@@ -133,12 +196,36 @@ export async function destroy(argv, deps = {}) {
     if (typeof f === "number")
         return f;
     const json = f.values.json === true;
+    const dryRun = f.values["dry-run"] === true;
     if (f.positionals.length)
         return failed("destroy", { message: `it takes no name (${f.positionals.join(" ")}): a project is its folder`, code: "usage", usage: DESTROY_USAGE, fix: "cd into the project's folder, then mason destroy" }, { json, io });
     const t = theProject(deps.cwd ?? process.cwd());
     if ("problem" in t)
         return failed("destroy", t, { json, io });
     const name = t.project.config.name;
+    const 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 ${dryRun ? "would go" : "went"} with the synced data: the next mason start seeds it again` : "");
+    if (dryRun) {
+        const plan = await (deps.destroyPlan ?? destroyPlan)(t.project);
+        const next = plan.error ? [] : [["mason destroy", "remove them"]];
+        if (json) {
+            out(jsonText(DESTROY, { dryRun: true, destroyed: { project: name, removedItems: plan.items, replication: plan.replication, error: plan.error } }, next));
+            return plan.error ? 1 : 0;
+        }
+        if (plan.error) {
+            return failed("destroy", { message: `${name}: ${plan.error}`, code: "failed", why: plan.items.length ? `mason destroy would remove: ${plan.items.join(", ")}` : undefined,
+                fix: "nothing was changed (a dry run)" }, { json: false, io });
+        }
+        out(withEnd(reportText({
+            headline: plan.items.length ? `mason destroy would remove ${name}'s synced data and state; nothing was changed` : `Nothing is left of ${name} to remove; nothing was changed`,
+            details: [...(plan.items.length ? [["would remove", plan.items.join(", ")]] : []), ["would keep", kept]],
+        }), { next }));
+        return 0;
+    }
+    // what replication made on the database, named before it goes (read from the config: nothing is connected for it)
+    const target = replicationTarget(t.project);
+    const replication = target === null ? null : replicationFacts(target);
     let result;
     try {
         result = { name, removed: await (deps.removeProject ?? removeProject)(t.project) };
@@ -148,16 +235,14 @@ export async function destroy(argv, deps = {}) {
     }
     const next = result.error ? [] : [["mason start", "syncs the tables again"]];
     if (json) {
-        out(jsonText(DESTROY, { removed: [result] }, next));
+        out(jsonText(DESTROY, { dryRun: false, destroyed: { project: name, removedItems: result.removed, replication, error: result.error ?? null }, removed: [result] }, next));
         return result.error ? 1 : 0;
     }
     if (result.error)
         return failed("destroy", { message: `${name}: ${result.error}`, code: "failed" }, { json: false, io });
     out(withEnd(reportText({
         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 synced data: the next mason start seeds it again` : "")]],
+        details: [...(result.removed.length ? [["removed", result.removed.join(", ")]] : []), ["kept", kept]],
     }), { next }));
     return 0;
 }

package/dist/src/cli/main.js

@@ -10,27 +10,73 @@
  * 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").
  */
-import { COMMANDS, orientation, topUsage, version } from "./registry.js";
+// FIRST: it sizes libuv's pool, which nothing below may have started (src/cli/pool-size.cjs)
+import "./pool-size.cjs";
+import { COMMANDS, orientation, runVersion, topUsage } 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";
-async function main(argv) {
+import { gatedExit, installOutputGate } from "./output-gate.js";
+import * as fs from "node:fs";
+/** `-C <folder>` before the command, as git's and make's (each one from the last): the folders, and the line after them. */
+function leadingFolders(argv) {
+    const folders = [];
+    let i = 0;
+    while (argv[i] === "-C") {
+        folders.push(argv[i + 1]);
+        i += 2;
+    }
+    return { folders, rest: argv.slice(i) };
+}
+/** Runs in each `-C` folder in turn, so the command means the project there; a folder missing or unreadable is a wrong
+ *  line, said before anything runs. Null once moved. */
+function moveTo(folders, json) {
+    for (const dir of folders) {
+        const wrong = (message) => failed("", { message, code: "usage", fix: "mason -C <folder> <command>: the command runs as if started in that folder" }, { json });
+        if (dir === undefined || dir === "")
+            return wrong("-C needs a folder: mason -C <folder> <command>");
+        let st;
+        try {
+            st = fs.statSync(dir);
+        }
+        catch (e) {
+            return wrong(`-C ${JSON.stringify(dir)}: ${e.code === "ENOENT" ? "there is no such folder" : "it cannot be read"}`);
+        }
+        if (!st.isDirectory())
+            return wrong(`-C ${JSON.stringify(dir)}: it is not a folder`);
+        try {
+            fs.accessSync(dir, fs.constants.R_OK | fs.constants.X_OK);
+            process.chdir(dir);
+        }
+        catch {
+            return wrong(`-C ${JSON.stringify(dir)}: it cannot be read`);
+        }
+    }
+    return null;
+}
+async function main(line) {
+    // -C <folder> first: everything after it, the project lookup included, is as if started there
+    const { folders, rest: argv } = leadingFolders(line);
     const [command, ...args] = argv;
+    const moved = moveTo(folders, wantsJson(args, COMMANDS.find((c) => c.name === command)));
+    if (moved !== null)
+        return moved;
     // mason alone: where you are and the next command; mason help / --help: every command
     if (command === undefined) {
         process.stdout.write(await orientation(process.cwd()));
         return 0;
     }
+    // mason --help --json is mason help --json: every command's spec as data
     if (command === "--help" || command === "-h") {
+        if (args.includes("--json"))
+            return COMMANDS.find((c) => c.name === "help").run(["--json"]);
         process.stdout.write(topUsage());
         return 0;
     }
-    if (command === "--version" || command === "-v" || command === "version") {
-        process.stdout.write(`${version()}\n`);
-        return 0;
-    }
+    if (command === "--version" || command === "-v" || command === "version")
+        return runVersion(args);
     const cmd = COMMANDS.find((c) => c.name === command);
     const json = wantsJson(args, cmd);
     // the commands' old names: said, never run as different ones
@@ -49,7 +95,7 @@ async function main(argv) {
         list: { message: "mason list is gone: a project is its folder, and a command means the project of the folder it runs in", next: [["mason status", "this folder's project"]] },
     };
     if (!cmd && Object.hasOwn(RENAMED, command))
-        return failed("", { ...RENAMED[command], code: "usage" }, { json });
+        return failed("", { ...RENAMED[command], code: "usage", fix: "run the command that does it now: the next steps name it" }, { json });
     if (!cmd)
         return failed("", { message: `there is no command ${JSON.stringify(command)}${didYouMean(command, COMMANDS.map((c) => c.name))}`, code: "usage", usage: json ? undefined : topUsage() }, { json });
     // a command quiet for a moment shows a spinner on a terminal until it prints (src/cli/style.ts spinUntilOutput)
@@ -70,14 +116,17 @@ 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.
     const message = e instanceof Error ? e.message : String(e);
-    const [command, ...args] = process.argv.slice(2);
+    const [command, ...args] = leadingFolders(process.argv.slice(2)).rest;
     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

@@ -43,26 +43,24 @@ export const MCP = {
   the request log under application_name mason-mcp/<the client's name>. It serves until the client closes stdin.
   Its stdout is the protocol's: it takes no --json, and a failure to start is said on stderr.
 
-  Its tools: tables; describe (a table); query (one statement; max_rows default 200, at most 10000; timeout_ms
-  default 30000, at most 300000); explain (a statement). Its resources: mason://help/agent and mason://help/mcp.
-
   Claude Code (in the project's folder, with Mason running), the URL in the server's environment:
     mason user add claude                          the URL to paste, printed once
     claude mcp add mason --env MASON_URL="${EXAMPLE_URL}" -- mason mcp
-  or on its command line, where ps shows it to this machine's users and claude mcp add prints it:
-    claude mcp add mason -- mason mcp --url "${EXAMPLE_URL}"
-
-  Claude Desktop (claude_desktop_config.json). The app often starts servers without your shell's PATH, where neither
-  mason nor the node its first line asks for is found: name both by their absolute paths (which node, which mason):
-    { "mcpServers": { "mason": { "command": "/absolute/path/to/node", "args": ["/absolute/path/to/mason", "mcp"],
-        "env": { "MASON_URL": "${EXAMPLE_URL}" } } } }
 
   What the client runs:
     MASON_URL="${EXAMPLE_URL}" mason mcp
-    mason mcp --url "${EXAMPLE_URL}"
 
   --url <url>   the Postgres API as a mason user: what mason user add printed (default MASON_URL); TLS as its sslmode
-                says (a host off this machine: require when it names none)
+                says (a host off this machine: require when it names none). A URL with a password here is taken,
+                with a warning on stderr: ps shows it to this machine's users, so MASON_URL is the safer place
+
+  Its tools: tables; describe (a table); query (one statement; max_rows default 200, at most 10000; timeout_ms
+  default 30000, at most 300000); explain (a statement). Its resources: mason://help/agent and mason://help/mcp.
+
+  Claude Desktop (claude_desktop_config.json). The app often starts servers without your shell's PATH, where neither
+  mason nor the node its first line asks for is found: name both by their absolute paths (which node, which mason):
+    { "mcpServers": { "mason": { "command": "/absolute/path/to/node", "args": ["/absolute/path/to/mason", "mcp"],
+        "env": { "MASON_URL": "${EXAMPLE_URL}" } } } }
 `,
     options: { url: { type: "string" } },
     stdout: "protocol",
@@ -71,6 +69,8 @@ export const MCP = {
  *  its own log (Claude Code: claude --debug; Claude Desktop: mcp-server-mason.log). A failure to START is failed()'s. */
 const log = (m) => { process.stderr.write(`[mason mcp] ${m}\n`); };
 const NEED_URL = "mason mcp needs a mason user's URL: MASON_URL, or --url";
+/** What `--url` with a password is told on stderr: the safer form, never the password. */
+export const MCP_ARGV_PASSWORD_WARNING = "warning: --url holds the user's password, which ps shows to this machine's users: put the URL in the server's environment as MASON_URL instead (claude mcp add mason --env MASON_URL=… -- mason mcp)";
 const HELP_STEP = ["mason help mcp", "how to add mason mcp to Claude Code or Claude Desktop"];
 const ADD_STEP = ["mason user add claude", "a user for the agent: its password and URL, printed once"];
 /** Where `mason mcp` connects: the URL given, or why there is none (the project's state says what to run). */
@@ -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). */
@@ -156,6 +156,9 @@ export async function mcp(argv) {
     const source = theSource(u.url, u.from);
     if ("message" in source)
         return failed("mcp", source, { json });
+    // a password on the command line is taken (a client's config may hold it so), and said with the safer form; never repeated
+    if (u.from === "--url" && source.password !== "")
+        log(MCP_ARGV_PASSWORD_WARNING);
     // the URL is checked once, before the protocol starts: a client that cannot connect is told now, in the failure shape
     try {
         (await connect(source, "mason-mcp")).close();

package/dist/src/cli/output-gate.js

@@ -0,0 +1,176 @@
+/**
+ * THE OUTPUT'S GATE: every byte a hosted command writes, on stdout and on stderr, put to the exact test at the point it
+ * is written (PR 645's class round: what was tested was not what was printed — a page tested whole and printed cut
+ * inside a `%XX` escape, a name tested with a lone surrogate read as a separator and printed by --json as `\udc00`, a
+ * page tested as it came and printed as the URL parser rewrote it). The per-value tests of src/cli/hosted.ts stay the
+ * first line (`carriesNoSecret`, `pageUrl`, `serviceText`); this is the last, and the authority: the bytes written.
+ *
+ * WHAT IS READ: each stream's text as written, after every transformation the CLI makes — styling (colour, the CLI's
+ * own line breaks: src/cli/command.ts serviceStyle), `JSON.stringify`'s escapes, a value's cut, the masks, the
+ * spinner's redraws — and the two streams together (a log that takes `2>&1`). Each is read in eight ways: with its
+ * terminal escapes and without them (what a log keeps; what a person sees), keeping `-` and `_` or not, and a `%XX`
+ * escape decoded or read as the characters it is written with — each as src/cli/hosted.ts reads a value (`bodyRead`:
+ * re-cased, in its compatibility form, every other character skipped). A run that crosses two writes is read whole:
+ * each reading keeps the last `ECHO_RUN - 1` characters it read, and a raw tail is kept for the shapes.
+ *
+ * WHAT FIRES IT: `ECHO_RUN` of a held secret's body in a row in any reading, or anything shaped as a documented token
+ * or (unless the command prints a password it made: `mason user add --replica`) a Mason user's password. Then the
+ * write that would complete it is NOT written, nor anything after it: the command's refusal is written instead, in the
+ * CLI's words (on stdout under --json, as its one object), and the process exits 1 (`gatedExit`). What was written
+ * before showed at most `ECHO_RUN - 1` in a row.
+ *
+ * HONEST OUTPUT IS NEVER REFUSED BY CHANCE, by `ECHO_RUN`'s derivation (src/cli/hosted.ts): an honest output is
+ * independent of the token, and a command writes a few KiB; read 8 ways and over 3 streams it is under 2^20
+ * characters read, and the bound W × 43 × 2 × 31^-11 is under 10^-8. tests/cli-hosted.test.ts measures it with a fixed
+ * seed over the honest outputs of deploy, login, logout and mason user --replica.
+ *
+ * ONE VALUE MAY BE PRINTED ONCE (`holdOutput`'s `once`: the CI token `mason token create` made, the one answer that
+ * carries a token by design): its FIRST whole occurrence in a write (`onceAt`: exactly as it is; the CLI writes it on a
+ * line of its own, never broken) is read as a separator, never as the secret it is, and is written; every other byte is read as before, the value held among the secrets, so a second
+ * occurrence, a piece of it elsewhere (11 of its body in a row) or anything else shaped as a token is refused as any
+ * secret is. What it allows is exactly that value, whole, one time, in one write.
+ *
+ * INERT until a command holds a secret (`holdOutput`): every other command writes as it always did.
+ */
+import { failed, serviceStyle } from "./command.js";
+import { bodyRead, canonicalTexts, ECHO_RUN, echoViews, ESCAPES, shapedSecret, wholeInCanonical } from "./hosted.js";
+import { err as styleErr } from "./style.js";
+/** The eight readings: [with escapes, without] × [keeping `-` and `_`, not] × [a `%XX` decoded, not]. */
+const READINGS = [true, false].flatMap((escapes) => [true, false].flatMap((keep) => [true, false].map((percent) => ({ escapes, keep, percent }))));
+const TAIL = ECHO_RUN - 1;
+/** The raw tail kept for the shapes and the secrets read whole: longer than any shape (a token is 56 characters, a
+ *  password 55), and than any held secret written `%XX`-encoded (`rawTail`). */
+const RAW_TAIL = 80;
+const rawTail = (secrets) => Math.max(RAW_TAIL, ...secrets.map((x) => 3 * x.length));
+export const nothingWritten = () => ({ reads: READINGS.map(() => ""), raw: "" });
+/**
+ * WHETHER WRITING `text` AFTER `before` WOULD WRITE A SECRET (the gate's test, pure): `ECHO_RUN` of a held secret's body
+ * in a row in any reading of the two together, or a shape. The stream as it would stand after it, either way.
+ */
+export function writes(before, text, secrets, o = {}) {
+    return writesAfter([before], readingsOf(text), secrets, o)[0];
+}
+/**
+ * `fresh` (a text's readings, `readingsOf(text)`) written after each of `befores`: the text is read and scanned once,
+ * and only where it meets each stream's tail again (a window of `ECHO_RUN` crossing into it lies within the tail and
+ * the text's first `TAIL` characters).
+ */
+function writesAfter(befores, fresh, secrets, o) {
+    const inside = readingsCarry(fresh, secrets, o);
+    const tail = rawTail(secrets);
+    return befores.map((before) => {
+        const meet = { reads: before.reads.map((r, i) => r + fresh.reads[i].slice(0, TAIL)), raw: before.raw + fresh.raw.slice(0, tail) };
+        const after = { reads: before.reads.map((r, i) => (r + fresh.reads[i]).slice(-TAIL)), raw: (before.raw + fresh.raw).slice(-tail) };
+        return { secret: inside || readingsCarry(meet, secrets, o), after };
+    });
+}
+/** `text`'s readings, after what was written before it (its tails): what `readingsCarry` tests. */
+export function readingsOf(text, before = nothingWritten()) {
+    // a text with no escape, or no `%`, reads the same either way: each distinct reading is made once
+    const stripped = text.includes("\x1b") ? text.replace(ESCAPES, "") : text, percents = text.includes("%");
+    const made = new Map();
+    const read = (escapes, keep, percent) => {
+        const key = `${escapes && stripped !== text}${keep}${percent && percents}`;
+        let r = made.get(key);
+        if (r === undefined) {
+            r = bodyRead(escapes ? text : stripped, keep, percent);
+            made.set(key, r);
+        }
+        return r;
+    };
+    return { reads: READINGS.map(({ escapes, keep, percent }, i) => before.reads[i] + read(escapes, keep, percent)), raw: before.raw + text };
+}
+/** Whether readings hold a secret: `run` of a held secret's body in a row in any of them, the secret whole, or a shape. */
+export function readingsCarry(read, secrets, o = {}) {
+    if (shapedSecret(read.raw, o) || shapedSecret(read.raw.replace(ESCAPES, ""), o))
+        return true;
+    for (const secret of secrets) {
+        if (!secret)
+            continue;
+        // whole, in the one reading, with its terminal escapes and without them (src/cli/hosted.ts wholeIn)
+        read.canonical ??= canonicalTexts(read.raw);
+        if (read.canonical.some((t) => wholeInCanonical(t, secret)))
+            return true;
+        for (const { keep, n, grams } of echoViews(secret, o.run ?? ECHO_RUN)) {
+            if (n === 0)
+                continue;
+            // a text with no escape and no `%` reads the same in several ways: each distinct reading is scanned once
+            const distinct = new Set(READINGS.flatMap((r, i) => r.keep === keep ? [read.reads[i]] : []));
+            for (const text of distinct)
+                for (let j = 0; j + n <= text.length; j++)
+                    if (grams.has(text.slice(j, j + n)))
+                        return true;
+        }
+    }
+    return false;
+}
+/** WHERE `value` IS WRITTEN WHOLE in `text`, exactly as it is (the CLI writes it alone, never broken: src/cli/token-hosted.ts);
+ *  null when it is not. The span, from its first character to its last. */
+export function onceAt(text, value) {
+    const i = text.indexOf(value);
+    return i < 0 ? null : [i, i + value.length];
+}
+let held = null;
+let refused = false;
+let originals = null;
+const state = { out: nothingWritten(), err: nothingWritten(), both: nothingWritten() };
+/** The refusal written in place of what the gate held back: the CLI's words alone. */
+const REFUSAL = {
+    message: "the service's answer would print a secret this command holds, so nothing more of it is printed",
+    code: "refused",
+    why: "what was about to be written held a secret this command holds (11 or more characters of a token's body in a row, or the database's password it sent), or something shaped as a token or a password: a hosted service's text is printed only when it carries none",
+    fix: "a service that repeats the token it was sent is answering outside its documented API: sign in again (mason login), so this token is replaced, and revoke it in the service's web app if it was shared",
+    next: [["mason login", "sign in again"]],
+};
+/**
+ * Hold `secrets` from here on, for `command`, whose answer is `--json` or not; again with more (login's new token)
+ * adds them. `passwords` false: this command prints a password it made (its answer's), so a password's shape is no
+ * secret in its output. `once`: a secret this command prints one time, whole (above), held as a secret beside it.
+ */
+export function holdOutput(o) {
+    const secrets = [...(held?.secrets ?? []), ...o.secrets.filter(Boolean), ...(o.once ? [o.once] : [])];
+    held = { command: o.command, json: o.json, secrets, passwords: o.passwords ?? held?.passwords ?? true, once: o.once || (held?.once ?? null) };
+}
+/** Whether the gate held output back: the process then exits 1, whatever the command returned. */
+export const outputRefused = () => refused;
+export const gatedExit = (code) => refused ? 1 : code;
+/** The gate, on process.stdout and process.stderr, once, before anything else wraps them (src/cli/main.ts). */
+export function installOutputGate() {
+    if (originals !== null)
+        return;
+    originals = { out: process.stdout.write.bind(process.stdout), err: process.stderr.write.bind(process.stderr) };
+    const gate = (which) => ((chunk, ...rest) => {
+        const original = originals[which];
+        const text = typeof chunk === "string" ? chunk : chunk instanceof Uint8Array ? Buffer.from(chunk).toString("utf8") : String(chunk);
+        const done = rest.find((x) => typeof x === "function");
+        // nothing to write (exitWhenWritten's flush), or nothing held: as it always was; once refused, nothing more
+        if (text === "")
+            return original(chunk, ...rest);
+        if (refused) {
+            if (done)
+                setImmediate(done);
+            return true;
+        }
+        if (held === null)
+            return original(chunk, ...rest);
+        // the one value printed once, whole, the first time it is written: read as a separator (above)
+        const once = held.once === null ? null : onceAt(text, held.once);
+        const tested = once === null ? text : `${text.slice(0, once[0])} ${text.slice(once[1])}`;
+        const [own, both] = writesAfter([state[which], state.both], readingsOf(tested), held.secrets, { passwords: held.passwords });
+        if (!own.secret && !both.secret) {
+            state[which] = own.after;
+            state.both = both.after;
+            if (once !== null)
+                held = { ...held, once: null };
+            return original(chunk, ...rest);
+        }
+        refused = true;
+        const io = { out: (m) => { originals.out(`${m}\n`); }, err: (m) => { originals.err(`\n${m}\n`); } };
+        failed(held.command, REFUSAL, { json: held.json, io, style: serviceStyle(styleErr()) });
+        if (done)
+            setImmediate(done);
+        return true;
+    });
+    process.stdout.write = gate("out");
+    process.stderr.write = gate("err");
+}