@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/cli/init.js

@@ -0,0 +1,366 @@
+/**
+ * `mason init [<postgres url>]` (a project directory is initiated as other CLIs do it, by `mason init`):
+ * makes the folder it is run in a Mason project. The database's URL comes from the argument, else the folder's
+ * `.env.local` or `.env` (`DATABASE_URL`, the variable web frameworks use), else the shell's. The database is checked as
+ * `mason start` checks it (checkSource) and nothing is written when it fails, unless --skip-check says the database is
+ * not up yet.
+ *
+ * It writes `.mason/config.json` (0600: the project's name and Mason's key), the project's source file
+ * (`mason/sources/<database>.yml`, src/cli/sources.ts: `kind: postgres`, `url: ${DATABASE_URL}`, `tables: {}`) — the
+ * URL itself in `.env`, never in a committed file (the sources file is the developer's to commit, so the URL stays out
+ * of it): nothing more when it came from there, the line added when it came from the argument or the shell — and adds
+ * `.mason/` and that .env to the folder's .gitignore. It refuses a folder that is in a project already (here or above)
+ * — but for a project with no source file (one an older Mason made), whose source file it writes, nothing else changed.
+ *
+ * `mason init demo` (src/cli/demo.ts) writes the same files for a database Mason hosts itself: the demo's URL, on a port
+ * free now, in `.env` (the one place the port is kept), three of the demo's four tables already added (the fourth,
+ * `DEMO_TABLE_TO_ADD`, left for the person's first `mason add`), and `demo: true` in the config; there is nothing to
+ * connect to yet — `mason start` makes the database in `.mason/demo/`.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import { STDIO, endText, failed, jsonText, parseCommand } from "./command.js";
+import { checklist, out as styleOut, PLAIN, StepFailed } from "./style.js";
+import { checkSource, maskedUrl, parseSource, remoteConfirmation, remoteWarning } from "./preflight.js";
+import { cliPinProblem, ensurePin } from "./pin.js";
+import { version } from "./version.js";
+import { parseVersion, PIN_FILE } from "../lib/project-version.js";
+import { appDatabaseUrl, appEnvValue, appendEnvLine, ENV_FILE } from "../lib/dotenv.js";
+import { DEMO_DIR, NAME_RE, STATE_DIR, brokenProblem, findProject, ignoresStateDir, nameFromFolder, newConfig, writeConfig } from "./project.js";
+import { DEMO_ADDED_TABLES, DEMO_ARG, DEMO_PORT, DEMO_TABLE_TO_ADD, demoUrl } from "./demo.js";
+import { freePort } from "./ports.js";
+import { newSourceText, OLD_TABLES_DIR, parseSourceText, shownPath, sourceFileNames, sourceNameFor, sourcesDir } from "./sources.js";
+export const INIT_USAGE = `usage: mason init [<postgres url> | demo] [--name <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:
+    .mason/                   this machine's: Mason's key and, once Mason runs, its copy and state (gitignored)
+    mason/sources/<db>.yml    the database and the tables to copy (mason add adds them) — commit it
+    mason/mason.yml           the Mason version the project is written for — commit it: production runs that version
+  The source file says url: \${DATABASE_URL}: the URL itself is in .env (written there when you give it here or it is
+  only in the shell), never in a committed file. .mason/ and that .env go into .gitignore. Every other mason command
+  then works anywhere in this folder. In a project with no source file (an older Mason's), it writes that file alone.
+  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 copy begin.
+
+    mason init                                          DATABASE_URL from .env.local, .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: the database name a tool connects to on the Postgres API (default: this folder's)
+  --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), env (the .env line
+                    written, its value masked, or null) }, 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 (DATABASE_URL from .env), mason init postgres://… or demo",
+    usage: INIT_USAGE,
+    options: { name: { type: "string" }, folder: { type: "string" }, remote: { type: "boolean" }, "skip-check": { type: "boolean" }, json: { type: "boolean" } },
+    json: ["name", "root", "folder", "config", "demo", "source", "database", "warnings", "next"],
+};
+/** Why `name` cannot be this project's, or null: not a name the Postgres API's database and the slot take. */
+export function nameProblem(name) {
+    if (!NAME_RE.test(name))
+        return `${JSON.stringify(name)} is not a project name: lower-case letters, digits, - and _, starting with a letter or digit (--name sets it)`;
+    return null;
+}
+/**
+ * .gitignore with `.mason/` and each of `files` (the one DATABASE_URL was read from) added where it does not ignore them
+ * already, and what was added; null when nothing is. Reading the URL from a file and leaving that file committable
+ * was the defect (on the test server, `git add .` in a new folder committed the database password), so the
+ * file is ignored with the state. A line already covering it — exact, anchored, or a glob like `.env*` — is enough.
+ */
+export function withIgnored(gitignore, files = []) {
+    const text = gitignore ?? "";
+    const added = [];
+    let tail = "";
+    if (!ignoresStateDir(text)) {
+        added.push(`${STATE_DIR}/`);
+        tail += `# Mason: this machine's key, copy and state (mason init)\n${STATE_DIR}/\n`;
+    }
+    for (const f of files)
+        if (!ignoresFile(text, f)) {
+            added.push(f);
+            tail += `# the database URL mason/sources/ names (mason init)\n${f}\n`;
+        }
+    if (added.length === 0)
+        return null;
+    const head = text === "" ? "" : text.endsWith("\n") ? text : `${text}\n`;
+    return { text: head + tail, added };
+}
+/** Whether a .gitignore line ignores the file `name` (at the root): its name, anchored or not, or a glob matching it. */
+export function ignoresFile(gitignore, name) {
+    return gitignore.split("\n").map((l) => l.trim()).some((l) => {
+        if (l === "" || l.startsWith("#") || l.startsWith("!") || l.endsWith("/"))
+            return false;
+        const pattern = l.replace(/^\//, "");
+        if (pattern.includes("/"))
+            return false;
+        const re = new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")}$`);
+        return re.test(name);
+    });
+}
+/**
+ * Whether `file` in `root` is committed in git — then ignoring it changes nothing and init says what to run. Without
+ * git, or outside a repository, git answers with another status or does not run: the file is not known to be
+ * committed, and nothing is said (a read with a safe default).
+ */
+export function committedInGit(root, file) {
+    const r = spawnSync("git", ["ls-files", "--error-unmatch", "--", file], { cwd: root, encoding: "utf8" });
+    return r.status === 0;
+}
+/**
+ * WHERE THE SOURCE FILE'S URL IS KEPT: the variable `url: ${…}` names and the `.env` line that gives it this URL — null
+ * when the folder's .env.local or .env gives it already. DATABASE_URL when the folder's files give it no other value
+ * (one only in the shell is written down: the next shell may not have it); else MASON_DATABASE_URL, so the app's own
+ * DATABASE_URL is never changed under it. A problem when both name other databases.
+ */
+export function urlVariable(root, url) {
+    for (const variable of ["DATABASE_URL", "MASON_DATABASE_URL"]) {
+        const inFiles = appEnvValue(root, variable, {});
+        if (inFiles === null)
+            return { variable, line: `${variable}=${url}` };
+        if (inFiles.value === url)
+            return { variable, line: null };
+    }
+    return { problem: "this folder's .env names DATABASE_URL and MASON_DATABASE_URL for other databases: set one of them to the database Mason copies from, then mason init again" };
+}
+/** `.env` with `line` added (made when there is none). */
+const addEnvLine = (root, line) => appendEnvLine(root, line, "the database Mason copies 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))}`; };
+export async function init(argv, cwd = process.cwd(), deps = {}) {
+    const io = deps.io ?? STDIO;
+    const { out: say } = io;
+    const f = parseCommand(INIT, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    const usage = (message, fix) => failed("init", { message, code: "usage", fix }, { json, io });
+    if (f.positionals.length > 1)
+        return failed("init", { message: "one postgres:// URL at most", code: "usage", usage: INIT_USAGE }, { json, io });
+    // THE DEMO (src/cli/demo.ts): a database Mason hosts, made by mason start; there is nothing to check, nor elsewhere
+    const demo = f.positionals[0] === DEMO_ARG;
+    if (demo) {
+        for (const flag of ["remote", "skip-check"]) {
+            if (f.values[flag] === true)
+                return failed("init", { message: `--${flag} means nothing for the demo database: it is on this machine, made and hosted by mason start`, code: "usage", fix: "mason init demo, without it", usage: INIT_USAGE }, { json, io });
+        }
+    }
+    let root = path.resolve(cwd);
+    const existing = findProject(root);
+    // a project whose config cannot be read is still this folder's: a second init over it would hide the first's data
+    if (existing && "broken" in existing)
+        return failed("init", brokenProblem(existing), { json, io });
+    // A PROJECT WITH NO SOURCE FILE (an older Mason's): its source file is written, its config kept; any other is refused
+    const sourceless = existing !== null && sourceFileNames(existing.folder).length === 0 ? existing : null;
+    if (existing && sourceless === null) {
+        const src = sourceFileNames(existing.folder)[0];
+        const file = path.join(sourcesDir(existing.folder), src);
+        const parsedFile = parseSourceText(fs.readFileSync(file, "utf8"), src.replace(/\.ya?ml$/, ""), file);
+        // the variable the file itself names, else its literal URL is where the database is said
+        const where = !("problems" in parsedFile) && "env" in parsedFile.url
+            ? `change ${parsedFile.url.env} in ${path.join(existing.root, ENV_FILE)} (url: in ${shownPath(existing.root, file)} names it), or url: itself`
+            : `change url: in ${shownPath(existing.root, file)}`;
+        return failed("init", { message: `${existing.root === root ? "this folder is" : `this folder is inside ${existing.root}, which is`} already the Mason project ${existing.config.name}`, code: "refused",
+            fix: `to point it at another database, ${where}`, next: [["mason status", "what it is doing"]] }, { json, io });
+    }
+    if (sourceless && demo) {
+        return failed("init", { message: `this folder is the Mason project ${sourceless.config.name} already: mason init demo makes a project of its own`, code: "refused",
+            fix: "run it in a new folder (mkdir mason-demo && cd mason-demo && mason init demo)", next: [["mason init", "this project's source file, on your database"]] }, { json, io });
+    }
+    if (sourceless && (f.values.name !== undefined || f.values.folder !== undefined)) {
+        return usage(`this folder is the Mason project ${sourceless.config.name} already, whose source file is all mason init writes here: it takes no --name or --folder`, "mason init [<postgres url>], in the project's folder");
+    }
+    if (sourceless)
+        root = sourceless.root;
+    const name = sourceless?.config.name ?? f.values.name ?? nameFromFolder(root);
+    const folderArg = f.values.folder ?? "mason";
+    const folder = sourceless?.folder ?? path.resolve(root, folderArg);
+    if (path.relative(root, folder).startsWith(".."))
+        return usage(`--folder ${folderArg} is outside this folder`, "the project's files go in this folder or below it");
+    if (fs.existsSync(folder) && !fs.statSync(folder).isDirectory())
+        return usage(`${folder} is a file, not a folder`, "--folder <dir> chooses another");
+    const named = nameProblem(name);
+    if (named)
+        return usage(named);
+    // 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;
+    let from = "";
+    let envFile = null; // the folder's file the URL was read from (.env.local or .env): ignored with .mason/
+    if (url === null) {
+        const found = appDatabaseUrl(root);
+        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 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)",
+                next: [["mason init postgres://user:password@localhost:5432/your_app", "its URL, given"], ["mason init", "again, once .env has DATABASE_URL"],
+                    ["mason init demo", "a demo database Mason makes itself: nothing to install"]] }, { json, io });
+        }
+        url = found.url;
+        from = ` (DATABASE_URL in ${found.from})`;
+        envFile = found.file;
+    }
+    const parsed = parseSource(url);
+    if ("problem" in parsed)
+        return usage(parsed.problem);
+    const remote = f.values.remote === true || sourceless?.config.remote === true;
+    // THE SOURCE FILE: one already here (a clone of the project) is kept; else written, its URL a variable of .env
+    const kept = sourceFileNames(folder)[0] ?? null;
+    if (demo && kept !== null) {
+        // a clone's sources file names the team's database: the demo never takes its place
+        return failed("init", { message: `${path.relative(root, path.join(sourcesDir(folder), kept))} is already here: mason init demo makes a project of its own`, code: "refused",
+            fix: "run it in a new folder (mkdir mason-demo && cd mason-demo && mason init demo), or mason init here for the database that file names" }, { json, io });
+    }
+    const keptText = kept === null ? null : fs.readFileSync(path.join(sourcesDir(folder), kept), "utf8");
+    const keptFile = kept === null ? null : parseSourceText(keptText, kept.replace(/\.ya?ml$/, ""), path.join(sourcesDir(folder), kept));
+    const keptVar = keptFile !== null && !("problems" in keptFile) && "env" in keptFile.url ? keptFile.url.env : null;
+    // 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)
+        : { variable: keptVar ?? "", line: keptVar !== null && keptValue === null ? `${keptVar}=${url}` : null };
+    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
+    // done): live on a terminal, the finished lines anywhere else (src/cli/style.ts checklist); under
+    // --json none of it, the facts as one document at the end
+    const st = deps.io ? PLAIN : styleOut();
+    const line = (t) => { if (!json)
+        say(t); };
+    const steps = checklist({ line, live: !deps.io && !json && process.stdout.isTTY ? { write: (t) => { process.stdout.write(t); } } : null, style: st });
+    const db = maskedUrl(parsed.source.url);
+    line(st.bold(`Making ${name} a Mason project in ${root}`));
+    const notes = [];
+    if (keptValue !== null && keptValue.value !== url)
+        notes.push(`${kept} reads ${keptVar} from ${keptValue.from}, which is ${maskedUrl(keptValue.value)}: mason start copies from that one, not ${db}`);
+    let database = { url: db, from: from ? from.slice(2, -1) : null, version: null, tables: null };
+    const rel = (p) => path.relative(root, p) || ".";
+    const sourceFile = kept !== null ? path.join(sourcesDir(folder), kept) : path.join(sourcesDir(folder), `${sourceNameFor(parsed.source.database)}.yml`);
+    // the folder an older Mason listed the tables in: read by nothing (no backwards compatibility before v1.0), said
+    const oldTables = path.join(folder, OLD_TABLES_DIR);
+    if (fs.existsSync(oldTables))
+        notes.push(`${rel(oldTables)}/ is an older Mason's, which this one does not read: mason add each table again, then remove it`);
+    // A DATABASE ON ANOTHER MACHINE, NOT CONFIRMED: not a failed step (the check passed, or was skipped) but a stop before
+    // anything is written, said as one failure (remoteConfirmation) — the same words whether the check ran or not
+    const confirmRemote = () => failed("init", remoteConfirmation(parsed.source.host, { cmd: "mason init",
+        wayOut: "run the same mason init again with --remote: that says yes, copy from that machine",
+        next: [["mason init --remote <url>", "the same command, confirmed"]] }), { json, io });
+    try {
+        if (demo) {
+            // nothing exists yet: mason start makes the database (src/demo/source.ts) at its first start
+            await steps.step("Choosing the demo database's port", () => null, () => `The demo database will be ${db}: mason start makes it in ${STATE_DIR}/${DEMO_DIR}/ and seeds it (nothing to connect to yet)`);
+        }
+        else if (f.values["skip-check"] === true) {
+            if (parsed.source.remote && !remote)
+                return confirmRemote();
+            await steps.step(`Not checking ${db}${from}`, () => null, () => `Not checking ${db}${from} (--skip-check): mason start checks it`);
+        }
+        else {
+            // the check's own words are its failure's (an error, then the ways out); on success its facts are the step's line
+            const said = [];
+            let needsRemote = false;
+            const checked = await steps.step(`Connecting to ${db}${from}`, async () => {
+                const c = await checkSource(url, { remote, cmd: "mason init", say: (m) => said.push(m) });
+                if ("exit" in c)
+                    throw new StepFailed(said.filter((m) => !/: connecting to /.test(m)).join("\n"), c.exit);
+                if ("needsRemote" in c) {
+                    needsRemote = true;
+                    return c.needsRemote;
+                }
+                return c;
+            }, (c) => `Connected to ${db}${from}: Postgres ${c.facts.versionText}${c.facts.standby ? " (a read replica)" : ""}, ${c.facts.tables.length} table(s) this user can read`);
+            if (needsRemote) {
+                // the other warnings (a primary, a serverless host) stand; the remote one is the confirmation's own words
+                for (const w of checked.warnings.filter((w) => w !== remoteWarning(checked.source)))
+                    line(`  ! ${w}`);
+                return confirmRemote();
+            }
+            notes.push(...checked.warnings);
+            database = { ...database, version: checked.facts.versionText, tables: checked.facts.tables.length };
+        }
+        if (sourceless)
+            await steps.step(`Keeping ${STATE_DIR}/config.json`, () => undefined, () => `Kept ${STATE_DIR}/config.json: the project ${name}, its key and its copy`);
+        else {
+            await steps.step(`Writing ${STATE_DIR}/config.json`, () => {
+                writeConfig(path.join(root, STATE_DIR), newConfig(name, path.relative(root, folder) || ".", remote, { demo }));
+            }, () => `Wrote ${STATE_DIR}/config.json: Mason's key (this machine's)`);
+        }
+        if (kept !== null) {
+            await steps.step(`Keeping ${rel(sourceFile)}`, () => undefined, () => `Kept ${rel(sourceFile)}: the database and the tables this project copies`);
+            if (keptFile !== null && "problems" in keptFile)
+                notes.push(`${rel(sourceFile)} has ${keptFile.problems.length === 1 ? "a mistake" : "mistakes"}, which mason start refuses: ${keptFile.problems.join("; ")}`);
+        }
+        else {
+            await steps.step(`Writing ${rel(sourceFile)}`, () => {
+                fs.mkdirSync(path.dirname(sourceFile), { recursive: true });
+                fs.writeFileSync(sourceFile, newSourceText(`\${${where.variable}}`, demo ? DEMO_ADDED_TABLES : []));
+            }, () => `Wrote ${rel(sourceFile)}: the database (url: \${${where.variable}}) and the tables to copy, ${demo ? `the demo's ${DEMO_ADDED_TABLES.length} added — mason add ${DEMO_TABLE_TO_ADD} adds the fourth` : "none yet (mason add)"} — commit it`);
+        }
+        if (where.line !== null) {
+            const envLine = where.line;
+            await steps.step(`Writing ${where.variable} to .env`, () => addEnvLine(root, envLine), () => `Wrote ${maskedLine(envLine)} to .env: the URL the source file names, kept out of git`);
+            envFile = ENV_FILE;
+        }
+        // THE VERSION PIN (src/cli/pin.ts): what production's image is held to. A checkout's mason (`dev`) has none to write
+        const cli = deps.version ?? version();
+        const pinFile = rel(path.join(folder, PIN_FILE));
+        if (parseVersion(cli) !== null) {
+            await steps.step(`Writing ${pinFile}`, () => ensurePin(folder, cli), (wrote) => wrote ? `Wrote ${pinFile}: version ${cli}, the Mason this project is written for — commit it` : `Kept ${pinFile}`);
+            const pinned = cliPinProblem(folder, cli);
+            if (pinned)
+                notes.push(pinned);
+        }
+        const gi = path.join(root, ".gitignore");
+        const ignored = [`${STATE_DIR}/`, ...(envFile ? [envFile] : [])].join(" and ");
+        await steps.step(`Ignoring ${ignored} in .gitignore`, () => {
+            const before = fs.existsSync(gi) ? fs.readFileSync(gi, "utf8") : null;
+            const after = withIgnored(before, envFile ? [envFile] : []);
+            if (after !== null)
+                fs.writeFileSync(gi, after.text);
+            return after === null ? "already" : before === null ? "made" : after.added.join(" and ");
+        }, (r) => r === "already" ? `.gitignore already ignores ${ignored}` : r === "made" ? `Made .gitignore, ignoring ${ignored}` : `Added ${r} to .gitignore`);
+        if (envFile && committedInGit(root, envFile)) {
+            notes.push(`${envFile} holds the database URL (DATABASE_URL) and is committed in git: git rm --cached ${envFile} takes it out of the next commit (the file stays); then change the password`);
+        }
+    }
+    catch (e) {
+        if (!(e instanceof StepFailed))
+            throw e;
+        // the step's own words (checkSource's: what is wrong, then the ways out as hints): the first line is the failure,
+        // the rest its fix
+        const [first, ...rest] = e.message.split("\n").map((l) => l.replace(/^mason init: /, ""));
+        return failed("init", { message: first ?? e.message, code: e.exit === 2 ? "usage" : "failed", exit: e.exit, fix: rest.length ? rest.map((l) => l.replace(/^\s*- /, "")).join("\n") : undefined,
+            why: parsed.source.remote ? undefined : `the database's URL is ${db}${from}` }, { json, io });
+    }
+    const next = demo ? [
+        ["mason start", "the demo database and Mason, in the background: its tables copied, then kept current"],
+        [`mason add ${DEMO_TABLE_TO_ADD}`, "the demo's fourth table, once Mason is up: watch its copy begin"],
+        ["mason status", "the copy keeping up with the demo's changes"],
+        ["mason user add <name>", "a user for psql or a BI tool: its password and URL, printed once"],
+    ] : [
+        ["mason start", "Mason in the background, for this folder"],
+        ["mason tables", "the database's tables and their columns"],
+        ["mason add <table>", "copy a table into Mason"],
+    ];
+    if (json) {
+        say(jsonText(INIT, { name, root, folder: path.relative(root, folder) || ".", config: path.join(root, STATE_DIR, "config.json"), demo,
+            source: { name: path.basename(sourceFile).replace(/\.ya?ml$/, ""), file: sourceFile, url: keptFile !== null && !("problems" in keptFile) ? ("env" in keptFile.url ? `\${${keptFile.url.env}}` : maskedUrl(keptFile.url.literal)) : `\${${where.variable}}`,
+                env: where.line === null ? null : maskedLine(where.line) },
+            database, warnings: notes }, next));
+        return 0;
+    }
+    for (const n of notes)
+        say(`  ! ${n}`);
+    say(endText({ tips: [demo ? `The demo database runs inside mason start, read by polling: a new order every few seconds; ${DEMO_TABLE_TO_ADD} is left for you to add; mason destroy removes it with the copy`
+                : "Mason only reads your database: no setting, slot or publication is needed or made"], next }, st));
+    return 0;
+}

