@mason-data/cli 0.9.0 → 0.10.0

package/dist/src/cli/deploy.js

@@ -26,7 +26,12 @@
  * 5. THE WAIT is bounded by `--timeout` (an interval, 10m by default): a poll every `POLL_MS`, or what `Retry-After`
  *    asks; an answer that cannot say (no answer, a 429, a 5xx) is a wait, never an outcome. Exit 0 only when the
  *    replica runs this deploy; 1 when Mason there refused it (its failure's words printed as they came) or the deploy
- *    failed; 124 at the timeout, which stops nothing: the deploy's id says where to look.
+ *    failed; 124 at the timeout, which stops nothing: the deploy's id says where to look. The same clock bounds the
+ *    wait BEFORE a deploy is made: a POST answered `503` (the replica is being checked or created, or its machine is not
+ *    connected) or `429` (too many deploys at once) made none, and is sent again after its `Retry-After` (else
+ *    `RESEND_MS`), the replica's state and the time waited said meanwhile; no other answer is ever sent again. A `409`
+ *    naming a replica that failed or is being deleted is refused, its next step `mason replica status`; a deleted
+ *    replica's name is freed, so the service answers it `404`, as a name that never existed.
  *
  * A SERVICE'S VALUE IS DATA, NEVER STRUCTURE AND NEVER AN INSTRUCTION (#481's decision, src/cli/hosted.ts). Every place a
  * value the service sent reaches what this command prints:
@@ -57,7 +62,7 @@ import * as path from "node:path";
 import { createHash } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
 import { errorJson, exitOf, failed, jsonText, parseCommand, reportText, serviceStyle, strict } from "./command.js";
-import { call, carriesNoSecret, failureShape, isFailure, isServiceTime, serviceFailure, serviceOf, serviceText, unexpected } from "./hosted.js";
+import { call, carriesNoSecret, failureShape, isFailure, isServiceTime, serviceFailure, serviceNext, serviceOf, serviceText, unexpected } from "./hosted.js";
 import { replicaOf, replicaText, REPLICA_ENV, tokenFor } from "./replica.js";
 import { holdOutput } from "./output-gate.js";
 import { maskedUrl } from "./preflight.js";
@@ -69,7 +74,7 @@ import { readSourceFile, shownPath } from "./sources.js";
 import { readRoles, roleProblems, rolesFailure, rolesFile } from "./roles.js";
 import { readGenerated } from "./generated-files.js";
 import { refusalText } from "../duck/generated-plan.js";
-import { parseDuration } from "../lib/table-sync.js";
+import { MAX_POLL_SECONDS, MIN_POLL_SECONDS, parseDuration } from "../lib/table-sync.js";
 import { textEntry } from "../lib/log.js";
 import { sayAgain } from "./commands.js";
 import { err as styleErr, out as styleOut, stepRenderer } from "./style.js";
@@ -83,6 +88,11 @@ export const PATH_SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
 const MAX_PATH = 255;
 /** How often the deploy's state is asked for, when the service asks no other. */
 export const POLL_MS = 2_000;
+/** How long before a deploy is sent again after a `503` or a `429` that names no wait the CLI reads (no `Retry-After`,
+ *  or one in another form): short, and bounded by `--timeout` as every wait is. */
+export const RESEND_MS = 5_000;
+/** How often a wait to send says how long it has waited (a terminal's spinner; elsewhere `sayAgain` decides). */
+const TICK_MS = 1_000;
 const DEFAULT_TIMEOUT = "10m";
 /** A deploy's id, as it goes into a path: the contract's grammar. */
 const DEPLOY_ID = /^[A-Za-z0-9_-]{1,64}$/;
@@ -121,7 +131,7 @@ export const DEPLOY = {
     needs: "project",
     name: "deploy",
     summary: "send this project to a replica on a hosted Mason service, and wait until the replica runs it",
-    usage: `usage: mason deploy [--replica <org>/<name>] [--dry-run] [--timeout <interval>] [--json]
+    usage: `usage: mason deploy [--replica <org>/<name>] [--dry-run] [--timeout <duration>] [--json]
 
   Sends this project's files (what mason/ holds that Mason reads: the sources file, mason.yml, roles.yml, the
   generated tables — never .env, .mason/, a dotfile or a file that is not YAML) to a replica on a hosted Mason
