@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/registry.js

@@ -3,19 +3,29 @@
  * 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 } from "./command.js";
+import { failed, parseCommand, reportText, wantsJson } from "./command.js";
+import { removedStartFlags } from "../lib/table-sync.js";
+import { sourcesTop } from "./sources.js";
 import { dev } from "./dev.js";
 import { devInBackground } from "./background.js";
 import { ADD, LOGS, REMOVE, STATUS, STOP, TABLES, WAIT, add, logs, remove, status, stop, tables, wait } from "./commands.js";
 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";
 import { DESTROY, destroy } from "./machine.js";
 import { INIT, init } from "./init.js";
 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";
@@ -27,21 +37,31 @@ 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] [--replication [--publication <name>] | --poll] [--self-signed-tls] [--port <n>] [--json]
+    usage: `usage: mason start [--attach] [--self-signed-tls] [--port <n>] [--json]
 
-  Starts Mason for the project of this folder (mason init made it): one process, which copies the tables you add
-  (mason add) from the project's database into its own file, keeps them current, and answers the Postgres protocol
-  for BI tools and your app. It only reads the database (SELECT): no wal_level, replication slot or publication is
-  needed or made. It returns once Mason is up; run it again any time (it says so when Mason is already running). The
-  copy and Mason's state stay between runs: the next start resumes.
+  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
+  the Postgres protocol for BI tools and your app. It only reads the database (SELECT, and a table's change log when
+  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.
 
-  With --replication it reads the database's change log instead: it needs wal_level = logical and a user that may
-  replicate, and makes its own publication and replication slot on the database (mason destroy, or mason start --poll,
-  drops them). The project keeps the mode until --poll; a switch keeps the copies and catches each table up by one
-  poll. --publication <name> (else PG_PUBLICATION) names a publication that is the database owner's: it is read as it
-  is, verified to carry every added table and column, and never created, altered or dropped — Mason makes only its
-  slot. A read replica needs one (it takes no CREATE PUBLICATION). The name is kept with the project, so the next
-  mason start --replication reads it again.
+  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
+  from the database's change log, as they are made. Each poll scans its table whole
+  on your database, and the next waits at least four times as long as that poll took, so the polls never take more
+  than a fifth of your database's time. The start says the file's default once; mason status says how each table is
+  kept current and when it was last synced. A table whose sync: changed keeps its synced data and is caught up by one poll.
+
+  A table under sync: replication needs wal_level = logical, a user that may replicate, and a primary key (a key:
+  table is polled): Mason makes one replication slot for the project and its own publication, carrying the replicated
+  tables alone, and drops them, verified gone, when no table's sync is replication any more (and at mason destroy).
+  publication: <name> at the top of the sources file (\${PG_PUBLICATION} reads it from .env) names a publication that
+  is the database owner's: it is read as it is, verified to carry every replicated table and column, and never
+  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.
 
   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
@@ -53,53 +73,56 @@ 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 start --replication read the change log, as production does
-    mason start --replication --publication app_pub   through the database owner's publication
     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)
-  --replication       read the database's changes from its change log (logical replication), as production does
-  --publication <name>  with --replication: the publication to read, the owner's, never altered (PG_PUBLICATION;
-                      default: Mason's own, mason_dev_<project>_<source>)
-  --poll              read them with SELECTs (the default; takes back --replication)
   --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)
+  --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 },
-        replication: { type: "boolean", default: false }, poll: { type: "boolean", default: false }, publication: { type: "string" },
         "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
+    // 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) });
     const f = parseCommand(DEV, argv);
     if (typeof f === "number")
         return f;
     const v = f.values;
-    if (v.replication && v.poll)
-        return failed("start", { message: "--replication or --poll, not both", code: "usage", usage: DEV.usage }, { json: v.json });
-    if (v.publication !== undefined && v.poll)
-        return failed("start", { message: "--publication goes with --replication, not --poll", code: "usage", usage: DEV.usage }, { json: v.json });
-    if (v.publication !== undefined && !/^\S+$/.test(v.publication))
-        return failed("start", { message: `--publication must name a publication, not ${JSON.stringify(v.publication)}`, code: "usage", usage: DEV.usage }, { json: v.json });
     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 });
     }
-    const port = v.port === undefined ? 4039 : Number(v.port);
+    const port = v.port === undefined ? DEFAULT_UI_PORT : Number(v.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 });
     if (!v.attach)
-        return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"], changes: v.replication ? "replication" : v.poll ? "poll" : null });
-    return dev({ port, version: version(), changes: v.replication ? "replication" : v.poll ? "poll" : null, publication: v.publication ?? null, selfSignedTls: v["self-signed-tls"] });
+        return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"] });
+    return dev({ port, version: version(), selfSignedTls: v["self-signed-tls"] });
+}
+/** The project's sources file as a person names it (`mason/sources/app.yml`), for a removed flag's answer: the one file
+ *  of the project of this folder, else the name every project's has. */
+function startSourcesTop(cwd) {
+    const t = theProject(cwd);
+    return "problem" in t ? { shown: "mason/sources/<name>.yml", sync: null, publication: null } : sourcesTop(t.project.root, t.project.folder);
 }
 export const HELP = {
     name: "help",
@@ -152,9 +175,9 @@ export const STEPS = [
     ["Learn", [{ ...HELP, run: runHelp }]],
     ["Set up", [{ ...DOCTOR, run: (argv) => doctor(argv) }, { ...INIT, run: (argv) => init(argv) }, { ...DEV, run: runDev }]],
     ["Add your tables", [{ ...TABLES, run: tables }, { ...ADD, run: add }, { ...REMOVE, run: remove }, { ...WAIT, run: wait }]],
-    ["Connect", [{ ...USER, run: user }, { ...MCP, run: mcp }]],
-    ["Run", [{ ...STATUS, run: status }, { ...UI, run: ui }, { ...SYNC, run: sync }, { ...LOGS, run: logs }, { ...STOP, run: stop }, { ...DESTROY, run: (argv) => destroy(argv) }]],
-    ["Go to production", [{ ...SERVE, run: serve }]],
+    ["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 }, { ...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);
@@ -164,6 +187,9 @@ export const COMMANDS = STEPS.flatMap(([, commands]) => commands);
  * it, then the next command for that moment — and mason help, every command. `mason help` and `mason --help` are the
  * whole list (topUsage).
  */
+/** WHAT MASON IS, in one line: the first `mason` alone and `mason --help` print, in the words its reader was told it
+ *  in ("a drop-in read replica for analytics"). */
+export const TAGLINE = "Mason: a drop-in read replica of your Postgres, for analytics — the tables you add, synced, kept current and served to psql, BI tools and your app.";
 export async function orientation(cwd, s = styleOut()) {
     const t = theProject(cwd);
     const project = "project" in t ? t.project : null;
@@ -172,12 +198,12 @@ 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 (DATABASE_URL from .env, or mason init postgres://…)"],
+        ? [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"],
             ["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"]]
             : [["mason status", "what Mason is doing: its tables, and the last day's slow and refused statements"], ["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"]];
-    return `${reportText({ headline: "Mason: your Postgres tables, copied and served to BI tools and your app.", details: rows,
+    return `${reportText({ headline: TAGLINE, details: rows,
         next: [...next, ["mason help", "every command, and the guides"]] }, s)}\n`;
 }
 /** `mason --help`: what Mason is, every command with its summary, and where each one's help is. On a terminal the steps are
@@ -204,8 +230,9 @@ export function topUsage(s = styleOut()) {
     return [
         `${s.bold("usage:")} mason <command> [options]`,
         "",
-        para("Mason: your Postgres tables, copied and served to BI tools and your app. Make your app's folder a project (mason init), " +
+        para(`${TAGLINE} Make your app's folder a project (mason init), ` +
             `add tables (mason add, before or after the start), start Mason (mason start), connect a tool (mason user add). It needs Node ${NODE_MIN} or later; mason doctor checks.`),
+        para("Try it first with nothing to install: mason init demo, then mason start and mason ui (a demo shop database, hosted by Mason itself)."),
         para(PROJECT_LINE),
         "",
         listed.map(([step, es]) => `  ${s.bold(step)}\n${block(es)}`).join("\n\n"),
@@ -214,7 +241,7 @@ export function topUsage(s = styleOut()) {
         para("A command means the project of the folder it runs in (or above it)."),
         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). Driving Mason from a coding agent: mason help agent."),
         "",
     ].join("\n");
 }