package/dist/src/cli/machine.js

@@ -0,0 +1,162 @@
+/**
+ * `mason destroy` — WHAT MASON HAS ON THIS MACHINE FOR A PROJECT, REMOVED (it was not clear how to purge everything, or
+ * even what still existed; named `destroy` so the CLI works more like docker's): the project's copy of the data (its
+ * DuckDB file) and its state in .mason/ — never its files, never .mason/config.json and never its users, so `mason
+ * start` begins again from the files and every tool connects as before. It means the project of the folder it runs in:
+ * a project is its folder (`mason list` was dropped; nothing on the machine lists them).
+ */
+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 { 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]
+
+  Removes this folder's project's copy of your data from this machine — its file — and Mason's state in its
+  .mason/ (the logs, the request log). Mason is stopped first if it runs. Your files (mason/sources/), .mason/config.json and
+  the users (mason user) stay: the next mason start copies the tables again, and every tool connects as before.
+
+    mason destroy                this folder's project
+
+  mason stop keeps the copy and the state, and the next mason start resumes in seconds; mason destroy frees the disk, and
+  the next mason start begins again. In replication mode the slot (and Mason's own publication) are dropped from the
+  database too: they hold its WAL for as long as they exist. A demo project's database (mason init demo, in .mason/demo/)
+  goes with the copy: the next mason start makes and seeds it again.
+
+  --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.
+`;
+export const DESTROY = {
+    needs: "project",
+    name: "destroy",
+    summary: "remove this project's copy of the data and Mason's state from this machine (your files and users stay)",
+    usage: DESTROY_USAGE,
+    options: { json: { type: "boolean" } },
+    json: ["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")) {
+    kill(pid);
+    const until = Date.now() + 90_000;
+    while (isAlive(pid) && Date.now() < until)
+        await new Promise((res) => setTimeout(res, 250));
+    if (isAlive(pid))
+        throw new Error(`${what} (pid ${pid}) is still running after 90 s: mason logs shows what it is doing`);
+}
+/** Stop the project's run if it is up, drop its replication objects, and empty its .mason/ but for the config and the users. */
+export async function removeProject(p, o = {}) {
+    const isAlive = o.isAlive ?? alive;
+    const removed = [];
+    const st = await (o.state ?? runState)(p);
+    // A RUN THAT IS ALIVE AND DOES NOT ANSWER (src/cli/runs.ts "alive and silent"; on the test server the copy
+    // was deleted under it, and the hung process kept the 58 GB file open): nothing is removed; mason stop ends it first
+    if (st.kind === "hung") {
+        throw new Error(`Mason for ${p.config.name} is running (pid ${st.run.pid}) but does not answer its commands, so nothing was removed: mason stop ends it (SIGKILL after ${END_GRACE_MS / 1000} s), then mason destroy`);
+    }
+    const run = st.run;
+    if (run) {
+        await stopPid(run.pid, `Mason for ${p.config.name}`, isAlive, o.kill);
+        removed.push(`stopped Mason (pid ${run.pid})`);
+    }
+    else {
+        // between restarts the run is dead and its supervisor waits to start it again over what is removed here
+        const sup = await (o.stopSupervisor ?? stopSupervisor)(p.dir);
+        if (sup !== null)
+            removed.push(`stopped its supervisor (pid ${sup}), which was about to start it again`);
+    }
+    // REPLICATION MODE made a publication and a slot on the database (src/cli/replication-mode.ts): the slot holds its WAL
+    // for as long as it exists, so it goes with the copy — and when it cannot, the rest goes and the failure says how
+    let replication = null;
+    let objects = "publication and replication slot";
+    if (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);
+        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 copy 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}`);
+        }
+        catch (e) {
+            replication = `${e.message}. They hold the database's WAL while they exist: drop them by hand — ${dropStatements(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)) : [];
+    for (const x of gone)
+        fs.rmSync(path.join(p.dir, x), { recursive: true, force: true });
+    if (gone.length)
+        removed.push(`${path.join(p.root, STATE_DIR)}/ (${gone.join(", ")})`);
+    // the copy is gone: the next start records the database's server again, and nothing is running
+    const fresh = readProject(p.root);
+    // the slot and publication dropped, nothing names them; when they could not be, the record stays for the next destroy
+    if (isProject(fresh)) {
+        fresh.config.running = null;
+        fresh.config.sourceServer = null;
+        if (replication === null)
+            fresh.config.replication = null;
+        writeConfig(p.dir, fresh.config);
+    }
+    if (replication)
+        throw new Error(`removed ${removed.join(", ")}; but not its ${objects}: ${replication}`);
+    return removed;
+}
+export async function destroy(argv, deps = {}) {
+    const io = deps.io ?? STDIO;
+    const { out } = io;
+    const f = parseCommand(DESTROY, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === 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;
+    let result;
+    try {
+        result = { name, removed: await (deps.removeProject ?? removeProject)(t.project) };
+    }
+    catch (e) {
+        result = { name, removed: [], error: e.message };
+    }
+    const next = result.error ? [] : [["mason start", "copies the tables again"]];
+    if (json) {
+        out(jsonText(DESTROY, { 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 copy: the next mason start seeds it again` : "")]],
+    }), { next }));
+    return 0;
+}

