@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/init.js

@@ -30,14 +30,15 @@ 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_SYNC, DEMO_TABLE_TO_ADD, demoUrl } from "./demo.js";
+import { DEMO_DIR, NAME_RE, STATE_DIR, brokenProblem, findProject, folderPlace, ignoresStateDir, nameFromFolder, newConfig, projectWriteRefusal, writeConfig } from "./project.js";
+import { DEMO_ADDED_TABLES, DEMO_ARG, DEMO_GENERATED, DEMO_PORT, DEMO_SYNC, DEMO_TABLE_TO_ADD, demoUrl } from "./demo.js";
+import { GENERATED_DIR, generatedDir } from "./generated-files.js";
 import { freePort } from "./ports.js";
 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, sourcesDir } from "./sources.js";
-export const INIT_USAGE = `usage: mason init [<postgres url> | demo] [--name <name>] [--database <name>] [--folder <dir>] [--remote] [--skip-check] [--json]
+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]
 
   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:
@@ -46,22 +47,12 @@ 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
-  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
-  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. 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 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.
 
     mason init                                          MASON_DATABASE_URL, else DATABASE_URL (.env or the shell)
-    mason init postgres://me:secret@localhost:5432/shop
+    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 postgres://me:secret@db.example.com/shop --remote
+    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
@@ -69,17 +60,37 @@ export const INIT_USAGE = `usage: mason init [<postgres url> | demo] [--name <na
   --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) },
-                    database: { url (password masked), from, version, tables }, warnings, next }
+  --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
+  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. 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.
+  It also writes mason/${GENERATED_DIR}/${DEMO_GENERATED.file}, a generated table over the synced orders (orders and
+  revenue per day and status, kept current: mason wait ${DEMO_GENERATED.table} once Mason is up; mason help generated); one
+  already there is kept.
+
+  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", "database", "warnings", "next"],
+    json: ["name", "root", "folder", "config", "demo", "source", "roles", "generated", "database", "warnings", "next"],
 };
 /** Why `name` cannot be this project's, or null: not a name its replication slot takes. */
 export function nameProblem(name) {
@@ -157,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;
@@ -205,8 +273,16 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
     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");
+    // the one authority on where the files go (src/cli/project.ts folderPlace): outside this folder, or a place it cannot
+    // resolve (a loop, a file as a folder, unreadable, too long), which can never become a project's folder, is refused
+    const place = folderPlace(root, folder);
+    const shownArg = folderArg.length > 200 ? `${folderArg.slice(0, 200)}…` : folderArg;
+    if (place.place === "outside")
+        return usage(`--folder ${shownArg} is outside this folder`, "the project's files go in this folder or below it");
+    if (place.place === "unknown") {
+        return failed("init", { message: `--folder ${shownArg} cannot be resolved to a folder`, code: "usage", why: place.why,
+            fix: "name a folder of its own inside this one with --folder (the default, mason, is one), or fix the path" }, { json, io });
+    }
     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);
@@ -216,6 +292,11 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
     const badDatabase = connectName === null ? null : databaseNameProblem(connectName);
     if (badDatabase !== null)
         return usage(`--database: ${badDatabase}`);
+    // THE PROJECT'S FILES DEPLOYED READ-ONLY (src/cli/project.ts projectWriteRefusal, the one authority): init writes them,
+    // so it writes none — refused before the database is asked, as every writer of a project file is
+    const readOnly = projectWriteRefusal(sourceless?.root ?? null, deps.env ?? process.env);
+    if (readOnly !== null)
+        return failed("init", readOnly, { json, io });
     // 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) {
@@ -229,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
@@ -245,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 };
         }
@@ -255,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;
@@ -264,14 +357,23 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
         envFile = found.file;
         envVariable = found.variable;
     }
-    const parsed = parseSource(url);
+    // 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" : 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
@@ -284,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 };
@@ -291,6 +396,9 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
     const sourceFile = kept !== null ? path.join(sourcesDir(folder), kept) : path.join(sourcesDir(folder), `${sourceNameFor(parsed.source.database)}.yml`);
     const rolesPath = rolesFile(folder);
     const rolesKept = fs.existsSync(rolesPath);
+    // THE DEMO'S GENERATED TABLE (src/demo/seed.ts DEMO_GENERATED): written beside the sources file, kept when one is here
+    const generatedPath = demo ? path.join(generatedDir(folder), DEMO_GENERATED.file) : null;
+    const generatedKept = generatedPath !== null && fs.existsSync(generatedPath);
     // 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))
@@ -315,7 +423,7 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
             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) });
+                const c = await checkSource(url, { remote, cmd: "mason init", say: (m) => said.push(m), name: urlName });
                 if ("exit" in c)
                     throw new StepFailed(said.filter((m) => !/: connecting to /.test(m)).join("\n"), c.exit);
                 if ("needsRemote" in c) {
@@ -353,6 +461,17 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
                 `(${demo ? "every table polled every 5 s" : "each table read once, then again only by mason sync <table>"}) and the tables to sync, ` +
                 `${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 (generatedPath !== null) {
+            const g = rel(generatedPath);
+            if (generatedKept)
+                await steps.step(`Keeping ${g}`, () => undefined, () => `Kept ${g}: the demo's generated table, as it is`);
+            else {
+                await steps.step(`Writing ${g}`, () => {
+                    fs.mkdirSync(path.dirname(generatedPath), { recursive: true });
+                    fs.writeFileSync(generatedPath, DEMO_GENERATED.text);
+                }, () => `Wrote ${g}: a generated table, orders and revenue per day, kept current from the synced orders (mason help generated) — commit it`);
+            }
+        }
         // THE ROLES FILE (src/cli/roles.ts newRolesText): today's access said in a committed file — every user reads every
         // copied table, as the default role everything — kept when one is here (a clone of the project)
         if (rolesKept)
@@ -373,7 +492,7 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
         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}`);
+            await steps.step(`Writing ${pinFile}`, () => ensurePin(folder, cli, root, deps.env ?? process.env), (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);
@@ -403,6 +522,7 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
     const next = demo ? [
         ["mason start", "the demo database and Mason, in the background: its tables synced, then kept current"],
         [`mason add ${DEMO_TABLE_TO_ADD}`, "the demo's fourth table, once Mason is up: watch its first sync begin"],
+        [`mason wait ${DEMO_GENERATED.table}`, "the demo's generated table, once Mason is up: orders and revenue per day, kept current"],
         ["mason status", "the synced data 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"],
     ] : [
@@ -416,12 +536,13 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
                 database: keptFile === null ? connectName ?? DEFAULT_DATABASE : "problems" in keptFile ? null : keptFile.database ?? DEFAULT_DATABASE,
                 env: where.line === null ? null : maskedLine(where.line) },
             roles: { file: rolesPath, written: !rolesKept },
+            generated: generatedPath === null ? [] : [{ table: sourceOf(DEMO_GENERATED.table), file: generatedPath, written: !generatedKept }],
             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 synced data`
+    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; ${DEMO_GENERATED.table} is a generated table over the synced orders; mason destroy removes the demo database with the synced data`
                 : "Mason only reads your database: no setting, slot or publication is needed or made"], next }, st));
     return 0;
 }

package/dist/src/cli/login.js

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