@mason-data/cli 0.9.0 → 0.10.0

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";
@@ -37,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
@@ -45,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
@@ -61,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
@@ -78,42 +90,36 @@ export const DEV = {
   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 ${DEFAULT_UI_PORT}, 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 ? DEFAULT_UI_PORT : 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"] });
@@ -127,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:
@@ -135,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
@@ -198,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"]]
@@ -238,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 a wait timed out (mason wait, mason deploy, mason replica create). 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");
 }