package/dist/src/cli/main.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * `mason` — the command line of `@mason-data/cli`: its commands for people AND coding agents, a project per folder.
+ *
+ *     mason init postgres://user:password@localhost:5432/your_app
+ *     mason start
+ *
+ * makes the folder a project, then reads that database with SELECTs alone and serves a copy of the tables you add over
+ * the Postgres protocol, in the background (src/cli/dev.ts, src/cli/background.ts); the other commands work with the
+ * 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";
+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) {
+    const [command, ...args] = argv;
+    // 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;
+    }
+    if (command === "--help" || command === "-h") {
+        process.stdout.write(topUsage());
+        return 0;
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+        process.stdout.write(`${version()}\n`);
+        return 0;
+    }
+    const cmd = COMMANDS.find((c) => c.name === command);
+    const json = wantsJson(args, cmd);
+    // the commands' old names: said, never run as different ones
+    const RENAMED = {
+        dev: { message: "mason dev is now mason start", next: [["mason init <postgres url>", "once, in your app's folder"], ["mason start", "Mason in the background"]] },
+        docs: { message: "mason docs is now mason help", next: [["mason help agent", "driving Mason from a coding agent"], ["mason help production", "running Mason on a server"]] },
+        // named for what it does to the copy, never for the mechanism
+        poll: { message: "mason poll is now mason sync", next: [["mason sync <table>", "make the copy of a table current now"], ["mason status", "each table's copy, and which the sync leaves out"]] },
+        purge: { message: "mason purge is now mason destroy", next: [["mason destroy", "this folder's project: its copy and state, never its files"]] },
+        // mason rm read as the opposite of mason add: it removed a project's copy and state, never a table;
+        // the opposite of mason add is mason remove, so both are offered
+        rm: { message: "mason rm is gone: mason remove takes a table out of the project, mason destroy removes the project's copy", next: [["mason remove <table>", "a table, and its copy"], ["mason destroy", "this folder's project: its copy and state, never its files"]] },
+        // a user's password does not expire, so mason user is enough and mason connect was dropped
+        connect: { message: "mason connect is gone: mason user add <name> makes a user whose password does not expire, and prints the URL to paste", next: [["mason user add <name>", "a user for a BI tool or your app"], ["mason status", "where the Postgres API listens"]] },
+        // a project is its folder (mason list was dropped): nothing on the machine lists them
+        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 });
+    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)
+    const stop = spinUntilOutput(`mason ${cmd.name}`);
+    try {
+        return await cmd.run(args);
+    }
+    catch (e) {
+        // a failure a command threw instead of returning (src/cli/command.ts CommandFailed), or a run that stopped answering
+        // mid-command: said as every failure is, in JSON under --json
+        if (e instanceof CommandFailed)
+            return failed(cmd.name, e.failure, { json });
+        if (e instanceof RunUnreachable)
+            return failed(cmd.name, e.failure, { json });
+        throw e;
+    }
+    finally {
+        stop();
+    }
+}
+main(process.argv.slice(2)).then(exitWhenWritten, (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 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);
+});