@mason-data/cli 0.9.0 → 0.11.0

package/dist/src/cli/init.js

@@ -38,7 +38,7 @@ import { databaseNameProblem, DEFAULT_DATABASE } from "../lib/database-name.js";
 import { DEFAULT_SYNC, syncText } from "../lib/table-sync.js";
 import { newRolesText, rolesFile } from "./roles.js";
 import { newSourceText, OLD_TABLES_DIR, parseSourceText, shownPath, sourceFileNames, sourceNameFor, sourceOf, sourcesDir } from "./sources.js";
-export const INIT_USAGE = `usage: mason init [<postgres url> | demo] [--name <name>] [--database <name>] [--folder <dir>] [--remote] [--skip-check] [--json]
+export const INIT_USAGE = `usage: mason init [- | <postgres url> | demo] [--name <name>] [--database <name>] [--folder <dir>] [--remote] [--skip-check] [--json]
 
   Makes this folder a Mason project — run it in your app's folder. It checks it can read the database (and writes
   nothing when it cannot), then creates:
@@ -47,6 +47,21 @@ export const INIT_USAGE = `usage: mason init [<postgres url> | demo] [--name <na
     mason/roles.yml           who may read what: one role, everything (tables: all), the default of a user added
                               without --role, so every user reads every synced table until you narrow it — commit it
     mason/mason.yml           the Mason version the project is written for — commit it: production runs that version
+
+    mason init                                          MASON_DATABASE_URL, else DATABASE_URL (.env or the shell)
+    mason init - < db-url.txt                           the URL on stdin, written to .env, never on the command line
+    mason init demo                                     a demo database Mason hosts itself: nothing to install
+    mason init --folder db/mason --name shop-admin      the project's files elsewhere; another name
+    mason init --remote                                 the database in .env is on another machine
+
+  --name <name>     the project's name, which its replication slot is named for (default: this folder's)
+  --database <name> the database name a tool connects with, written as database: in the source file (default: none
+                    written, so tools connect with ${DEFAULT_DATABASE}): your database's own, and a tool keeps the name it has
+  --folder <dir>    where sources/ goes, relative to this folder (default mason; . for this folder itself)
+  --remote          go ahead with a database on another machine (read the warnings mason init prints); not with demo
+  --skip-check      write the project without connecting (the database is not up yet); mason start checks it; not with demo
+  --json            as data: its shape is at the end
+
   With no URL it reads MASON_DATABASE_URL, else your app's DATABASE_URL, each from .env.local, then .env, then the
   shell. The source file names the variable read, url: \${DATABASE_URL} — \${MASON_DATABASE_URL} when that is the one
   read, or when a URL given here is another database than your app's DATABASE_URL: the URL itself is in .env (written
@@ -54,6 +69,9 @@ export const INIT_USAGE = `usage: mason init [<postgres url> | demo] [--name <na
   .gitignore. Every other mason command then works anywhere in this folder. A source file already here (a clone of the
   project) is kept, and a bare mason init reads the variable it names; a roles file already here is kept. In a project
   with no source file (an older Mason's), it writes that file alone, and the roles file when there is none.
+  mason init - reads the URL from stdin (one line, from a pipe), so its password stays off the command line, where ps
+  shows it to this machine's users and your shell keeps it in its history: a URL with a password given as the argument
+  is still taken, with a warning on stderr.
   mason init demo, in a new folder, makes a project on a demo database Mason hosts itself (a shop: customers, products,
   orders, order_items): mason start makes it in .mason/demo/ and changes it every few seconds. Three of its tables are
   added; the fourth is yours to add after mason start (mason add ${DEMO_TABLE_TO_ADD}), to watch its first sync begin.
@@ -61,27 +79,15 @@ export const INIT_USAGE = `usage: mason init [<postgres url> | demo] [--name <na
   revenue per day and status, kept current: mason wait ${DEMO_GENERATED.table} once Mason is up; mason help generated); one
   already there is kept.
 
-    mason init                                          MASON_DATABASE_URL, else DATABASE_URL (.env or the shell)
-    mason init postgres://me:secret@localhost:5432/shop
-    mason init demo                                     a demo database Mason hosts itself: nothing to install
-    mason init --folder db/mason --name shop-admin      the project's files elsewhere; another name
-    mason init postgres://me:secret@db.example.com/shop --remote
-
-  --name <name>     the project's name, which its replication slot is named for (default: this folder's)
-  --database <name> the database name a tool connects with, written as database: in the source file (default: none
-                    written, so tools connect with ${DEFAULT_DATABASE}): your database's own, and a tool keeps the name it has
-  --folder <dir>    where sources/ goes, relative to this folder (default mason; . for this folder itself)
-  --remote          go ahead with a database on another machine (read the warnings mason init prints); not with demo
-  --skip-check      write the project without connecting (the database is not up yet); mason start checks it; not with demo
-  --json            as data: { name, root, folder, config, demo (true for the demo database's project, else false),
-                    source: { name (the source's: its file's), file, url (as the file writes it), database (the name
-                    a tool connects with, or null when the file has a mistake), env (the .env line written, its value masked, or null) }, roles: { file, written (false: one was here, and kept) },
-                    generated: [{ table, file, written (false: one was here, and kept) }] (the demo's generated table; [] for
-                    any other project), database: { url (password masked), from, version, tables }, warnings, next }
+  The --json answer: { name, root, folder, config, demo (true for the demo database's project, else false),
+    source: { name (the source's: its file's), file, url (as the file writes it), database (the name
+    a tool connects with, or null when the file has a mistake), env (the .env line written, its value masked, or null) }, roles: { file, written (false: one was here, and kept) },
+    generated: [{ table, file, written (false: one was here, and kept) }] (the demo's generated table; [] for
+    any other project), database: { url (password masked), from, version, tables }, warnings, next }
 `;
 export const INIT = {
     name: "init",
-    summary: "make this folder a Mason project on your Postgres: mason init (its URL from .env), mason init postgres://… or demo",
+    summary: "make this folder a Mason project on your Postgres: mason init (its URL from .env), mason init - (from stdin) or demo",
     usage: INIT_USAGE,
     options: { name: { type: "string" }, database: { type: "string" }, folder: { type: "string" }, remote: { type: "boolean" }, "skip-check": { type: "boolean" }, json: { type: "boolean" } },
     json: ["name", "root", "folder", "config", "demo", "source", "roles", "generated", "database", "warnings", "next"],
@@ -162,6 +168,63 @@ export function urlVariable(root, url, found = null) {
 const addEnvLine = (root, line) => appendEnvLine(root, line, "the database Mason syncs from (mason/sources/ names it; never commit this file)");
 /** A `.env` line as it is said: its value's password masked. */
 const maskedLine = (line) => { const eq = line.indexOf("="); return `${line.slice(0, eq)}=${maskedUrl(line.slice(eq + 1))}`; };
+/** The argument that reads the URL from stdin: `mason init -`. */
+export const STDIN_ARG = "-";
+/** The most of stdin `mason init -` reads (a URL is far shorter), and how long it waits for a pipe left open and silent. */
+const STDIN_MAX_BYTES = 8192, STDIN_TIMEOUT_MS = 10_000;
+/**
+ * THE URL FROM A PIPE (`mason init -`): stdin read whole, bounded in bytes and in time, one trailing newline trimmed;
+ * a terminal, nothing, more than one line, too much or nothing in time is said by kind — never by what was read, which
+ * may hold a password.
+ */
+export function readPipedUrl(input, max = STDIN_MAX_BYTES, timeoutMs = STDIN_TIMEOUT_MS) {
+    const way = "pipe one line into it (mason init - < db-url.txt), or put the URL in .env as DATABASE_URL=… and run mason init";
+    if (input.isTTY === true)
+        return Promise.resolve({ problem: `mason init - reads the URL from a pipe, and stdin is a terminal: ${way}` });
+    return new Promise((resolve) => {
+        const chunks = [];
+        let size = 0, ended = false;
+        const finish = (r) => {
+            if (ended)
+                return;
+            ended = true;
+            clearTimeout(timer);
+            input.removeListener("data", onData);
+            input.removeListener("end", onEnd);
+            input.removeListener("error", onError);
+            input.pause();
+            resolve(r);
+        };
+        const onData = (c) => {
+            const b = typeof c === "string" ? Buffer.from(c) : c;
+            size += b.length;
+            if (size > max) {
+                finish({ problem: `stdin held more than ${max} bytes, which is no URL: ${way}` });
+                return;
+            }
+            chunks.push(b);
+        };
+        const onEnd = () => {
+            const text = Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+            if (text.trim() === "")
+                finish({ problem: `stdin was empty: ${way}` });
+            else if (/[\r\n]/.test(text))
+                finish({ problem: `stdin held more than one line: ${way}` });
+            else
+                finish({ url: text.trim() });
+        };
+        const onError = (e) => finish({ problem: `stdin could not be read (${e.message}): ${way}` });
+        const timer = setTimeout(() => finish({ problem: `nothing ended on stdin within ${timeoutMs / 1000} s: ${way}` }), timeoutMs);
+        input.on("data", onData);
+        input.on("end", onEnd);
+        input.on("error", onError);
+        input.resume();
+    });
+}
+/** The warning for a URL whose password was given as the argument, naming the safer forms — `variable` the one the
+ *  sources file would name (DATABASE_URL, or MASON_DATABASE_URL for a database other than the app's) — never the password. */
+export const argvPasswordWarning = (variable) => "the URL given on the command line holds its password, which ps shows to this machine's users and your shell keeps in its history: " +
+    `put it in .env as ${variable}=… and run mason init, or pipe it in with mason init - < db-url.txt`;
 export async function init(argv, cwd = process.cwd(), deps = {}) {
     const io = deps.io ?? STDIO;
     const { out: say } = io;
@@ -247,7 +310,19 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
     const keptFile = kept === null || keptPath === null ? null : parseSourceText(fs.readFileSync(keptPath, "utf8"), kept.replace(/\.ya?ml$/, ""), keptPath);
     const keptVar = keptFile !== null && !("problems" in keptFile) && "env" in keptFile.url ? keptFile.url.env : null;
     // the demo's URL names a port free now, and is the one place the port is kept: mason start reads it from there
-    let url = demo ? demoUrl(await freePort(DEMO_PORT)) : f.positionals[0] ?? null;
+    // `mason init -`: the URL from a pipe, so its password never reaches the command line (ps, the shell's history)
+    const piped = f.positionals[0] === STDIN_ARG;
+    let url;
+    if (demo)
+        url = demoUrl(await freePort(DEMO_PORT));
+    else if (piped) {
+        const r = await readPipedUrl(deps.stdin ?? process.stdin);
+        if ("problem" in r)
+            return failed("init", { message: r.problem, code: "usage", usage: INIT_USAGE }, { json, io });
+        url = r.url;
+    }
+    else
+        url = f.positionals[0] ?? null;
     let from = "";
     let envFile = null; // the folder's file the URL was read from (.env.local or .env): ignored with .mason/
     let envVariable = null; // the variable envFile holds the URL in, set with it: the warning names it
@@ -263,8 +338,8 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
             if (v === null) {
                 return failed("init", { message: `which database? ${file} names url: \${${keptVar}}, and this folder has no ${keptVar}`, code: "usage",
                     why: `mason start reads the URL from ${keptVar}, so mason init checks that one`,
-                    fix: `put it in this folder's .env as ${keptVar}=postgres://… (the variable ${file} names), or give its URL on the command line: mason init writes it there`,
-                    next: [["mason init postgres://user:password@localhost:5432/your_app", `its URL, given: written to .env as ${keptVar}`], ["mason init", `again, once .env has ${keptVar}`]] }, { json, io });
+                    fix: `put it in this folder's .env as ${keptVar}=postgres://… (the variable ${file} names), or pipe its URL in (mason init - < db-url.txt): mason init writes it there`,
+                    next: [["mason init - < db-url.txt", `its URL on stdin: written to .env as ${keptVar}`], ["mason init", `again, once .env has ${keptVar}`]] }, { json, io });
             }
             found = { url: v.value, variable: keptVar, from: `${keptVar} in ${v.from}`, file: v.file };
         }
@@ -273,8 +348,8 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
         if (!found) {
             // the fixes ARE the next commands, so a coding agent reads them as such too
             return failed("init", { message: "which database? none is named, and this folder has no MASON_DATABASE_URL or DATABASE_URL", code: "usage",
-                fix: "give its URL on the command line, or put it in this folder's .env as DATABASE_URL=postgres://… (your app's, usually) or as MASON_DATABASE_URL=postgres://… (read first: a database other than your app's)",
-                next: [["mason init postgres://user:password@localhost:5432/your_app", "its URL, given"], ["mason init", "again, once .env has MASON_DATABASE_URL or DATABASE_URL"],
+                fix: "pipe its URL in (mason init - < db-url.txt), or put it in this folder's .env as DATABASE_URL=postgres://… (your app's, usually) or as MASON_DATABASE_URL=postgres://… (read first: a database other than your app's)",
+                next: [["mason init - < db-url.txt", "its URL on stdin: written to .env"], ["mason init", "again, once .env has MASON_DATABASE_URL or DATABASE_URL"],
                     ["mason init demo", "a demo database Mason makes itself: nothing to install"]] }, { json, io });
         }
         url = found.url;
@@ -283,15 +358,22 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
         envVariable = found.variable;
     }
     // a problem names where the URL is (DATABASE_URL in .env, the URL given), never the value (src/cli/preflight.ts shownUrl)
-    const urlName = found !== null ? found.from : demo ? "the demo database's URL" : "the URL given";
+    const urlName = found !== null ? found.from : demo ? "the demo database's URL" : piped ? "the URL read from stdin" : "the URL given";
     const parsed = parseSource(url, urlName);
     if ("problem" in parsed)
         return usage(parsed.problem);
+    // A PASSWORD ON THE COMMAND LINE: taken (refusing it would break scripts), and said on stderr with the safer forms;
+    // the password itself is never repeated
+    const argvPassword = !demo && !piped && found === null && parsed.source.password !== "";
     const remote = f.values.remote === true || sourceless?.config.remote === true;
     // a kept file's variable gets this URL in .env when the folder's files give it none; one they give another value is said
     const keptValue = keptVar === null ? null : appEnvValue(root, keptVar, {});
     const where = kept === null ? urlVariable(root, url, found)
         : { variable: keptVar ?? "", line: keptVar !== null && keptValue === null ? `${keptVar}=${url}` : null };
+    // the variable .env would hold it in: the one the sources file names (MASON_DATABASE_URL for another database than the app's)
+    const argvWarning = argvPassword ? argvPasswordWarning("problem" in where || where.variable === "" ? "DATABASE_URL" : where.variable) : null;
+    if (argvWarning !== null)
+        io.err(`! ${argvWarning}`);
     if ("problem" in where)
         return failed("init", { message: where.problem, code: "refused" }, { json, io });
     // WHAT IT DOES, AS A CHECKLIST (each item it is doing, with a spinner left of it that turns into a checkmark when
@@ -304,6 +386,9 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
     const db = maskedUrl(parsed.source.url);
     line(st.bold(`Making ${name} a Mason project in ${root}`));
     const notes = [];
+    // a person read the warning on stderr already; an agent reads warnings in the answer too
+    if (argvWarning !== null && json)
+        notes.push(argvWarning);
     if (keptValue !== null && keptValue.value !== url)
         notes.push(`${kept} reads ${keptVar} from ${keptValue.from}, which is ${maskedUrl(keptValue.value)}: mason start syncs from that one, not ${db}`);
     let database = { url: db, from: from ? from.slice(2, -1) : null, version: null, tables: null };

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;
 }