@mason-data/cli 0.9.0 → 0.11.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/dev.js

@@ -29,6 +29,7 @@ import * as path from "node:path";
 import { choosePgPort, freePort } from "./ports.js";
 import { failed } from "./command.js";
 import { checkSource, connectSource, maskedUrl, readSourceFacts, remoteConfirmation, remoteWarning } from "./preflight.js";
+import { uiReadOnlySetting } from "./ui-read-only.js";
 import { createRunServer, listenOnLoopback, metricsFacts, usageFacts } from "./run-server.js";
 import { readGenerated } from "./generated-files.js";
 import { addedTables, effectiveSync, entryName, replicatedEntries, rereadSources, shownPath, syncWritten } from "./sources.js";
@@ -789,6 +790,10 @@ async function run(o, hosted) {
         version: o.version, startedAt,
         // the web page (mason ui): on loopback alone, so mason serve's is reached through mason ui --ssh
         page: true, served: o.serve !== undefined,
+        // MASON_UI_READ_ONLY=1: a server's page refuses every change it asks for (mason start refuses the setting above)
+        pageReadOnly: o.serve !== undefined && uiReadOnlySetting(process.env) === true,
+        // MASON_UI_SOCKET: the page on a Unix socket too (src/cli/ui-socket.ts), or null
+        pageSocket: o.serve?.socket ?? null,
         demo: cfg.demo === true,
         users: { file: path.join(home, USERS_FILE), apiKey: cfg.apiKey, database, postgresUrl },
         // the roles as the listener holds them: their row filters checked by its catalog (a filter Postgres refuses is a problem)
@@ -824,6 +829,7 @@ async function run(o, hosted) {
             restarts: () => readRestarts(home), jsonPaths: () => sync.kept.status(), generated: () => sync.generated.status() },
     };
     const server = createRunServer(runCtx);
+    o.serve?.page?.(server);
     // a sample is /api/state's facts at its moment (src/cli/run-server.ts usageFacts): one computation of each
     usage.start(() => usageFacts(runCtx));
     await listenOnLoopback(server, setupPort);
@@ -867,6 +873,8 @@ async function run(o, hosted) {
     // the stop is in place BEFORE the ready line: a supervisor or a test signals on reading it, and a SIGTERM that found
     // no handler would end the run with the default action, never recording `running: null`
     let stopping = false;
+    // the run's own stop, for a step of a serve's ready that failed (`ServeHooks.ready`): its words are what lastStop says
+    let stopFor = () => undefined;
     const stopped = new Promise((resolve) => {
         // a crash of the engine's thread: the run exits 1 with its reason in V8's fatal form, which the supervisor reads
         // (src/cli/supervise.ts crashReason), and its config still says it runs, so the supervisor starts it again
@@ -889,7 +897,7 @@ async function run(o, hosted) {
                 resolve(1);
             })();
         };
-        const stop = (signal) => {
+        const stop = (signal, how) => {
             if (stopping)
                 return;
             stopping = true;
@@ -965,14 +973,16 @@ async function run(o, hosted) {
                         (repl.owned ? "" : `; publication ${repl.publication} is its owner's, left as it is`));
                 cfg.running = null;
                 // how it ended, for mason status once it is gone (a kill records nothing: mason stop writes that one)
-                cfg.lastStop = { at: new Date().toISOString(), how: signal === "SIGINT" ? "stopped from its terminal (SIGINT)" : `stopped by mason stop, or a shutdown (${signal})` };
+                cfg.lastStop = { at: new Date().toISOString(), how: how ?? (signal === "SIGINT" ? "stopped from its terminal (SIGINT)" : `stopped by mason stop, or a shutdown (${signal})`) };
                 writeConfig(home, cfg);
                 log.end();
                 resolve(0);
             })();
         };
-        process.on("SIGINT", stop);
-        process.on("SIGTERM", stop);
+        // wrapped: Node calls a signal's listener with (name, number), and the number must never be read as `how`
+        process.on("SIGINT", () => { stop("SIGINT"); });
+        process.on("SIGTERM", () => { stop("SIGTERM"); });
+        stopFor = (how) => { stop("SIGTERM", how); };
     });
     say("");
     say(`  Postgres  ${withPlaceholders(postgresUrl)}  (mason user add <name> makes a user)`);
@@ -985,9 +995,15 @@ async function run(o, hosted) {
     const elsewhere = elsewhereTip(pgTls.listener);
     if (elsewhere)
         say(`  ${elsewhere}`);
+    // before the ready line: what a serve writes when it answers (MASON_UI_RUN_FILE) is there when a supervisor reads it
+    // a step of it that failed stops the run, said in its words, and the ready line is never printed: it did not get ready
+    const notReady = o.serve?.ready({ tables: () => sync.state(), metrics: () => metricsFacts(runCtx), page: { port: setupPort, token } }) ?? null;
+    if (notReady !== null) {
+        stopFor(notReady);
+        return await stopped;
+    }
     say(READY);
     say("");
-    o.serve?.ready({ tables: () => sync.state(), metrics: () => metricsFacts(runCtx) });
     return await stopped;
 }
 /**

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;