@mason-data/cli 0.9.0 → 0.10.0

package/dist/src/cli/sync.js

@@ -6,7 +6,7 @@
  * polled: its answer is where the stream is, beside the polled ones'. The run's `POST /api/sync` (src/cli/run-server.ts) answers it, through the sync's own
  * poll (`Sync.pollNow`).
  */
-import { failed, jsonText, parseCommand, reportText } from "./command.js";
+import { failed, failureCode, jsonText, parseCommand, reportText } from "./command.js";
 import { out as styleOut } from "./style.js";
 import { callRun } from "./control.js";
 import { reach } from "./state.js";
@@ -15,7 +15,7 @@ import { didYouMean } from "../lib/did-you-mean.js";
 import { syncedText, syncWords } from "../lib/table-sync.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const n = (x) => x.toLocaleString("en-US");
-export const SYNC_USAGE = `usage: mason sync <table>… [--json]
+export const SYNC_USAGE = `usage: mason sync (<table>… | --all) [--json]
 
   Brings these synced tables up to date now: it reads what changed in your database since Mason last read them —
   the rows inserted or updated, and the ones deleted — in one transaction, as a poll does (each one scans its table
@@ -27,7 +27,9 @@ export const SYNC_USAGE = `usage: mason sync <table>… [--json]
 
     mason sync orders
     mason sync orders public.events
+    mason sync --all               every table the sources file names (each one a scan of its table)
 
+  --all    every table the sources file names, instead of naming them
   --json   as data: { syncedAt, tables: [{ table, changed, deleted, rows, ms }] (the tables polled), streamed (the
            tables whose sync: is replication, not polled: [{ table, position, state, why }]), next }
 `;
@@ -36,7 +38,7 @@ export const SYNC = {
     name: "sync",
     summary: "bring these synced tables up to date now: mason sync orders (a table whose sync is off is read again only so)",
     usage: SYNC_USAGE,
-    options: { json: { type: "boolean" } },
+    options: { json: { type: "boolean" }, all: { type: "boolean" } },
     json: ["syncedAt", "tables", "streamed", "next"],
 };
 /**
@@ -67,8 +69,11 @@ export async function sync(argv) {
         return f;
     const json = f.values.json === true;
     const names = [...new Set(f.positionals)];
-    if (!names.length)
-        return failed("sync", { message: "name a table: mason sync orders (mason status lists the added ones)", code: "usage", usage: SYNC_USAGE }, { json });
+    const all = f.values.all === true;
+    if (all && names.length)
+        return failed("sync", { message: `--all syncs every added table: name tables (${names.join(" ")}) or --all, not both`, code: "usage", usage: SYNC_USAGE }, { json });
+    if (!names.length && !all)
+        return failed("sync", { message: "name a table: mason sync orders (mason status lists the added ones), or mason sync --all", code: "usage", usage: SYNC_USAGE }, { json });
     const w = await reach(SYNC, json);
     if (w === null || !("run" in w))
         return 1;
@@ -76,7 +81,11 @@ export async function sync(argv) {
     return guarded("sync", json, async () => {
         const s = await readState(run);
         const added = s.tables.filter((t) => t.added);
-        const picked = [];
+        // --all: every table the sources file names, as the run read it
+        const picked = all ? added.map((t) => t.table) : [];
+        if (all && !picked.length) {
+            return failed("sync", { message: "no table is added yet, so there is nothing to sync", code: "nothing_yet", next: [["mason tables", "the database's tables"], ["mason add <table>", "add one to the sources file"]] }, { json });
+        }
         for (const name of names) {
             const t = findTable(added, name);
             if (!("message" in t)) {
@@ -97,12 +106,12 @@ export async function sync(argv) {
         // a sync scans each table whole on the database (and waits for a copy under way): minutes, not the commands' 30 s
         const r = await callRun(run, "POST", "/api/sync", { tables: picked }, 60 * 60_000);
         if (r.status !== 200) {
-            const code = typeof r.body.code === "string" ? r.body.code : r.status === 404 ? "not_found" : "failed";
+            const code = failureCode(r.body.code, r.status === 404 ? "not_found" : "failed");
             return failed("sync", { message: `${picked.join(", ")} ${picked.length === 1 ? "was" : "were"} not synced`, code, why: String(r.body.error),
                 next: [["mason status", "each synced table"], ["mason logs", "the run's log"]] }, { json });
         }
         const b = r.body;
-        const next = [[`mason sync ${names.join(" ")}`, "sync again, whenever you need it current"], ["mason status", "how each table is kept current, and when it was last synced"]];
+        const next = [[all ? "mason sync --all" : `mason sync ${names.join(" ")}`, "sync again, whenever you need it current"], ["mason status", "how each table is kept current, and when it was last synced"]];
         if (json) {
             out(jsonText(SYNC, { syncedAt: b.at, tables: b.tables, ...(b.streamed ? { streamed: b.streamed } : {}) }, next));
             return 0;

package/dist/src/cli/token-hosted.js

@@ -28,9 +28,9 @@
  *   createdAt, expiresAt, lastUsedAt   rows, --json                         `isServiceTime` (lastUsedAt or null)
  *   more                               a tip, --json                        a boolean
  */
-import { endText, failed, jsonText, parseCommand, reportText, serviceStyle, strict } from "./command.js";
+import { endText, failed, jsonText, listFlag, parseCommand, reportText, serviceStyle, strict } from "./command.js";
 import { call, carriesNoSecret, echoesSecret, isFailure, isServiceTime, serviceFailure, serviceOf, serviceText, unexpected } from "./hosted.js";
-import { loginOrgs, orgNamed, REPLICA_PART, replicaOf, tokenFor } from "./replica.js";
+import { loginOrgs, orgNamed, orgOf, REPLICA_PART, replicaOf, tokenFor } from "./replica.js";
 import { refusedNext } from "./replica-hosted.js";
 import { holdOutput } from "./output-gate.js";
 import { didYouMean } from "../lib/did-you-mean.js";
@@ -53,7 +53,7 @@ export const TOKEN = {
     name: "token",
     summary: "a hosted Mason service's CI tokens: make one for a replica (printed once), list them, revoke one",
     usage: `usage: mason token create --replica <org>/<name> [--scope deploy|users …] [--name <name>] [--days <n>] [--json]
-       mason token list [<org>] [--json]
+       mason token list [<org> | --org <org>] [--json]
        mason token revoke <id> [--org <org>] [--json]
 
   A CI token lets CI act on ONE replica of a hosted Mason service, for the scopes it was made with (deploy: mason
@@ -61,6 +61,19 @@ export const TOKEN = {
   an owner of the organisation makes, lists and revokes them, signed in as a person (mason login): a CI token
   makes none.
 
+    mason token create --replica acme/shop --name github-actions
+    mason token create --replica acme/shop --scope deploy --scope users --days 30 --json
+    mason token list acme
+    mason token revoke 3f1c9a2e --org acme
+
+  --replica <org>/<name>   create: the replica it acts on (else MASON_REPLICA)
+  --scope <scope,…>        create: what it may do, deploy or users; both: --scope deploy,users or the flag twice
+                           (default deploy)
+  --name <name>            create: what the list calls it, 1 to 64 characters (default ${DEFAULT_NAME})
+  --days <n>               create: the days it acts, 1 to ${MAX_DAYS} (default ${DEFAULT_DAYS})
+  --org <org>              list: the organisation, in place of the argument; revoke: the organisation it is of
+  --json                   as data: its shape is at the end
+
   create makes one and prints it ONCE: the service does not keep it, and nothing shows it again, so store it at once
   (as MASON_TOKEN in CI's secrets). It is alone on the first line printed, never broken, or, with --json, in the
   one field token.value of the document, so a setup step can pipe it straight into a secret store. Nothing else
@@ -72,27 +85,18 @@ export const TOKEN = {
 
   The login is MASON_TOKEN, else this machine's (mason login); the service is MASON_CLOUD_URL, else the default.
 
-    mason token create --replica acme/shop --name github-actions
-    mason token create --replica acme/shop --scope deploy --scope users --days 30 --json
-    mason token list acme
-    mason token revoke 3f1c9a2e --org acme
-
-  --replica <org>/<name>   create: the replica it acts on (else MASON_REPLICA)
-  --scope <scope>          create: what it may do, deploy or users; repeat it for both (default deploy)
-  --name <name>            create: what the list calls it, 1 to 64 characters (default ${DEFAULT_NAME})
-  --days <n>               create: the days it acts, 1 to ${MAX_DAYS} (default ${DEFAULT_DAYS})
-  --org <org>              revoke: the organisation it is of
-  --json                   as data: { token (create: { id, value (the token itself, this once), name,
-                           replica, scopes, createdAt, expiresAt }), tokens (list: [{ id, name, replica, scopes,
-                           madeBy, createdAt, lastUsedAt (null: never used), expiresAt }]), more (list: true when an
-                           organisation has more than the service lists), revoked (revoke: { org, id, name }), next }
-
   Exit status: 0 done; 1 not signed in, refused by the service (its words printed as they came, the code the
   CLI's own), or the service answered outside its contract; 2 a wrong command line.
+
+  The --json answer: { token (create: { id, value (the token itself, this once), name,
+    replica, scopes, createdAt, expiresAt }), tokens (list: [{ id, name, replica, scopes,
+    madeBy, createdAt, lastUsedAt (null: never used), expiresAt }]), more (list: true when an
+    organisation has more than the service lists), revokedToken (revoke: { org, id,
+    name }), revoked (revoke: the same, kept until 1.0), next }
 `,
     options: { replica: { type: "string" }, scope: { type: "string", multiple: true }, name: { type: "string" }, days: { type: "string" }, org: { type: "string" },
         json: { type: "boolean", default: false } },
-    json: ["token", "tokens", "more", "revoked", "next"],
+    json: ["token", "tokens", "more", "revokedToken", "revoked", "next"],
 };
 const outStyle = () => serviceStyle(styleOut());
 const errStyle = () => serviceStyle(styleErr());
@@ -176,10 +180,10 @@ export async function token(argv) {
     for (const k of ["replica", "scope", "name", "days"])
         if (verb !== "create" && f.values[k] !== undefined)
             return usage(`--${k} goes with mason token create`);
-    if (verb !== "revoke" && f.values.org !== undefined)
-        return usage("--org goes with mason token revoke", verb === "list" ? "name the organisation: mason token list <org>" : "create names it: --replica <org>/<name>");
+    if (verb === "create" && f.values.org !== undefined)
+        return usage("--org goes with mason token list and revoke", "create names it: --replica <org>/<name>");
     if (verb === "list") {
-        const org = arg === undefined ? null : orgNamed(arg, TOKEN.usage);
+        const org = orgOf(typeof f.values.org === "string" ? f.values.org : undefined, arg, TOKEN.usage);
         if (org !== null && isFailure(org))
             return fail(org, json);
         return list(org, json);
@@ -197,7 +201,9 @@ export async function token(argv) {
         return usage("mason token create names the replica it acts on", "--replica <org>/<name>, or MASON_REPLICA=<org>/<name>");
     if (isFailure(r))
         return fail(r, json);
-    const asked = Array.isArray(f.values.scope) ? f.values.scope.filter((x) => typeof x === "string") : [];
+    // a comma list or the flag repeated, the same (src/cli/command.ts listFlag)
+    const listed = listFlag(f.values.scope);
+    const asked = listed === undefined ? [] : listed.split(",");
     for (const s of asked)
         if (!SCOPES.includes(s))
             return usage(`--scope ${JSON.stringify(serviceText(s, 100))} is not a scope${didYouMean(s, SCOPES)}`, `a CI token's scopes are ${SCOPES.join(" and ")}`);
@@ -329,7 +335,7 @@ async function revoke(id, named, json) {
     const revoked = { org, id, name: serviceText(j.revoked.name, 64, secrets) };
     const next = [listStep(org)];
     if (json) {
-        out(jsonText(TOKEN, { revoked }, next));
+        out(jsonText(TOKEN, { revokedToken: revoked, revoked }, next));
         return 0;
     }
     out(reportText({ headline: `Revoked the CI token ${id} of ${org}: it acts no more`, details: [["name", revoked.name]], next }, outStyle()));

package/dist/src/cli/tunnel.js

@@ -133,7 +133,7 @@ export function startTunnel(plan, o) {
         const timer = setTimeout(() => {
             stop();
             const said = lastLines(output, plan.token);
-            settle({ message: `the tunnel gave no address in ${Math.round(o.timeoutMs / 1000)} s`, code: "failed", why: said === "" ? `${plan.bin} printed nothing` : `${plan.bin} printed: ${said}`,
+            settle({ message: `the tunnel gave no address in ${Math.round(o.timeoutMs / 1000)} s`, code: "timeout", why: said === "" ? `${plan.bin} printed nothing` : `${plan.bin} printed: ${said}`,
                 fix: `its output is the service's, and may have changed: this Mason cannot read it${plan.via === "pinggy" ? ", and --via bore is another tunnel" : ""}. Nothing was left open` });
         }, o.timeoutMs);
         const read = (b) => {

package/dist/src/cli/ui-hosted.js

@@ -0,0 +1,163 @@
+/**
+ * `mason ui --replica <org>/<name>` — A HOSTED REPLICA'S WEB PAGE, IN THE BROWSER OF THE ORGANISATION'S OWNER
+ * (docs/HOSTED-API.md "A replica's page"). ONE request, `POST /v1/replicas/{org}/{name}/ui`, whose answer is a one-use,
+ * short-lived address of the replica's page (on the service's origin, or on https at a subdomain of its host), read-only
+ * (the service refuses every write through it: changes go by `mason user … --replica`, which it audits); the CLI opens it as `mason ui` opens a run's
+ * page and `mason login` its sign-in page (`openBrowser`), or prints it (`--no-open`, `--json`, a browser that would not
+ * start). Who may ask (the owner's login alone), and the audit row of each page opened, are the service's: the CLI cannot
+ * write that row and never says it did.
+ *
+ * Every value of the answer, and how it is held (src/cli/hosted.ts's header: a service's value is data, never structure):
+ *
+ *   value                      where it is printed                     what holds it
+ *   every string, keys too     nowhere until held                      `carriesNoSecret`: an answer carrying a secret is refused whole
+ *   url                        opened; printed where it was not        `pageOrigin`, `pageUrl`: the service's origin or https at a
+ *                                                                      subdomain of its host, its port; no user, at most 2048, carries
+ *                              opened, and in --json                   no secret as printed; then `OPENABLE`: letters, digits and
+ *                                                                      `. : [ ] - _ ~ / ? = +` alone, so no shell reads it
+ *   expiresAt                  a row, --json                           `isServiceTime`
+ *   a failure's words          stderr's failure, --json error          `serviceFailure`: one line each, masked; the code by the status
+ *   a failure's next           nowhere: never read                     the step is `failureNext`'s, by the status
+ *   Retry-After                a next step's words                     `retryAfterOf`: 1 to 3600 seconds
+ *
+ * THE ADDRESS IS PRINTED ONLY WHERE THE PERSON NEEDS IT: opened in the browser, it is not printed (the browser used it,
+ * and it opens the page once); printed when it was not opened, and in `--json` for the agent that passes it on. It is
+ * never logged: this command writes no log. A 409 or a 503 (a replica not ready, its machine not connected) is said
+ * with the next step, never waited on: the person runs the command again.
+ */
+import { failed, jsonText, reportText, serviceStyle } from "./command.js";
+import { environmentToken, TOKEN_ENV } from "./credentials.js";
+import { call, carriesNoSecret, codeOfStatus, isFailure, isServiceTime, pageUrl, serviceFailure, serviceOf, unexpected } from "./hosted.js";
+import { holdOutput } from "./output-gate.js";
+import { replicaText, tokenFor } from "./replica.js";
+import { err as styleErr, out as styleOut } from "./style.js";
+import { OPENABLE, openBrowser, UI } from "./ui.js";
+const out = (m) => { process.stdout.write(`${m}\n`); };
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** The request: the replica's page, asked of the service. Both parts are `REPLICA_PART`'s, safe in a path as they are. */
+export const pagePath = (r) => `/v1/replicas/${r.org}/${r.name}/ui`;
+const STEP = "a replica's page was asked for";
+/**
+ * THE ORIGIN A REPLICA'S PAGE MAY BE ON: the service's own, or an `https:` origin whose host is a subdomain of the
+ * service's host, on the service's port (a page of its own origin keeps the service's session cookie and its routes
+ * apart from Mason's page: `r-abc.ui.app.example` under `app.example`). A subdomain by its labels, never a suffix of the
+ * text (`evilapp.example` is not under `app.example`), and none under an IP address. The origin the page is held to,
+ * or null when `v` is on none of them (or is no URL).
+ */
+export function pageOrigin(service, v) {
+    if (typeof v !== "string")
+        return null;
+    let u, base;
+    try {
+        u = new URL(v);
+        base = new URL(service.base);
+    }
+    catch {
+        return null;
+    }
+    if (u.origin === service.base)
+        return service;
+    const ip = /^[\d.]+$/.test(base.hostname) || base.hostname.startsWith("[");
+    if (u.protocol !== "https:" || u.port !== base.port || ip || !u.hostname.endsWith(`.${base.hostname}`))
+        return null;
+    return { base: u.origin };
+}
+/**
+ * `POST …/ui`'s answer (200), held: every string of it, each key included, put to the exact test first
+ * (`carriesNoSecret`), then the address on an origin it may be on (`pageOrigin`; refused naming the origin when it is
+ * not), held there by `pageUrl` (no user or password, at most 2048, no secret as printed), of the characters a browser
+ * is handed (`OPENABLE`), and the time to its grammar. The page, or a Failure said by the status alone (or naming the
+ * other origin).
+ */
+export function heldPage(service, a, secrets) {
+    const j = a.json;
+    if (!obj(j) || !carriesNoSecret(j, secrets))
+        return unexpected(service, a, STEP);
+    const origin = pageOrigin(service, j.url);
+    // on an origin it may be on, `pageUrl` holds it as on the service's own; elsewhere, `pageUrl` says the origin safely
+    const page = pageUrl(origin ?? service, j.url, secrets);
+    if (page !== null && "elsewhere" in page) {
+        return { message: `${service.base} named a replica's page on another address: ${page.elsewhere}`, code: "refused",
+            why: `a replica's page is opened only on the service's own address, ${service.base}, or on https at a subdomain of its host: anything else would send you to an address nobody chose`,
+            fix: "check MASON_CLOUD_URL names the service you mean; if it does, the service is answering outside its documented API" };
+    }
+    if (page === null || !OPENABLE.test(page.href) || !isServiceTime(j.expiresAt))
+        return unexpected(service, a, STEP);
+    return { url: page.href, expiresAt: j.expiresAt };
+}
+/**
+ * WHAT TO RUN AFTER THE SERVICE REFUSED: the CLI's own, by the status (never the service's `next`). A 401 or 403 is a
+ * login that may not (only the organisation's owner opens a replica's page; a CI token never does), a 404 a replica the
+ * login does not see, a 409 or 503 a replica not ready or not connected: its state, and the command again when the
+ * service's `Retry-After` says.
+ */
+export function failureNext(status, r, retryAfter, env = process.env) {
+    const named = replicaText(r);
+    if (status === 401 || status === 403) {
+        return environmentToken(env) !== null
+            ? [[`env -u ${TOKEN_ENV} mason ui --replica ${named}`, `with your own login, not ${TOKEN_ENV}: a CI token never opens a page`]]
+            : [["mason login", "sign in as the organisation's owner: only an owner opens a replica's page"]];
+    }
+    if (status === 404)
+        return [[`mason replica list ${r.org}`, "the replicas this login sees"]];
+    if (status === 409 || status === 503) {
+        return [[`mason replica status ${named}`, "whether it is ready"],
+            [`mason ui --replica ${named}`, retryAfter !== null ? `again in ${retryAfter} s, as the service asks` : "again in a moment"]];
+    }
+    return [[`mason ui --replica ${named}`, "again in a moment"]];
+}
+/** A refusal said as the service worded it; a 409 or 503 it sent without its words is said in the CLI's. */
+export function refusalOf(service, a, r, secrets, env = process.env) {
+    const next = failureNext(a.status, r, a.retryAfter, env);
+    const notReady = a.status === 409 || a.status === 503;
+    const again = a.retryAfter !== null ? `try again in ${a.retryAfter} s` : "try again in a moment";
+    const said = serviceFailure(a, secrets, () => next);
+    if (said !== null)
+        return notReady && said.fix === undefined ? { ...said, fix: `${again}; mason replica status ${replicaText(r)} says whether it is ready` } : said;
+    if (notReady) {
+        return { message: `the replica ${replicaText(r)} is not ready to open its page (HTTP ${a.status})`, code: codeOfStatus(a.status),
+            why: a.status === 409 ? "it is not ready yet: being made, deleted, or failed" : "its machine is not connected to the service now",
+            fix: `${again}; mason replica status ${replicaText(r)} says whether it is ready`, next };
+    }
+    return unexpected(service, a, STEP);
+}
+/** `mason ui --replica <org>/<name>`: the page asked for, then opened, printed, or said as --json. */
+export async function hostedUi(r, o) {
+    const fail = (f) => failed("ui", f, { json: o.json, style: serviceStyle(styleErr()) });
+    const service = serviceOf();
+    if (isFailure(service))
+        return fail(service);
+    const token = tokenFor(service, { asked: "a replica's page is asked for", again: `mason ui --replica ${replicaText(r)}` });
+    if (isFailure(token))
+        return fail(token);
+    // from here every byte written is put to the exact test against the token (src/cli/output-gate.ts)
+    holdOutput({ command: "ui", json: o.json, secrets: [token] });
+    const secrets = [token];
+    const a = await call(service, "POST", pagePath(r), { token });
+    if (isFailure(a))
+        return fail(a);
+    if (a.status !== 200)
+        return fail(refusalOf(service, a, r, secrets));
+    const page = heldPage(service, a, secrets);
+    if (isFailure(page))
+        return fail(page);
+    const named = replicaText(r);
+    const next = [[`mason replica status ${named}`, "the replica's state, in this terminal"], [`mason ui --replica ${named}`, "a new address: each opens the page once"]];
+    if (o.json) {
+        out(jsonText(UI, { url: page.url, replica: named, expiresAt: page.expiresAt }, next));
+        return 0;
+    }
+    const couldNot = o.open ? await openBrowser(page.url) : null;
+    const opened = o.open && couldNot === null;
+    out(reportText({
+        headline: opened ? `The page of the replica ${named}, opened in your browser` : `The page of the replica ${named}`,
+        // opened, the address is not printed: the browser used it, and it opens the page once
+        details: [...(opened ? [] : [["url", page.url]]), ["replica", named], ["expires", page.expiresAt]],
+        tips: [
+            ...(couldNot !== null ? [`Could not open a browser (${couldNot}): open the URL yourself.`] : []),
+            opened ? "The address opens the page once: for another tab, run the command again." : "The URL opens the page once, for you alone, until it expires: paste it nowhere else.",
+        ],
+        next,
+    }, serviceStyle(styleOut())));
+    return 0;
+}

package/dist/src/cli/ui-ssh.js

@@ -32,7 +32,7 @@ import * as net from "node:net";
 import { fileURLToPath } from "node:url";
 import { Worker } from "node:worker_threads";
 import { runnable } from "../lib/runnable.js";
-import { errorJson, nextJson } from "./command.js";
+import { errorJson, failureCode, nextJson } from "./command.js";
 import { holdRun, RunUnreachable } from "./control.js";
 import { whereIs } from "./state.js";
 import { lastLines } from "./tunnel.js";
@@ -335,7 +335,7 @@ function refusal(h, target) {
         : stopped ? `start mason serve on ${target}: its service or container` : h.error.fix;
     // these two say mason init and mason start, words for a person at that machine: run here they would do the wrong thing
     const next = lost || stopped ? [] : h.next.map((n) => n.what === undefined ? [n.command] : [n.command, n.what]);
-    return { message: `on ${target}: ${h.error.message}`, code: h.error.code, ...(h.error.why ? { why: h.error.why } : {}), ...(fix ? { fix } : {}), next };
+    return { message: `on ${target}: ${h.error.message}`, code: failureCode(h.error.code, "failed"), ...(h.error.why ? { why: h.error.why } : {}), ...(fix ? { fix } : {}), next };
 }
 /** Starts ssh and the bridge, with a free loopback port before them: the tunnel, or why not. */
 export function openSshTunnel(o) {
@@ -381,7 +381,7 @@ export function openSshTunnel(o) {
             };
             const timer = setTimeout(() => {
                 const last = lastLines(said, null);
-                fail({ message: `no answer from ${o.target} in ${Math.round(o.timeoutMs / 1000)} s`, code: "failed", ...(last === "" ? {} : { why: `ssh printed: ${last}` }),
+                fail({ message: `no answer from ${o.target} in ${Math.round(o.timeoutMs / 1000)} s`, code: "timeout", ...(last === "" ? {} : { why: `ssh printed: ${last}` }),
                     fix: `run ssh ${o.target} on its own to see where it waits; --timeout gives it longer`, next: [[`ssh ${o.target} true`, "whether ssh reaches it on its own"]] });
             }, o.timeoutMs);
             // Ctrl-C before an answer: ssh goes too, a process signalled alone included

package/dist/src/cli/ui.js

@@ -2,7 +2,8 @@
  * `mason ui` — THE WEB PAGE OF THE RUNNING MASON, IN THE BROWSER (src/web/, docs/WEB-UI.md): the Overview (what `mason
  * status` says), the Tables (`mason tables`, `add`, `remove`, `sync`), the Users (`mason user`) and Observability (`mason
  * logs`, `mason usage`), refreshed while the tab is seen. It prints the page's URL WITH the run's token (src/cli/security.ts: the first request trades it for an HttpOnly cookie and is redirected to a URL without
- * it) and opens the browser. The reader is the person at this terminal, whom `mason user add` already shows a
+ * it) and opens the browser when its stdout is a terminal (as `mason login` does: a pipe, a file or an agent's shell has
+ * no one at a browser, so it gets the address alone). The reader is the person at this terminal, whom `mason user add` already shows a
  * password once; the token is never written anywhere else — not in `mason start`'s output (its log is a file), not in
  * `mason status`, which prints the URL without it.
  *
@@ -12,6 +13,9 @@
  * `--ssh <user@server>` (src/cli/ui-ssh.ts, docs/WEB-UI.md "On a server") opens a server's page from this machine, through
  * the machine's own ssh, and stays in the foreground until Ctrl-C, as `mason share` does; it needs no project here. Its
  * URL carries a ticket for one use, never the run's token, which stays on the server. `--bridge` is what it runs there.
+ *
+ * `--replica <org>/<name>` (else `MASON_REPLICA`; src/cli/ui-hosted.ts, docs/HOSTED-API.md "A replica's page") opens a
+ * replica's page on a hosted Mason service: one request, whose one-use address is opened as this command opens a run's.
  */
 import { spawn } from "node:child_process";
 import { failed, jsonText, parseCommand, reportText } from "./command.js";
@@ -19,6 +23,9 @@ import { reach } from "./state.js";
 import { bridge, openSshTunnel, targetProblem } from "./ui-ssh.js";
 import { version } from "./version.js";
 import { RunUnreachable } from "./control.js";
+import { parseDuration } from "../lib/table-sync.js";
+import { replicaOf } from "./replica.js";
+import { hostedUi } from "./ui-hosted.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const say = (m) => { process.stderr.write(`${m}\n`); };
 const DEFAULT_TIMEOUT_S = 60;
@@ -27,7 +34,8 @@ export const UI = {
     name: "ui",
     summary: "the status, tables, users and statements, in your browser",
     usage: `usage: mason ui [--no-open] [--json]
-       mason ui --ssh <user@server> [--mason <command>] [--timeout <seconds>] [--no-open] [--json]
+       mason ui --ssh <user@server> [--mason <command>] [--timeout <duration>] [--no-open] [--json]
+       mason ui --replica <org>/<name> [--no-open] [--json]
 
   Opens the running Mason's web page in your browser, refreshed while the tab is open: the Overview (what mason status
   says: whether the synced data is ready, the database, the sync, the statements and the recent errors); the Tables (add,
@@ -35,38 +43,51 @@ export const UI = {
   the URL to paste, or remove one); and Observability: the statements running and that ran (mason logs --requests,
   cancel one), usage over time (mason usage), and the sync's events (mason logs --events).
 
-  The URL carries this run's token: the page trades it for a cookie at once and drops it from the address
-  bar. It is printed for you alone, like a user's password: paste it nowhere else. Every mason start makes a new
-  token, so after a restart run mason ui again.
-
-  --ssh opens a server's page (mason serve's) from this machine, with nothing public: it runs your ssh, so your
-  ~/.ssh/config, keys and SSO apply, starts mason there, and forwards a free local port to the page, which listens on the
-  server's loopback alone. It stays in the foreground: Ctrl-C closes the tunnel. It needs no project here. Its URL
-  carries a ticket for one use, never the run's token, which stays on the server. The server's Mason must be this
-  version or close to it, and must be a command ssh can run: --mason says how, for a container or a folder.
-
     mason ui
     mason ui --no-open        print the URL, open no browser
     mason ui --json
     mason ui --ssh deploy@mason.example.com
     mason ui --ssh deploy@mason.example.com --mason "docker exec -i mason-mason-1 mason"
     mason ui --ssh deploy@mason.example.com --mason "cd /var/lib/mason && mason" --timeout 120 --no-open
+    mason ui --replica acme/shop     a replica's page on a hosted Mason service
     mason ui --bridge --local-port 51000      what --ssh runs on the server; its stdout is a stream, not for reading
 
-  --no-open            print the URL only
+  --no-open            print the URL only (as when its output is not a terminal: a browser opens only for one)
   --ssh <target>       the server, as you give it to ssh: user@server, or a Host of your ssh config
   --mason <command>    how to run mason on the server (default mason); a shell's text, kept to ssh's command line
-  --timeout <s>        how long ssh and the server have to answer (default ${DEFAULT_TIMEOUT_S}): a passphrase or a touch counts
+  --timeout <duration> how long ssh and the server have to answer (default ${DEFAULT_TIMEOUT_S}s; a bare number is seconds;
+                       2m): a passphrase or a touch counts; past it, exit 124
   --bridge             the server's end of --ssh, on stdin and stdout
   --local-port <n>     the port the browser names, for --bridge: the laptop's
-  --json               as data: { url (with this run's token; with --ssh a ticket for one use; null when Ctrl-C came
-                       before the server answered, as port is, exit 0), port, server, project,
-                       version (with --ssh: the server's Mason, for what its answer may lack) }, next; it never opens a
-                       browser. With --ssh it then holds the tunnel: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
+  --replica <org>/<name> a replica on a hosted Mason service, as the service lists it
+  --json               as data: its shape is at the end
+
+  The URL carries this run's token: the page trades it for a cookie at once and drops it from the address
+  bar. It is printed for you alone, like a user's password: paste it nowhere else. Every mason start makes a new
+  token, so after a restart run mason ui again.
+
+  --ssh opens a server's page (mason serve's) from this machine, with nothing public: it runs your ssh, so your
+  ~/.ssh/config, keys and SSO apply, starts mason there, and forwards a free local port to the page, which listens on the
+  server's loopback alone. It stays in the foreground: Ctrl-C closes the tunnel. It needs no project here. Its URL
+  carries a ticket for one use, never the run's token, which stays on the server. The server's Mason must be this
+  version or close to it, and must be a command ssh can run: --mason says how, for a container or a folder.
+
+  --replica opens the page of a replica on a hosted Mason service (else MASON_REPLICA, unless --ssh or --bridge names
+  the target), for the organisation's owner alone: the service answers an address that opens it once, for a few
+  minutes. The page is read-only: the service refuses changes through it, so add or remove users with mason user …
+  --replica. It needs no project here, and goes with --no-open and --json alone. Opened in your browser, the address is
+  not printed: run it again for another tab. A replica not ready yet is said, with when to try again.
+
+  The --json answer: { url (with this run's token; with --ssh a ticket for one use; null when Ctrl-C came
+    before the server answered, as port is, exit 0; with --replica the one-use address), port, server,
+    project, version (with --ssh: the server's Mason, for what its answer may lack), replica
+    (with --replica: "<org>/<name>"), expiresAt (with --replica: until when the address opens it)
+    }, next; it never opens a
+    browser. With --ssh it then holds the tunnel: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
 `,
     options: { "no-open": { type: "boolean", default: false }, json: { type: "boolean", default: false }, ssh: { type: "string" }, mason: { type: "string" },
-        timeout: { type: "string" }, bridge: { type: "boolean", default: false }, "local-port": { type: "string" } },
-    json: ["url", "port", "server", "project", "version", "next"],
+        timeout: { type: "string" }, bridge: { type: "boolean", default: false }, "local-port": { type: "string" }, replica: { type: "string" } },
+    json: ["url", "port", "server", "project", "version", "replica", "expiresAt", "next"],
 };
 const NEXT = [["mason status", "the same, in this terminal"], ["mason user list", "the users"]];
 /** The command that opens a URL in the person's browser, by platform (macOS `open`, Windows `start`, else `xdg-open`). */
@@ -78,6 +99,9 @@ export function openCommand(platform, url) {
         return ["cmd", ["/c", "start", "", url]];
     return ["xdg-open", [url]];
 }
+/** An address Mason hands the browser by itself (a sign-in page, a replica's page): a plain https (or this machine's
+ *  http) URL, and none of the characters a shell or `cmd /c start` reads (the service's URL is not ours). */
+export const OPENABLE = /^https?:\/\/[A-Za-z0-9.:[\]-]+(?:\/[A-Za-z0-9._~/?=+-]*)?$/;
 /** Open `url` in the browser: null once the opener started, else why it could not (the URL is printed either way). */
 export function openBrowser(url) {
     const [command, args] = openCommand(process.platform, url);
@@ -87,6 +111,9 @@ export function openBrowser(url) {
         child.once("spawn", () => { child.unref(); resolve(null); });
     });
 }
+/** Whether to open a browser: asked for (no --no-open) and stdout a terminal, a person in front of it (never a pipe,
+ *  a file or a coding agent's shell, which get the address alone). */
+const opens = (noOpen) => !noOpen && process.stdout.isTTY === true;
 /** Whether the run serves the page: its `GET /` answered, with the token the commands send. */
 async function servesPage(run) {
     let res;
@@ -155,6 +182,12 @@ export async function ui(argv) {
     const wrong = (message) => failed("ui", { message, code: "usage", usage: UI.usage }, { json });
     if (f.positionals.length)
         return wrong(`mason ui takes no argument: ${f.positionals.join(" ")}`);
+    if (v.replica !== undefined) {
+        const beside = [["--ssh", v.ssh !== undefined], ["--bridge", v.bridge], ["--mason", v.mason !== undefined], ["--timeout", v.timeout !== undefined],
+            ["--local-port", v["local-port"] !== undefined]].filter(([, given]) => given).map(([name]) => name);
+        if (beside.length)
+            return wrong(`--replica opens a hosted replica's page: it goes with --no-open and --json alone, not ${beside.join(", ")}`);
+    }
     if (v.bridge) {
         if (v.ssh !== undefined || v.mason !== undefined || v.timeout !== undefined || json)
             return wrong("--bridge is mason ui --ssh's own end on the server: it goes with --local-port alone");
@@ -173,11 +206,18 @@ export async function ui(argv) {
             return wrong(`--ssh: ${problem}`);
         if (v.mason !== undefined && (v.mason.trim() === "" || /[\r\n]/.test(v.mason)))
             return wrong("--mason is one line of shell that runs mason on the server");
-        const seconds = v.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(v.timeout);
-        if (!Number.isFinite(seconds) || seconds <= 0)
-            return wrong(`--timeout is a number of seconds, not ${JSON.stringify(v.timeout)}`);
-        return overSsh(v.ssh, v.mason ?? "mason", seconds * 1000, !v["no-open"], json);
+        const read = parseDuration(v.timeout ?? String(DEFAULT_TIMEOUT_S));
+        if ("problem" in read)
+            return wrong(`--timeout ${read.problem}`);
+        const seconds = read.seconds;
+        return overSsh(v.ssh, v.mason ?? "mason", seconds * 1000, opens(v["no-open"]), json);
     }
+    // a replica on a hosted service (--replica, else MASON_REPLICA): --ssh and --bridge name their own target, above
+    const replica = replicaOf(v.replica, UI.usage);
+    if (replica !== null && "message" in replica)
+        return failed("ui", replica, { json });
+    if (replica !== null)
+        return hostedUi(replica, { open: opens(v["no-open"]), json });
     const w = await reach(UI, json);
     if (w === null || w.state !== "up")
         return 1;
@@ -199,8 +239,9 @@ export async function ui(argv) {
         out(jsonText(UI, { url, port }, NEXT));
         return 0;
     }
-    const couldNot = f.values["no-open"] === true ? null : await openBrowser(url);
-    const opened = f.values["no-open"] !== true && couldNot === null;
+    const open = opens(v["no-open"]);
+    const couldNot = open ? await openBrowser(url) : null;
+    const opened = open && couldNot === null;
     out(reportText({
         headline: opened ? `Mason's web page, opened in your browser` : `Mason's web page`,
         details: [["url", url], ["project", run.name]],