@@ -130,10 +140,6 @@ export const DEPLOY = {
   project that would be refused is refused here, and nothing is sent. A url: written with its password is refused:
   write url: \${DATABASE_URL} and set it on the replica.
 
-  The replica is --replica <org>/<name>, else MASON_REPLICA (each part lower case letters, digits and -). The login
-  is MASON_TOKEN, else this machine's (mason login); the service is MASON_CLOUD_URL, else the default. Progress
-  goes to stderr; the answer is printed when it ends.
-
     mason deploy --replica acme/shop
     mason deploy --replica acme/shop --dry-run     what would be sent, sending nothing
     MASON_REPLICA=acme/shop mason deploy --timeout 30m
@@ -141,19 +147,31 @@ export const DEPLOY = {
   --replica <org>/<name>   the replica to deploy to (else MASON_REPLICA)
   --dry-run                print each file that would be sent, its size and its sha256, and send nothing (no
                            login needed)
-  --timeout <interval>     how long to wait for the outcome (default ${DEFAULT_TIMEOUT}; 1s to 24h); the deploy goes on after it
-  --json                   as data, once it ends: { dryRun, replica (null when none is named on a dry run),
-                           service, files: [{ path, size, sha256 }], totalBytes, warnings (the generated tables
-                           refused, as mason start says them, each one line), deploy ({ id, status (queued,
-                           applying, starting, running, refused, failed), phase (null, checking, writing,
-                           restarting, syncing), createdAt, finishedAt };
-                           null on a dry run), error (when the replica refused it, it failed or the wait timed out:
-                           { code, message, why, fix }), next }
+  --timeout <duration>     how long to wait for the outcome, a wait to send included (default ${DEFAULT_TIMEOUT}; 1s
+                           to 24h; a bare number is seconds); a deploy sent goes on after it
+  --json                   as data: its shape is at the end
+
+  The replica is --replica <org>/<name>, else MASON_REPLICA (each part lower case letters, digits and -). The login
+  is MASON_TOKEN, else this machine's (mason login); the service is MASON_CLOUD_URL, else the default. Progress
+  goes to stderr; the answer is printed when it ends.
+
+  While the replica is being created (or the service asks for a wait: too many deploys at once), it waits as the
+  service asks and sends the deploy again, within --timeout, saying the replica's state and how long it has waited.
+  A replica that failed or is being deleted is refused: mason replica status says its state.
 
   Exit status: 0 the replica runs it (or a dry run printed); 1 refused here or by the service, refused by Mason on
   the replica (its words printed as they came, the code the CLI's own), the deploy failed, or the service answered
   outside its contract; 2 a wrong command line; 124 the wait timed out (nothing stopped: the deploy's id says where
-  to look). Whatever the service sends, it never makes the exit 0, 2 or 124.
+  to look; or, before one was sent, no deploy was made). Whatever the service sends, it never makes the exit 0, 2
+  or 124.
+
+  The --json answer, once it ends: { dryRun, replica (null when none is named on a dry run),
+    service, files: [{ path, size, sha256 }], totalBytes, warnings (the generated tables
+    refused, as mason start says them, each one line), deploy ({ id, status (queued,
+    applying, starting, running, refused, failed), phase (null, checking, writing,
+    restarting, syncing), createdAt, finishedAt };
+    null on a dry run), error (when the replica refused it, it failed or the wait timed out:
+    { code, message, why, fix }), next }
 `,
     options: { replica: { type: "string" }, "dry-run": { type: "boolean", default: false }, timeout: { type: "string" }, json: { type: "boolean", default: false } },
     json: ["dryRun", "replica", "service", "files", "totalBytes", "warnings", "deploy", "error", "next"],
@@ -377,6 +395,29 @@ const STATUS_WORDS = {
     failed: "The deploy failed",
 };
 const NEXT_AGAIN = (r) => [[`mason deploy --replica ${replicaText(r)}`, "deploy again, after the next edit"]];
+/**
+ * THE REPLICA'S STATE, as a `503` or a `409` to the POST may carry it (`{ replica: { state } }`, docs/HOSTED-API.md):
+ * one of a closed set, said in the CLI's words, never the service's text; null when it carries none, or another.
+ * `503`: a replica being made (`checking`, `creating`), or `ready` with the machine it runs on not connected just now —
+ * a wait, and the deploy is sent again. `409`: a replica that cannot take one (`failed`, `deleting`) — refused,
+ * never sent again. A deleted replica is no state here: its name is freed, and the service answers it `404`.
+ */
+export const WAITING_STATES = {
+    checking: "is being checked (Mason checks its database)",
+    creating: "is being created",
+    ready: "is ready, and the machine it runs on is not connected just now",
+};
+export const REFUSED_STATES = {
+    failed: "failed: its creation did not finish",
+    deleting: "is being deleted",
+};
+function replicaStateOf(json, states) {
+    if (!obj(json) || !obj(json.replica) || typeof json.replica.state !== "string")
+        return null;
+    return Object.hasOwn(states, json.replica.state) ? json.replica.state : null;
+}
+/** A wait, as a person reads it: whole seconds, then minutes and seconds. */
+const waited = (ms) => { const n = Math.floor(ms / 1000); return n < 60 ? `${n} s` : `${Math.floor(n / 60)} min ${n % 60} s`; };
 const stateLine = (s) => `${STATUS_WORDS[s.status]}${s.phase ? ` (${PHASES[s.phase]})` : ""}`;
 export async function deploy(argv) {
     const f = parseCommand(DEPLOY, argv);
@@ -387,7 +428,7 @@ export async function deploy(argv) {
     if (f.positionals.length)
         return fail({ message: "it takes no argument", code: "usage", why: "the project is the folder's, the replica --replica's", usage: DEPLOY.usage }, { json });
     const timeoutText = typeof f.values.timeout === "string" ? f.values.timeout : DEFAULT_TIMEOUT;
-    const timeout = parseDuration(timeoutText);
+    const timeout = parseDuration(timeoutText, { min: MIN_POLL_SECONDS, max: MAX_POLL_SECONDS });
     if ("problem" in timeout)
         return fail({ message: `--timeout ${timeout.problem}`, code: "usage", usage: DEPLOY.usage }, { json });
     const replica = replicaOf(typeof f.values.replica === "string" ? f.values.replica : undefined, DEPLOY.usage);
@@ -448,26 +489,91 @@ export async function deploy(argv) {
     const secrets = [token];
     const where = `/v1/replicas/${r.org}/${r.name}/deploys`;
     const started = Date.now(), deadline = started + timeout.seconds * 1000;
-    // THE DEPLOY, SENT: 201 and its id, else the service's failure as it worded it
-    const sent = await call(service, "POST", where, { token, json: { files: files.map(({ path: p, sha256, content }) => ({ path: p, sha256, content })), client: { version: version() } } });
+    const s = errStyle();
+    // a spinner turns only on a terminal wide enough for a label beside its frame; else each line is said once, as on a pipe
+    const terminal = !json && process.stderr.isTTY === true && clipped("x") !== null;
+    const steps = stepRenderer({ line: say, live: terminal ? process.stderr : null, style: s });
+    const name = replicaText(r);
+    const statusStep = [`mason replica status ${name}`, "the replica's state"];
+    // THE DEPLOY, SENT: 201 and its id, else the service's failure as it worded it. A 503 (the replica is being made, or
+    // its machine is not connected; or the service is full) or a 429 (too many deploys at once) says NO deploy was made:
+    // the same body is sent again after the wait it asks (`Retry-After`, else RESEND_MS), within --timeout. No other
+    // answer is ever sent again: a POST that may have made a deploy would make a second.
+    const body = { files: files.map(({ path: p, sha256, content }) => ({ path: p, sha256, content })), client: { version: version() } };
+    let waitSaid = "", waitSaidAt = 0, waitLine = null;
+    let sent = await call(service, "POST", where, { token, json: body });
+    while (!isFailure(sent) && (sent.status === 503 || sent.status === 429)) {
+        const asked = sent;
+        // nothing of a wait's answer is printed but its status and the replica's state (in the CLI's words); still, an
+        // answer that carries the token anywhere but a failure's words is refused whole, as every answer is
+        const j = asked.json;
+        const keys = obj(j) && obj(j.error) ? { ...j, error: { ...j.error, message: null, why: null, fix: null } } : j;
+        if (!carriesNoSecret(keys, secrets)) {
+            if (terminal && waitLine !== null)
+                steps.fail(waitLine);
+            return fail(unexpected(service, asked, "a deploy was sent"), { json });
+        }
+        const st = asked.status === 503 ? replicaStateOf(j, WAITING_STATES) : null;
+        const reason = asked.status === 429 ? "too many deploys are being sent at once"
+            : st !== null ? `${name} ${WAITING_STATES[st]}` : "the service cannot take a deploy just now";
+        const resendAt = Date.now() + (asked.retryAfter !== null ? asked.retryAfter * 1000 : RESEND_MS);
+        for (;;) {
+            waitLine = `Waiting to send the deploy: ${reason} (HTTP ${asked.status}); waited ${waited(Date.now() - started)}`;
+            if (terminal)
+                steps.relabel(clipped(waitLine));
+            else if (!json) {
+                // a line when what it waits on changes, and every 30 s while it does not (`sayAgain`, as mason wait says its block)
+                const what = waitLine.replace(/; waited .*$/, "");
+                if (sayAgain(what, waitSaid, waitSaidAt, Date.now())) {
+                    say(`  ${waitLine}`);
+                    waitSaid = what;
+                    waitSaidAt = Date.now();
+                }
+            }
+            const left = Math.min(resendAt, deadline) - Date.now();
+            if (left <= 0)
+                break;
+            await sleep(Math.min(TICK_MS, left));
+        }
+        if (Date.now() >= deadline) {
+            if (terminal)
+                steps.fail(waitLine);
+            return fail({ message: `the deploy to ${name} was not sent within ${timeout.every}`, code: "timeout",
+                why: `the service asked to wait: ${reason} (HTTP ${asked.status}); no deploy was made`,
+                fix: `mason deploy again once ${name} is ready (mason replica status ${name} says its state); a longer wait is --timeout 30m`,
+                next: [statusStep, [`mason deploy --replica ${name}`, "deploy again"]] }, { json });
+        }
+        sent = await call(service, "POST", where, { token, json: body });
+    }
+    if (terminal && waitLine !== null)
+        steps.done(waitLine);
     if (isFailure(sent)) {
         return fail({ ...sent, why: `${sent.why ?? ""}${sent.why ? "; " : ""}whether the deploy was made is not known`,
             fix: `${sent.fix ?? "check this machine is online"}, then mason deploy again (a deploy still running is refused as busy)` }, { json });
     }
-    if (sent.status !== 201)
-        return fail(serviceFailure(sent, secrets) ?? unexpected(service, sent, "a deploy was sent"), { json });
+    if (sent.status !== 201) {
+        // a 409 that names the replica's state: it cannot take a deploy (failed, being deleted), never sent again;
+        // the next step is the replica's status, the CLI's own (never the generic "mason login")
+        const refused = sent.status === 409 ? replicaStateOf(sent.json, REFUSED_STATES) : null;
+        // a 404: no such replica, a deleted one included (its name is freed): the organisation's replicas, never mason login
+        const notFound = (st) => st === 404
+            ? [[`mason replica list ${r.org}`, "the organisation's replicas: this one was deleted, or never existed"]] : serviceNext(st);
+        if (refused === null)
+            return fail(serviceFailure(sent, secrets, notFound) ?? unexpected(service, sent, "a deploy was sent"), { json });
+        const f = serviceFailure(sent, secrets, () => [statusStep]);
+        if (f === null)
+            return fail(unexpected(service, sent, "a deploy was sent"), { json });
+        return fail({ ...f, why: `${name} ${REFUSED_STATES[refused]}; ${f.why}`,
+            fix: f.fix ?? `a replica takes a deploy only once it is ready: mason replica status ${name} says its state` }, { json });
+    }
     // what to run after a refused or failed deploy: the CLI's own step, never one the service names
-    const again = [[`mason deploy --replica ${replicaText(r)}`, "deploy again, once what it says is fixed"]];
+    const again = [[`mason deploy --replica ${name}`, "deploy again, once what it says is fixed"]];
     const first = deployStateOf(sent.json, null, secrets, again);
     if (first === null || first.status !== "queued")
         return fail(unexpected(service, sent, "a deploy was sent"), { json });
     const id = first.id;
-    const s = errStyle();
-    // a spinner turns only on a terminal wide enough for a label beside its frame; else each line is said once, as on a pipe
-    const terminal = !json && process.stderr.isTTY === true && clipped("x") !== null;
-    const steps = stepRenderer({ line: say, live: terminal ? process.stderr : null, style: s });
     if (!json)
-        say(`Sent ${files.length} file${files.length === 1 ? "" : "s"} (${bytes(totalBytes)}) to ${replicaText(r)} on ${service.base}: deploy ${id}`);
+        say(`Sent ${files.length} file${files.length === 1 ? "" : "s"} (${bytes(totalBytes)}) to ${name} on ${service.base}: deploy ${id}`);
     // THE WAIT: a line when the state changes (and every 30 s while it does not), a spinner beside it on a terminal
     let state = first, said = "", saidAt = 0, unsure = null, unsureSaid = null;
     const show = (line) => {

package/dist/src/cli/doctor.js

@@ -32,8 +32,13 @@ export const DOCTOR_USAGE = `usage: mason doctor [--json]
   Says whether this machine is ready for Mason — Node ${NODE_MIN} or later, memory (what the engine may use and what it
   leaves beside it; MASON_DUCKDB_MEMORY=4GiB sets it), Mason's postgres and inet extensions (installed with Mason for this
   platform, so nothing is downloaded; else the first sync downloads them), the ports Mason listens on — with the way
-  out for anything missing. In a
-  project's folder it checks the project's database too; with Mason running for it, the run in a few lines instead: its
+  out for anything missing.
+
+    mason doctor
+
+  --json   as data: its shape is at the end
+
+  In a project's folder it checks the project's database too; with Mason running for it, the run in a few lines instead: its
   database, whether every added table is synced, the statements of the last day it refused or answered slowly. Both
   say whether the user Mason connects as could change a synced table's rows (a superuser, BYPASSRLS, an owner of a
   synced table, a write privilege on one or CREATE on its schema; or a write that reaches its rows through a
@@ -41,16 +46,14 @@ export const DOCTOR_USAGE = `usage: mason doctor [--json]
   reaches; a foreign server; ADMIN OPTION or a server role; directly or through a role it is a member of), with the
   statements that make a role that only reads.
 
-    mason doctor
-
-  --json   as data: { ready, verdict, checks: [{ name, ok, detail, warn, code, fix }], next: [{ command, what }] }; ok
-           is true, false, or null when it could not tell; warn (only when true): fine to run, but said loudly; code
-           (the role's lines): ${ROLE_CODES.slice(0, 5).join(", ")},
-           ${ROLE_CODES.slice(5).join(", ")};
-           fix (with code): the statements and the edit that make a role that only reads
-
   Exit status: 0 nothing failed — a warning (!) and a check that could not tell (?) are said, and leave it 0; 1
   something failed (said, with the way out).
+
+  The --json answer: { ready, verdict, checks: [{ name, ok, detail, warn, code, fix }], next: [{ command, what }] }; ok
+    is true, false, or null when it could not tell; warn (only when true): fine to run, but said loudly; code
+    (the role's lines): ${ROLE_CODES.slice(0, 5).join(", ")},
+    ${ROLE_CODES.slice(5).join(", ")};
+    fix (with code): the statements and the edit that make a role that only reads
 `;
 export const DOCTOR = {
     name: "doctor",
@@ -255,7 +258,7 @@ export function nextSteps(checks, run, project) {
     if (project === null)
         return [
             ["mason init", "in your app's folder: the database from MASON_DATABASE_URL or DATABASE_URL in .env.local, .env or the shell"],
-            ["mason init postgres://user:password@localhost:5432/your_app", "or name it"],
+            ["mason init - < db-url.txt", "or its URL on stdin"],
         ];
     if (run === null)
         return [["mason start", "Mason in the background, for this folder"]];

package/dist/src/cli/guides.js

@@ -110,18 +110,29 @@ ${keys}
 async function agentGuide() {
     // imported here, not at the top: the registry imports this file for the HELP usage
     const { STEPS } = await import("./registry.js");
-    const { FAILURE_CODES } = await import("./command.js");
+    const { EXIT_CODES, FAILURE_CODES, TIMEOUT_COMMANDS } = await import("./command.js");
     const { GENERATED_DIR } = await import("./generated-files.js");
     const w = Math.max(...STEPS.flatMap(([, cs]) => cs.map((c) => c.name.length))) + "mason  --json".length;
     const commands = STEPS.map(([step, cs]) => `  ${step}\n${cs.map((c) => `    ${`mason ${c.name}${Object.hasOwn(c.options, "json") ? " --json" : ""}`.padEnd(w)}  ${c.summary}`).join("\n")}`).join("\n");
-    const codes = Object.entries(FAILURE_CODES).map(([code, what]) => `    ${code.padEnd(12)} ${what}`).join("\n");
+    const codes = Object.entries(FAILURE_CODES).map(([code, what]) => `    ${code.padEnd(13)} ${what}`).join("\n");
     return `DRIVING MASON FROM A CODING AGENT — the same commands a person runs, answered as data
 
-  Every command prints for a person, or with --json one JSON object for a program. One prints text alone: mason help
-  (this reference); mason mcp's stdout is the MCP protocol's, so it takes no --json and says a failure to start on
-  stderr; mason logs --json is the log's entries ({ at, text }), or with --requests the request log, --events the sync's
-  events, --running the statements running now. Nothing a command prints
-  refers to a file this package does not ship.
+  Every command prints for a person, or with --json one JSON object for a program. mason mcp's stdout is the MCP
+  protocol's, so it takes no --json and says a failure to start on stderr; mason logs --json is the log's entries
+  ({ at, text }), or with --requests the request log, --events the sync's events, --running the statements running now.
+  mason version --json is { version, next }. Nothing a command prints refers to a file this package does not ship.
+
+  EVERY COMMAND'S SPEC, AS DATA: mason <command> --help --json (or mason help <command> --json) is { command: <spec>,
+  next }; mason help --json is { version, commands: [<spec>…], guides: [{ name, summary }], failureCodes: [{ code,
+  meaning }], next }. A <spec> is read from the same description --help prints, so the two cannot drift:
+    name, summary, usage   usage is the text --help prints
+    forms                  [{ synopsis, positionals }]: each form of the synopsis, and its words that are no option
+    options                [{ name, short, type, multiple, default, value }]: every option, --help too; type
+                           "string" or "boolean"; short, default and value (a string option's placeholder) null if none
+    json                   the top-level keys of its --json answer, next last; null when it takes no --json
+    needs                  "project", "run" or null
+    stdout                 "protocol" for mason mcp, else null
+    exitCodes              [{ code, meaning }]: the exit codes below it can exit with
 
   AN AGENT WITH MCP (Claude Code, Claude Desktop, any MCP client) adds Mason as an MCP server first, then asks with
   its tools rather than through a shell: tables (each synced table's rows and how current it is), describe, query (rows with
@@ -141,10 +152,8 @@ ${commands}
 
   A FAILURE is { "error": { "code", "message", "why", "fix" }, "next": […] } on stdout ("why" and "fix" where there is
   more to say than the message), and the exit code says it — the same code exits the same wherever it is found:
-    0  done
-    1  failed, with the reason
-    2  the command line is wrong (without --json the usage follows)
-    124  ran out of time: mason wait, mason deploy, mason replica create (nothing stopped)
+${Object.entries(EXIT_CODES).map(([code, meaning]) => `    ${code}  ${code === "124" ? `${meaning}: ${TIMEOUT_COMMANDS}` : meaning}`).join("\n")}
+  A wrong command line's next steps end with mason <command> --help, and its fix says what to change.
   The codes:
 ${codes}
 

package/dist/src/cli/hosted.js

@@ -689,7 +689,7 @@ export function failureShape(error, secrets, as) {
  * the mask would change is no page to send a person to: either refuses it. An honest page is refused by the mask with
  * a probability under 1 in a million (it must hold 3 runs of 4 of a 43-character body by chance).
  */
-function pageUrl(service, v, secrets) {
+export function pageUrl(service, v, secrets) {
     if (!str(v, 2048))
         return null;
     let u;

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