@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/readiness.js

@@ -55,19 +55,30 @@ export function copyProgress(source, copied, rowsEstimate, p) {
     const c = copyingText(copied, rowsEstimate, p);
     return `${source}: ${c.fraction !== null ? `syncing ${Math.floor(c.fraction * 100)}% · ` : /^\d/.test(c.text) ? "syncing " : ""}${c.text}`;
 }
-export function syncStateOf(c) {
+export function syncStateOf(c, now = Date.now()) {
     if (c === undefined || c.phase === "waiting")
         return "waiting";
     if (c.phase === "failed" || c.error !== null)
         return "failed";
     if (c.phase === "copying" || c.rebuilding !== undefined || c.behind !== undefined)
         return "syncing";
-    return "synced";
+    return (behindOf(c.kept, now).behindBySeconds ?? 0) > 0 ? "behind" : "synced";
+}
+export function behindOf(k, now) {
+    if (k === undefined || k.by === "generated")
+        return { asOf: null, promisedSeconds: null, behindBySeconds: null, behindWhy: null };
+    const asOf = k.by === "recopy" ? k.syncedAt ?? k.copiedAt : k.syncedAt;
+    const promisedSeconds = k.promisedSeconds ?? null;
+    if (promisedSeconds === null || asOf === null)
+        return { asOf, promisedSeconds, behindBySeconds: null, behindWhy: null };
+    const over = (now - Date.parse(asOf)) / 1000 - promisedSeconds;
+    return over > 0 ? { asOf, promisedSeconds, behindBySeconds: Math.round(over * 10) / 10, behindWhy: k.lateWhy ?? "its next sync is late" }
+        : { asOf, promisedSeconds, behindBySeconds: 0, behindWhy: null };
 }
 export function tableSync(c, now) {
     const s = c?.synced;
-    return { state: syncStateOf(c), syncedAt: s?.at ?? null, syncSeconds: s?.seconds ?? null, syncedBy: s?.by ?? null,
-        ageSeconds: s === undefined ? null : Math.max(0, Math.round((now - Date.parse(s.at)) / 100) / 10) };
+    return { state: syncStateOf(c, now), syncedAt: s?.at ?? null, syncSeconds: s?.seconds ?? null, syncedBy: s?.by ?? null,
+        ageSeconds: s === undefined ? null : Math.max(0, Math.round((now - Date.parse(s.at)) / 100) / 10), ...behindOf(c?.kept, now) };
 }
 export function syncTotals(added, copies) {
     const copied = copies.filter((c) => c.phase === "copied");
@@ -95,8 +106,12 @@ export function readinessWord(r) {
 export function readiness(s) {
     const failed = [], waiting = [];
     for (const t of s.tables.filter((t) => t.added)) {
-        if (t.error) {
-            failed.push(`${t.table}: ${firstLine(t.error)}`);
+        // the table's state in one word (`syncStateOf`), never a second reading of its error or phase: a copied table whose
+        // poll, catch-up, stream or publication check failed is failed here as it is there (issues 100, 82). Behind is said
+        // on its line, never a failure: it is served and being kept. A run from before `sync` was said: its error and phase.
+        const state = t.sync?.state ?? (t.error ? "failed" : t.copy?.phase === "copying" ? "syncing" : !t.copy ? "waiting" : "synced");
+        if (state === "failed") {
+            failed.push(`${t.table}: ${firstLine(t.error ?? "its sync failed (mason status says why)")}`);
             continue;
         }
         if (t.copy?.phase === "copying") {
@@ -108,3 +123,24 @@ export function readiness(s) {
     }
     return { ready: failed.length === 0 && waiting.length === 0, failed, waiting };
 }
+/**
+ * WHERE A GENERATED TABLE IS, for `mason wait <table>`: ready once it is served and holds every base change Mason had
+ * synced when the wait began (`since`, ms), across its chain — nothing behind (`behindSince` null), or only changes
+ * committed after it began. A last run that failed, or a parent that blocks it, is a failure, so an agent is never left
+ * waiting for a run that cannot come. The marks are the run's clock and `since` this machine's: `mason wait` reads a run
+ * on this machine.
+ */
+export function generatedReadiness(g, since) {
+    const caught = g.serving && (g.behindSince === null || Date.parse(g.behindSince) > since);
+    if (caught)
+        return { ready: true, failed: [], waiting: [] };
+    const fail = (why) => ({ ready: false, failed: [`${g.table}: ${why}`], waiting: [] });
+    if (g.error !== null)
+        return fail(`its last run failed: ${firstLine(g.error)}`);
+    if (g.state === "refused" && !g.serving)
+        return fail(`refused: ${g.refusals[0]?.message ?? "mason status says why"}`);
+    if (g.waitingFor !== null && /(failed its last run|is refused)$/.test(g.waitingFor))
+        return fail(`not run, because ${g.waitingFor}`);
+    return { ready: false, failed: [], waiting: [`${g.table}: ${!g.serving ? g.waitingFor === null ? "being built" : `waiting for ${g.waitingFor}` :
+                `${Math.round(g.behindSeconds)} s behind its bases; its next run brings in what was synced before the wait`}`] };
+}

package/dist/src/cli/registry.js

@@ -3,7 +3,7 @@
  * command's summary, in this order — so a command cannot exist without being listed, and tests/cli-help.test.ts holds
  * each one to src/cli/command.ts's rules (its own --help, an example, every option documented).
  */
-import { failed, parseCommand, reportText, wantsJson } from "./command.js";
+import { FAILURE_CODES, SPEC_NEXT, failed, jsonText, parseCommand, reportText, specAnswer, specJson, wantsJson } from "./command.js";
 import { removedStartFlags } from "../lib/table-sync.js";
 import { sourcesTop } from "./sources.js";
 import { dev } from "./dev.js";
@@ -12,6 +12,7 @@ import { ADD, LOGS, REMOVE, STATUS, STOP, TABLES, WAIT, add, logs, remove, statu
 import { USER, user } from "./user.js";
 import { MCP, mcp } from "./mcp.js";
 import { SHARE, share } from "./share.js";
+import { DEFAULT_UI_PORT } from "./ports.js";
 import { UI, ui } from "./ui.js";
 import { GUIDES, guideText } from "./guides.js";
 import { DOCTOR, NODE_MIN, doctor } from "./doctor.js";
@@ -21,6 +22,10 @@ import { SYNC, sync } from "./sync.js";
 import { USAGE, usage } from "./usage.js";
 import { CANCEL, cancel } from "./cancel.js";
 import { SERVE, serve } from "./serve.js";
+import { LOGIN, LOGOUT, login, logout } from "./login.js";
+import { DEPLOY, deploy } from "./deploy.js";
+import { REPLICA, replica } from "./replica-hosted.js";
+import { TOKEN, token } from "./token-hosted.js";
 import { PROJECT_LINE } from "./dev.js";
 import { version } from "./version.js";
 import { didYouMean } from "../lib/did-you-mean.js";
@@ -32,7 +37,7 @@ export const DEV = {
     needs: "project",
     name: "start",
     summary: "start Mason for this folder's project, in the background (mason init makes the project)",
-    usage: `usage: mason start [--attach] [--self-signed-tls] [--port <n>] [--json]
+    usage: `usage: mason start [--attach] [--self-signed-tls] [--ui-port <n>] [--json]
 
   Starts Mason for the project of this folder (mason init made it): one process, which syncs the tables you add
   (mason add) from the project's database into its own file, keeps them current as the sources file says, and answers
@@ -40,6 +45,17 @@ export const DEV = {
   its sync: says replication). It returns once Mason is up; run it again any time (it says so when Mason is
   already running). The synced data and Mason's state stay between runs: the next start resumes.
 
+    mason start
+    mason start --attach      in the foreground: Ctrl-C stops it
+    MASON_PG_HOST=0.0.0.0 mason start --self-signed-tls   the Postgres API for other machines, over TLS
+
+  --attach            stay in the foreground (Ctrl-C stops Mason)
+  --self-signed-tls   the Postgres API requires TLS, from a certificate made for this project in .mason/ (kept and
+                      served again by every later start with the flag); not with MASON_PG_TLS_CERT / _KEY
+  --ui-port <n>       the port of its web page and of the mason commands, on 127.0.0.1 (default ${DEFAULT_UI_PORT}, or the
+                      next free one); MASON_UI_PORT on a server, never the Postgres API's (MASON_PG_PORT)
+  --json              as data, once it is up: { running, pid, postgres: { url, host, port, database, sslmode }, next }
+
   After its first sync, each table is kept current as the sources file's sync: says — at the top for every table, or
   on a table's entry: off (the default, which mason init writes) reads it again only when you run mason sync <table>;
   poll <interval> (poll 5s, poll 5m, poll 1h) polls it with SELECTs at that interval; replication reads its changes
@@ -56,7 +72,8 @@ export const DEV = {
   created, altered or dropped — Mason makes only its slot. A read replica needs one (it takes no CREATE PUBLICATION).
 
   --replication, --poll and --publication are gone: each answers with the line to write at the top of the sources
-  file (sync: replication, sync: poll 5m, publication: <name>) and exit 2, and starts nothing.
+  file (sync: replication, sync: poll 5m, publication: <name>) and exit 2, and starts nothing. --port is now
+  --ui-port: it answers with the line to run and exit 2.
 
   The Postgres API's port is the project's: the first start takes 5433, or the next port free on every address when a
   second Postgres holds it, and records it; every later start listens on the same port, so a BI tool's saved connection
@@ -68,44 +85,41 @@ export const DEV = {
   MASON_PG_TLS_KEY (PEM files), or --self-signed-tls, which makes a certificate for the project in .mason/ and serves
   it again at every later start with the flag. Every client then connects with sslmode=require. A team whose own proxy
   or load balancer terminates TLS keeps it on 127.0.0.1, or sets MASON_PG_PLAIN=1 for a private network.
+  Behind a TCP proxy that sends the PROXY protocol v2, MASON_PG_PROXY_FROM=<cidr>[,<cidr>…] names the proxy's own
+  addresses: a connection from one must begin with the header, whose client the request log names, and a header from
+  any other address is refused.
 
   ${PROJECT_LINE}
-
-    mason start
-    mason start --attach      in the foreground: Ctrl-C stops it
-    MASON_PG_HOST=0.0.0.0 mason start --self-signed-tls   the Postgres API for other machines, over TLS
-
-  --attach            stay in the foreground (Ctrl-C stops Mason)
-  --self-signed-tls   the Postgres API requires TLS, from a certificate made for this project in .mason/ (kept and
-                      served again by every later start with the flag); not with MASON_PG_TLS_CERT / _KEY
-  --port <n>          the port the mason commands reach it on (default 4039, or the next free one)
-  --json              as data, once it is up: { running, pid, postgres: { url, host, port, database, sslmode }, next }
 `,
     options: {
-        port: { type: "string" }, attach: { type: "boolean", default: false }, json: { type: "boolean", default: false },
+        "ui-port": { type: "string" }, attach: { type: "boolean", default: false }, json: { type: "boolean", default: false },
         "self-signed-tls": { type: "boolean", default: false },
     },
     json: ["running", "pid", "postgres", "next"],
 };
 async function runDev(argv) {
-    // --replication, --poll and --publication are gone (issue 33): each answered with the edit to make in the sources
+    // --replication, --poll and --publication are gone (issue 33), and --port is --ui-port: each answered with the edit to make in the sources
     // file, exit 2, before the options are parsed (it would be an unknown option there) and before anything starts. The
     // file is read only when one is given. A decision: `mason start --replication --help` answers the refusal, not the
     // usage — the flag is wrong whatever else the line asks
     const removed = removedStartFlags(argv, () => startSourcesTop(process.cwd()));
-    if (removed !== null)
-        return failed("start", { code: "usage", ...removed, next: [["mason start", "each table kept current as its sync: says"], ["mason help production", "sync: and publication:, and what each needs"]] }, { json: wantsJson(argv, DEV) });
+    if (removed !== null) {
+        const { start, sync, ...said } = removed;
+        const next = sync ? [[start, "each table kept current as its sync: says"], ["mason help production", "sync: and publication:, and what each needs"]]
+            : [[start, "Mason, its web page and the commands on that port"]];
+        return failed("start", { code: "usage", ...said, next }, { json: wantsJson(argv, DEV) });
+    }
     const f = parseCommand(DEV, argv);
     if (typeof f === "number")
         return f;
     const v = f.values;
     if (f.positionals.length) {
         // the database is the project's now: a URL here is the old habit, answered with the new way
-        return failed("start", { message: "it takes no database URL: the project has one", code: "usage", why: "mason init <url> made it; .mason/config.json holds it", usage: DEV.usage }, { json: v.json });
+        return failed("start", { message: "it takes no database URL: the project has one", code: "usage", why: "mason init <url> made it; .mason/config.json holds it", fix: "run mason start alone", usage: DEV.usage }, { json: v.json });
     }
-    const port = v.port === undefined ? 4039 : Number(v.port);
+    const port = v["ui-port"] === undefined ? DEFAULT_UI_PORT : Number(v["ui-port"]);
     if (!Number.isInteger(port) || port < 1 || port > 65_535)
-        return failed("start", { message: `--port must be a port number (1-65535), not ${JSON.stringify(v.port)}`, code: "usage" }, { json: v.json });
+        return failed("start", { message: `--ui-port must be a port number (1-65535), not ${JSON.stringify(v["ui-port"])}`, code: "usage" }, { json: v.json });
     if (!v.attach)
         return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"] });
     return dev({ port, version: version(), selfSignedTls: v["self-signed-tls"] });
@@ -119,7 +133,7 @@ function startSourcesTop(cwd) {
 export const HELP = {
     name: "help",
     summary: "the commands by step, or one command's usage: mason help add",
-    usage: `usage: mason help [<command> | <guide>]
+    usage: `usage: mason help [<command> | <guide>] [--json]
 
   The commands by step (mason help), how to use one (mason help add — the same as mason add --help), or a guide,
   offline, short enough to read whole and listing exactly what Mason accepts:
@@ -127,35 +141,74 @@ export const HELP = {
     mason help
     mason help add
 ${Object.entries(GUIDES).map(([k, v]) => `    mason help ${k.padEnd(14)} ${v}`).join("\n")}
+    mason help --json         every command's spec as data (mason help agent says its shape)
+
+  --json   as data: mason help, { version, commands: [<spec>…], guides: [{ name, summary }], failureCodes:
+           [{ code, meaning }], next }; mason help <command> (the same as mason <command> --help --json), { command:
+           <spec>, next }; mason help <guide>, { guide: { name, summary, text }, next }
 `,
-    options: {},
+    options: { json: { type: "boolean", default: false } },
+    json: ["version", "commands", "guides", "failureCodes", "command", "guide", "next"],
 };
+/** `mason version` (also `--version`, `-v`): the CLI's version, as text or with --json as data. Answered by main.ts
+ *  before the registry, so not one of COMMANDS; described here so `mason help version` and its --json read one spec. */
+export const VERSION = {
+    name: "version",
+    summary: "the CLI's version",
+    usage: `usage: mason version [--json]
+
+  The CLI's version (mason --version and mason -v are the same):
+
+    mason version
+
+  --json   as data: { version, next }
+`,
+    options: { json: { type: "boolean", default: false } },
+    json: ["version", "next"],
+};
+/** `mason version` (and `--version`, `-v`): its line read by VERSION, as every command's is by its spec, so what it
+ *  accepts is what its spec as data says — `--help`, `--help --json`, a wrong option or an argument refused (exit 2). */
+export function runVersion(argv) {
+    const f = parseCommand(VERSION, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    if (f.positionals.length)
+        return failed("version", { message: `it takes no argument: ${f.positionals.join(" ")}`, code: "usage", usage: VERSION.usage }, { json });
+    process.stdout.write(`${json ? jsonText(VERSION, { version: version() }) : version()}\n`);
+    return 0;
+}
 async function runHelp(argv) {
     const f = parseCommand(HELP, argv);
     if (typeof f === "number")
         return f;
+    const json = f.values.json === true;
     const [asked, ...rest] = f.positionals;
     if (rest.length)
-        return failed("help", { message: "one command or guide at a time", code: "usage", usage: HELP.usage }, { json: false });
+        return failed("help", { message: "one command or guide at a time", code: "usage", usage: HELP.usage }, { json });
     if (asked === undefined) {
-        process.stdout.write(topUsage());
-        return 0;
-    }
-    if (asked === "version") {
-        process.stdout.write("usage: mason version (or --version, -v): the CLI's version\n");
+        if (!json) {
+            process.stdout.write(topUsage());
+            return 0;
+        }
+        process.stdout.write(`${jsonText(HELP, {
+            version: version(), commands: [...COMMANDS, VERSION].map(specJson), guides: Object.entries(GUIDES).map(([name, summary]) => ({ name, summary })),
+            failureCodes: Object.entries(FAILURE_CODES).map(([code, meaning]) => ({ code, meaning })),
+        }, [["mason help agent", "driving Mason from a coding agent: these shapes, the failures and the exit codes"]])}\n`);
         return 0;
     }
     if (Object.hasOwn(GUIDES, asked)) {
-        process.stdout.write(await guideText(asked));
+        const text = await guideText(asked);
+        process.stdout.write(json ? `${jsonText(HELP, { guide: { name: asked, summary: GUIDES[asked], text } }, SPEC_NEXT)}\n` : text);
         return 0;
     }
-    const cmd = COMMANDS.find((c) => c.name === asked);
+    const cmd = asked === "version" ? VERSION : COMMANDS.find((c) => c.name === asked);
     if (cmd) {
-        process.stdout.write(cmd.usage);
+        process.stdout.write(json ? `${specAnswer(cmd)}\n` : cmd.usage);
         return 0;
     }
     return failed("help", { message: `there is no command or guide ${JSON.stringify(asked)}${didYouMean(asked, [...COMMANDS.map((c) => c.name), ...Object.keys(GUIDES)])}`, code: "usage",
-        why: `the guides: ${Object.keys(GUIDES).join(", ")}`, next: [["mason help", "every command"]] }, { json: false });
+        why: `the guides: ${Object.keys(GUIDES).join(", ")}`, fix: "name a command or a guide mason help lists", next: [["mason help", "every command"]] }, { json });
 }
 /**
  * EVERY COMMAND, IN THE ORDER A FIRST SESSION NEEDS THEM (listed in the order a developer will likely need them, the
@@ -169,7 +222,7 @@ export const STEPS = [
     ["Add your tables", [{ ...TABLES, run: tables }, { ...ADD, run: add }, { ...REMOVE, run: remove }, { ...WAIT, run: wait }]],
     ["Connect", [{ ...USER, run: user }, { ...MCP, run: mcp }, { ...SHARE, run: share }]],
     ["Run", [{ ...STATUS, run: status }, { ...UI, run: ui }, { ...SYNC, run: sync }, { ...LOGS, run: logs }, { ...CANCEL, run: cancel }, { ...USAGE, run: (argv) => usage(argv) }, { ...STOP, run: stop }, { ...DESTROY, run: (argv) => destroy(argv) }]],
-    ["Go to production", [{ ...SERVE, run: serve }]],
+    ["Go to production", [{ ...SERVE, run: serve }, { ...LOGIN, run: login }, { ...LOGOUT, run: logout }, { ...REPLICA, run: replica }, { ...TOKEN, run: token }, { ...DEPLOY, run: deploy }]],
 ];
 /** Every command, in the order `mason --help` lists them. */
 export const COMMANDS = STEPS.flatMap(([, commands]) => commands);
@@ -190,7 +243,7 @@ export async function orientation(cwd, s = styleOut()) {
         ? [["Project", `${project.config.name}, files in ${project.folder}`], ["Mason", run ? `running (pid ${run.pid})` : "not running"]]
         : [["Project", "none here: mason init makes this folder one"]];
     const next = !project
-        ? [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"],
+        ? [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or its URL on stdin: mason init -)"],
             ["mason init demo", "or try it on a demo database Mason makes itself: nothing to install"],
             ["mason doctor", "what this machine needs for Mason, and whether it has it"]]
         : !run ? [["mason start", "start Mason for this project, in the background"], ["mason status", "the project and its tables"]]
@@ -230,10 +283,10 @@ export function topUsage(s = styleOut()) {
         listed.map(([step, es]) => `  ${s.bold(step)}\n${block(es)}`).join("\n\n"),
         "",
         para("mason <command> --help (or mason help <command>) says how to use one, with examples; the guides are offline and short enough to read whole."),
-        para("A command means the project of the folder it runs in (or above it)."),
+        para("A command means the project of the folder it runs in (or above it); mason -C <folder> <command> runs it as if started in that folder."),
         para("Every command but help and mcp (whose stdout is the MCP protocol's) takes --json: one JSON object for a program, always with next (what to run " +
             "next); a failure is { error: { code, message, why, fix }, next }. The exit code says how it went: 0 done, 1 failed " +
-            "with the reason, 2 a wrong command line, 124 mason wait timed out. Driving Mason from a coding agent: mason help agent."),
+            "with the reason, 2 a wrong command line, 124 a wait timed out (mason wait, mason deploy, mason replica create, mason replica delete). Driving Mason from a coding agent: mason help agent."),
         "",
     ].join("\n");
 }