@mason-data/cli 0.9.0 → 0.10.0

package/dist/src/cli/login.js

@@ -23,7 +23,7 @@ import { environmentToken, readLogins, TOKEN_ENV, writeLogins } from "./credenti
 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";
+import { OPENABLE, 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. */
@@ -42,6 +42,12 @@ export const LOGIN = {
   ~/.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.
 
+    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 }
+
   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.
 
@@ -49,11 +55,8 @@ export const LOGIN = {
   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 }
+  Exit status: 0 signed in; 1 refused or failed (said); 2 a wrong command line; 124 the code expired before it
+  was approved (run mason login again).
 `,
     options: { json: { type: "boolean", default: false } },
     json: ["service", "email", "name", "orgs", "file", "replaced", "next"],
@@ -68,21 +71,21 @@ export const LOGOUT = {
   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 }
+  --json    as data: its shape is at the end
+
+  MASON_TOKEN in the environment is not a saved login: logout cannot remove it, and says so while it is set.
+
+  The --json answer: { service, signedOut (a saved login was removed), email (its account, null when there was
+    none), loginRevoked (true, false when the service did not take it, null when there was nothing to
+    revoke), revoked (the same, kept until 1.0), 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"],
+    json: ["service", "signedOut", "email", "loginRevoked", "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) {
@@ -258,7 +261,7 @@ export async function logout(argv) {
     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));
+            out(jsonText(LOGOUT, { service: service.base, signedOut: false, email: null, loginRevoked: 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()));
@@ -274,7 +277,7 @@ export async function logout(argv) {
     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));
+        out(jsonText(LOGOUT, { service: service.base, signedOut: true, email, loginRevoked: revokeError === null, revoked: revokeError === null, revokeError, environmentToken: fromEnv, file: written.file }, next));
         return 0;
     }
     const notRevoked = revokeError === null ? undefined

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, src.from);
+    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

@@ -12,28 +12,71 @@
  */
 // 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 { 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";
 import { gatedExit, installOutputGate } from "./output-gate.js";
-async function main(argv) {
+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
@@ -52,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)
@@ -81,7 +124,7 @@ main(process.argv.slice(2)).then((code) => exitWhenWritten(gatedExit(code)), (e)
     // 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`);

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). */
@@ -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/project.js

@@ -162,7 +162,7 @@ export function theProject(cwd) {
     if (p)
         return { project: p };
     return { problem: "no Mason project here or above", code: "no_project", fix: "cd into a project's folder, or make this folder one (mason init demo: a demo database, nothing to install)",
-        next: [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"]] };
+        next: [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or its URL on stdin: mason init -)"]] };
 }
 /** Whether `root`'s .gitignore already ignores `.mason/`. */
 export function ignoresStateDir(gitignore) {