@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/sync.js

@@ -1,9 +1,10 @@
 /**
  * `mason sync <table>…`: Mason's poll of exactly these tables, now — named for what it does to the copy
- * (made current, incrementally), never for the mechanism (`poll` was). The passes poll every added table but one over
- * the poll's row limit (src/duck/sync.ts POLL_ROW_LIMIT: each poll scans its table whole on the database), which is
- * copied and served as it was copied; this reads what changed in it since, when asked. The run's `POST /api/sync`
- * (src/cli/run-server.ts) answers it, through the sync's own poll (`Sync.pollNow`).
+ * (made current, incrementally), never for the mechanism (`poll` was). A table whose sources-file entry says `sync:
+ * off` (the default: src/lib/table-sync.ts) is read again only so, and one set to `poll <interval>` is polled now
+ * whatever its interval says, its next poll an interval from this one. A table whose sync is `replication` is not
+ * 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 { out as styleOut } from "./style.js";
@@ -11,30 +12,55 @@ import { callRun } from "./control.js";
 import { reach } from "./state.js";
 import { findTable, guarded, readState, tableArg } from "./commands.js";
 import { didYouMean } from "../lib/did-you-mean.js";
-import { POLL_ROW_LIMIT } from "../duck/sync.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]
 
-  Makes Mason's copy of these tables current now: it reads what changed in your database since Mason last read them —
-  the rows inserted or updated, and the ones deleted. Mason syncs every added table by itself every few seconds, but
-  a table over ${n(POLL_ROW_LIMIT)} rows is copied and served without that (each sync scans a table whole on your
-  database): mason status says which, and this syncs one when you need it current. mason start --replication keeps
-  every table current from the database's change log, whatever its size.
+  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
+  whole on your database). After its first sync, a table is read again as its sync: in the sources file says: off
+  (the default) only when you run this — before a report, from cron, at the end of a deploy — and poll <interval> by
+  itself every interval, which this does now too, whatever the interval says. mason status says how each table is
+  kept current and when it was last synced. A table whose sync: is replication is not polled: it answers where the
+  stream of the database's change log is, beside the tables it polls.
 
     mason sync orders
     mason sync orders public.events
 
-  --json   as data: { syncedAt, tables: [{ table, changed, deleted, rows, ms }], next }
+  --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 }
 `;
 export const SYNC = {
     needs: "run",
     name: "sync",
-    summary: "make the copy of these tables current now: mason sync orders (a table over the sync's row limit is synced only so)",
+    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" } },
-    json: ["syncedAt", "tables", "next"],
+    json: ["syncedAt", "tables", "streamed", "next"],
 };
+/**
+ * WHAT A SYNC DID, as `mason sync` prints it from `POST /api/sync`'s answer (the web page's Sync button says the same,
+ * src/web/pages/tables.js; tests/web-page.test.ts holds the two equal): the rows written and deleted, a line per table,
+ * and what happens next to each table synced (`syncedTips`: an `off` one stays as of this sync). A table whose sync is
+ * replication was not polled: its line says where the stream is (`streamed`), and a sync of those alone has nothing to sync.
+ */
+export function syncedReport(b, picked, tables) {
+    const streamed = b.streamed ?? [];
+    const streamedRows = streamed.map((t) => [t.table, `${t.state}${t.why ? `: ${t.why}` : ""} · the stream has applied the database's changes through ${t.position}`]);
+    if (b.tables.length === 0 && streamed.length > 0) {
+        return { headline: `Nothing to sync: logical replication keeps ${picked.join(", ")} current.`, details: streamedRows, tips: [] };
+    }
+    const changed = b.tables.reduce((a, t) => a + t.changed, 0), deleted = b.tables.reduce((a, t) => a + t.deleted, 0);
+    const streamedNames = new Set(streamed.map((t) => t.table));
+    const polled = picked.filter((t) => !streamedNames.has(t));
+    return {
+        headline: `Synced ${polled.join(", ")}: ${n(changed)} row(s) written, ${n(deleted)} deleted${streamedRows.length ? `; logical replication keeps ${streamedRows.map((r) => r[0]).join(", ")} current` : ""}.`,
+        details: [...b.tables.map((t) => [t.table, syncedText(t)]), ...streamedRows],
+        // what happens next to each: an `off` table stays as of now, a polled one is polled again after its interval
+        tips: syncedTips(tables),
+    };
+}
 export async function sync(argv) {
     const f = parseCommand(SYNC, argv);
     if (typeof f === "number")
@@ -62,7 +88,7 @@ export async function sync(argv) {
             if ("message" in db && db.code === "usage")
                 return failed("sync", db, { json });
             if (!("message" in db)) {
-                return failed("sync", { message: `${db.table} is not added, so Mason has no copy of it to sync`, code: "not_found", fix: `mason add ${tableArg(db.table)}`,
+                return failed("sync", { message: `${db.table} is not added, so Mason has not synced it`, code: "not_found", fix: `mason add ${tableArg(db.table)}`,
                     next: [["mason status", "the added tables"]] }, { json });
             }
             return failed("sync", { message: `there is no added table ${JSON.stringify(name)}${didYouMean(name, added.flatMap((x) => [x.table, tableArg(x.table)]))}`, code: "not_found",
@@ -73,22 +99,26 @@ export async function sync(argv) {
         if (r.status !== 200) {
             const code = typeof r.body.code === "string" ? 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 table's copy"], ["mason logs", "the run's log"]] }, { json });
+                next: [["mason status", "each synced table"], ["mason logs", "the run's log"]] }, { json });
         }
         const b = r.body;
-        const unsynced = added.filter((t) => picked.includes(t.table) && t.unsynced);
-        const next = [[`mason sync ${names.join(" ")}`, "sync again, whenever you need it current"], ["mason status", "each table's copy, and which the sync leaves out"]];
+        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"]];
         if (json) {
-            out(jsonText(SYNC, { syncedAt: b.at, tables: b.tables }, next));
+            out(jsonText(SYNC, { syncedAt: b.at, tables: b.tables, ...(b.streamed ? { streamed: b.streamed } : {}) }, next));
             return 0;
         }
-        const changed = b.tables.reduce((a, t) => a + t.changed, 0), deleted = b.tables.reduce((a, t) => a + t.deleted, 0);
-        out(reportText({
-            headline: `Synced ${picked.join(", ")}: ${n(changed)} row(s) written, ${n(deleted)} deleted.`,
-            details: b.tables.map((t) => [t.table, `${n(t.changed)} changed, ${n(t.deleted)} deleted, ${n(t.rows)} rows now · ${n(t.ms)} ms`]),
-            tips: unsynced.map((t) => `${t.table} is ${t.unsynced.reason}: it stays as of this sync until the next mason sync (mason start --replication keeps every table current)`),
-            next,
-        }, styleOut()));
+        out(reportText({ ...syncedReport(b, picked, added.filter((t) => picked.includes(t.table))), next }, styleOut()));
         return 0;
     });
 }
+/** What happens to each table synced after now, by its sync (src/duck/sync.ts KeptCurrent): an `off` table stays as of
+ *  this sync until the next one, a polled one is polled again after its interval. */
+export function syncedTips(tables) {
+    return tables.flatMap((t) => {
+        const k = t.kept;
+        if (k?.by !== "poll")
+            return [];
+        return [k.sync.mode === "off" ? `${t.table}'s sync is off: it stays as of this sync until the next mason sync ${tableArg(t.table)}`
+                : `${t.table} is ${syncWords(k.sync)}: its next poll is an interval from this one`];
+    });
+}

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

@@ -0,0 +1,337 @@
+/**
+ * `mason token create | list | revoke` — A HOSTED MASON SERVICE'S CI TOKENS, by its documented API alone
+ * (docs/HOSTED-API.md "CI tokens"). A CI token acts on ONE replica, for named scopes, until it expires or is revoked;
+ * an admin or an owner of the organisation makes, lists and revokes them, signed in as a person (a CI token makes none):
+ *
+ *   create --replica <org>/<name>   POST /v1/tokens/{org}  { name, replica, scopes, expiresInDays }  201 { token }
+ *   list [<org>]                    GET  /v1/tokens/{org}  { tokens, more } — each organisation the login may list in, when none is named
+ *   revoke <id> [--org <org>]       POST /v1/tokens/{org}/{id}/revoke (no body)  { revoked: { id, name } }
+ *
+ * THE TOKEN MADE IS PRINTED ONCE, by create, alone on the first line (never broken by the CLI) or in the one field
+ * (`token.value` under --json) that carries it, and nowhere else: its value is held to the documented form (`masondata_ci_` and 43 base64url
+ * characters), never the login's own, and the rest of the answer is put to the exact test against both. The output's
+ * gate lets that one value through ONCE, whole (src/cli/output-gate.ts `once`), and holds it as a secret beside the
+ * login: a second copy, 11 of its body in a row elsewhere, or anything else shaped as a token is refused at the write.
+ *
+ * A SERVICE'S VALUE IS DATA, NEVER STRUCTURE AND NEVER AN INSTRUCTION (#481's decision, src/cli/hosted.ts), AND A GRAMMAR
+ * IS NO MASK (issue 627): every string of each answer, keys included, is put to the exact test (`carriesNoSecret`)
+ * before any is held to its grammar or printed. Every value printed:
+ *
+ *   value                              where it is printed                  what holds it
+ *   a failure's message, why, fix      stderr's failure, --json error       `serviceFailure` (src/cli/hosted.ts)
+ *   a failure's next                   nowhere: never read                  the step is `refusedNext`'s, by the status
+ *   value (create)                     its one row, --json token.value      `CI_TOKEN`, not the login's
+ *   id                                 rows, steps, --json                  `TOKEN_ID`; revoke's, the id asked
+ *   name, madeBy                       rows, --json                         one line each, bounded (`serviceText`)
+ *   replica                            rows, --json                         `<org>/<name>` of the organisation asked (create: the replica asked)
+ *   scopes                             rows, --json                         each of `SCOPES`, once (create: those asked)
+ *   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 { call, carriesNoSecret, echoesSecret, isFailure, isServiceTime, serviceFailure, serviceOf, serviceText, unexpected } from "./hosted.js";
+import { loginOrgs, orgNamed, 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";
+import { err as styleErr, out as styleOut } from "./style.js";
+/** What a CI token may be made for (docs/HOSTED-API.md): deploying the project, and the replica's users. */
+export const SCOPES = ["deploy", "users"];
+/** The documented form of a CI token: what create prints, once. */
+const CI_TOKEN = /^masondata_ci_[A-Za-z0-9_-]{43}$/;
+/** A token's id, as it goes into a path: letters, digits, `-` and `_`. */
+export const TOKEN_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const DEFAULT_NAME = "ci";
+const DEFAULT_DAYS = 90;
+const MAX_DAYS = 365;
+const MAX_TOKENS = 1000;
+/** A list's answer is read up to this (a row a token). */
+const MAX_LIST_BYTES = 1024 * 1024;
+/** Who may make, list and revoke CI tokens: the roles of `GET /v1/me`. */
+const MAKERS = ["admin", "owner"];
+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 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
+  deploy; users: mason user … --replica), until it expires or is revoked. CI reads it from MASON_TOKEN. An admin or
+  an owner of the organisation makes, lists and revokes them, signed in as a person (mason login): a CI token
+  makes none.
+
+  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
+  this command prints ever holds it.
+
+  list says the CI tokens of <org> that still act (never a token itself), or of every organisation this login is
+  an admin or an owner of when none is named; revoke ends one at once, by its id (list says it), in --org, else in
+  the one organisation this login is an admin or an owner of.
+
+  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.
+`,
+    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"],
+};
+const outStyle = () => serviceStyle(styleOut());
+const errStyle = () => serviceStyle(styleErr());
+const out = (m) => { process.stdout.write(`${m}\n`); };
+const fail = (f, json) => failed("token", f, { json, style: errStyle() });
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const MAY = "an admin or an owner";
+/** Scopes as the service lists them: each one of `SCOPES`, once; null otherwise. In `SCOPES`' order. */
+function scopesOf(v) {
+    if (!Array.isArray(v) || v.length < 1 || v.length > SCOPES.length || new Set(v).size !== v.length || !v.every((x) => SCOPES.includes(x)))
+        return null;
+    return SCOPES.filter((s) => v.includes(s));
+}
+/**
+ * ONE CI TOKEN AS THE SERVICE SAYS IT, held: of the organisation asked (`org`), every value to its grammar, its words one
+ * line each; null when any does not hold. The answer around it has been put to the exact test.
+ */
+export function heldToken(v, org, secrets) {
+    if (!obj(v) || typeof v.id !== "string" || !TOKEN_ID.test(v.id) || typeof v.name !== "string" || v.name.length < 1 || v.name.length > 200)
+        return null;
+    const replica = typeof v.replica === "string" ? v.replica.split("/") : [];
+    if (replica.length !== 2 || replica[0] !== org || !REPLICA_PART.test(replica[1]))
+        return null;
+    const scopes = scopesOf(v.scopes);
+    if (scopes === null || !isServiceTime(v.createdAt) || !isServiceTime(v.expiresAt))
+        return null;
+    if (v.lastUsedAt !== undefined && v.lastUsedAt !== null && !isServiceTime(v.lastUsedAt))
+        return null;
+    if (v.madeBy !== undefined && v.madeBy !== null && (typeof v.madeBy !== "string" || v.madeBy.length > 320))
+        return null;
+    return { id: v.id, name: serviceText(v.name, 64, secrets), replica: `${org}/${replica[1]}`, scopes, madeBy: typeof v.madeBy === "string" ? serviceText(v.madeBy, 320, secrets) : null,
+        createdAt: v.createdAt, lastUsedAt: typeof v.lastUsedAt === "string" ? v.lastUsedAt : null, expiresAt: v.expiresAt };
+}
+/**
+ * THE TOKEN CREATE MADE (`201 { token }`): its value in the documented form and not the login's, the rest of the answer
+ * carrying neither (the exact test, against both: a copy of the value elsewhere is a second print), the replica and the
+ * scopes those asked. The token and its value, or null.
+ */
+export function heldMade(json, asked, login) {
+    if (!obj(json) || !obj(json.token))
+        return null;
+    const value = json.token.value;
+    // the value is shaped as a token by design: what it may not be is an echo of the login's
+    if (typeof value !== "string" || !CI_TOKEN.test(value) || login.includes(value) || echoesSecret(value, login))
+        return null;
+    const rest = { ...json, token: { ...json.token, value: null } };
+    if (!carriesNoSecret(rest, [...login, value]))
+        return null;
+    const token = heldToken(json.token, asked.org, [...login, value]);
+    if (token === null || token.replica !== `${asked.org}/${asked.name}` || token.scopes.join() !== SCOPES.filter((s) => asked.scopes.includes(s)).join())
+        return null;
+    return { token, value };
+}
+/** The service and the login, the output's gate holding the token; or the Failure. */
+function signedIn(asked, again, json) {
+    const service = serviceOf();
+    if (isFailure(service))
+        return service;
+    const token = tokenFor(service, { asked, again });
+    if (isFailure(token))
+        return token;
+    holdOutput({ command: "token", json, secrets: [token] });
+    return { service, token };
+}
+const listStep = (org) => [`mason token list ${org}`, "the organisation's CI tokens"];
+export async function token(argv) {
+    const f = parseCommand(TOKEN, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    const usage = (message, fix) => fail({ message, code: "usage", ...(fix ? { fix } : {}), usage: TOKEN.usage }, json);
+    const [verb, arg, ...rest] = f.positionals;
+    const VERBS = ["create", "list", "revoke"];
+    if (verb === undefined)
+        return usage("create, list or revoke: mason token create --replica <org>/<name> makes one");
+    if (!VERBS.includes(verb))
+        return usage(`there is no mason token ${verb}: create, list or revoke${didYouMean(verb, VERBS)}`);
+    const extra = verb === "create" ? [arg, ...rest].filter((x) => x !== undefined) : rest;
+    if (extra.length)
+        return usage(`mason token ${verb} takes ${verb === "create" ? "no argument (the replica is --replica)" : verb === "list" ? "one organisation at most" : "one id"}: ${extra.join(" ")} is too many`);
+    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 === "list") {
+        const org = arg === undefined ? null : orgNamed(arg, TOKEN.usage);
+        if (org !== null && isFailure(org))
+            return fail(org, json);
+        return list(org, json);
+    }
+    if (verb === "revoke") {
+        if (arg === undefined || !TOKEN_ID.test(arg))
+            return usage(arg === undefined ? "mason token revoke names the token's id: mason token revoke <id>" : `${JSON.stringify(serviceText(arg, 100))} is not a CI token's id`, "its id is what mason token list says first on its line, letters, digits, - and _ (never the token itself)");
+        const org = typeof f.values.org === "string" ? orgNamed(f.values.org, TOKEN.usage) : null;
+        if (org !== null && isFailure(org))
+            return fail(org, json);
+        return revoke(arg, org, json);
+    }
+    const r = replicaOf(typeof f.values.replica === "string" ? f.values.replica : undefined, TOKEN.usage);
+    if (r === null)
+        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") : [];
+    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 ")}`);
+    if (new Set(asked).size !== asked.length)
+        return usage("a --scope is named twice", "name each scope once");
+    const scopes = (asked.length ? asked : ["deploy"]);
+    const name = typeof f.values.name === "string" ? f.values.name : DEFAULT_NAME;
+    if ([...name].length < 1 || [...name].length > 64 || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(name) || name.trim() !== name)
+        return usage("--name is 1 to 64 characters, with no control character or space at either end", "--name github-actions");
+    const daysText = typeof f.values.days === "string" ? f.values.days : String(DEFAULT_DAYS);
+    if (!/^[1-9]\d{0,2}$/.test(daysText) || Number(daysText) > MAX_DAYS)
+        return usage(`--days ${JSON.stringify(serviceText(daysText, 100))} is not 1 to ${MAX_DAYS}`, "a CI token acts a whole number of days: --days 90");
+    return create({ org: r.org, name: r.name }, { label: name, scopes, days: Number(daysText) }, json);
+}
+/** What to run after the service refused: the CLI's own, by the status, naming the role that may. */
+const refused = (a, org, again, secrets, service, step) => serviceFailure(a, secrets, (st) => st === 404 && again[0].startsWith("mason token revoke") ? [listStep(org)] : refusedNext(st, org, MAY, again)) ?? unexpected(service, a, step);
+async function create(r, o, json) {
+    const again = [`mason token create --replica ${r.org}/${r.name}`, "make it again"];
+    const s = signedIn("a CI token is made", "mason token create", json);
+    if (isFailure(s))
+        return fail(s, json);
+    const { service, token: login } = s;
+    const a = await call(service, "POST", `/v1/tokens/${r.org}`, { token: login, json: { name: o.label, replica: r.name, scopes: o.scopes, expiresInDays: o.days } });
+    if (isFailure(a)) {
+        return fail({ ...a, why: `${a.why ?? "no answer"}; whether a token was made is not known, and it is never shown again`,
+            fix: `mason token list ${r.org} says the tokens that act: revoke any you did not see made, then make it again`, next: [listStep(r.org), again] }, json);
+    }
+    if (a.status !== 201)
+        return fail(refused(a, r.org, again, [login], service, "a CI token was made"), json);
+    const made = heldMade(a.json, { org: r.org, name: r.name, scopes: o.scopes }, [login]);
+    if (made === null) {
+        // the service answered 201: a token may have been made, whose value nobody has now been shown
+        const f = unexpected(service, a, "a CI token was made");
+        return fail({ ...f, why: `${f.why}; a token may have been made all the same, and it was not shown`,
+            fix: `mason token list ${r.org} says the tokens that act: revoke one you did not see made (mason token revoke <id> --org ${r.org}), then make it again`, next: [listStep(r.org)] }, json);
+    }
+    // the one print of the token: the gate lets this value through once, whole (src/cli/output-gate.ts)
+    holdOutput({ command: "token", json, secrets: [], once: made.value });
+    const t = made.token;
+    const next = [listStep(r.org), [`mason token revoke ${t.id} --org ${r.org}`, "end it"]];
+    if (json) {
+        out(jsonText(TOKEN, { token: { id: t.id, value: made.value, name: t.name, replica: t.replica, scopes: t.scopes, createdAt: t.createdAt, expiresAt: t.expiresAt } }, next));
+        return 0;
+    }
+    // THE TOKEN ON A LINE OF ITS OWN, FIRST, written alone and never broken by the CLI (PR 660's review, B2: a value to copy
+    // is no service text to break at the width — a line break inside it would be copied with it). A terminal narrower
+    // than it wraps it softly, which a copy joins. It cannot begin a line of anyone's making: held to `CI_TOKEN`, it has
+    // no space, no colon and no control character, so no piece of it is a step, a heading or a failure.
+    process.stdout.write(`${made.value}\n`);
+    out(reportText({ headline: `Made a CI token for ${t.replica}: the line above is the token, printed this once`,
+        details: [["id", t.id], ["name", t.name], ["scopes", t.scopes.join(", ")], ["expires", t.expiresAt]],
+        tips: ["Store it now, as MASON_TOKEN in your CI's secrets: the service does not keep it, and nothing shows it again.",
+            `It acts on ${t.replica} alone, for ${t.scopes.join(" and ")}, until it expires or is revoked.`], next }, outStyle()));
+    return 0;
+}
+async function list(org, json) {
+    const s = signedIn("the CI tokens are asked for", org === null ? "mason token list" : `mason token list ${org}`, json);
+    if (isFailure(s))
+        return fail(s, json);
+    const { service, token: login } = s, secrets = [login];
+    const orgs = org !== null ? [org] : await loginOrgs(service, login, "mason token list <org>", MAKERS);
+    if (isFailure(orgs))
+        return fail(orgs, json);
+    const slugs = orgs.map((o) => typeof o === "string" ? o : o.slug);
+    const tokens = [];
+    const more = [];
+    for (const slug of slugs) {
+        const a = await call(service, "GET", `/v1/tokens/${slug}`, { token: login, maxBytes: MAX_LIST_BYTES });
+        if (isFailure(a))
+            return fail(a, json);
+        if (a.status !== 200)
+            return fail(refused(a, slug, listStep(slug), secrets, service, "the CI tokens were asked for"), json);
+        const j = a.json;
+        if (!obj(j) || !Array.isArray(j.tokens) || j.tokens.length > MAX_TOKENS || typeof j.more !== "boolean" || !carriesNoSecret(j, secrets))
+            return fail(unexpected(service, a, "the CI tokens were asked for"), json);
+        for (const v of j.tokens) {
+            const t = heldToken(v, slug, secrets);
+            if (t === null)
+                return fail(unexpected(service, a, "the CI tokens were asked for"), json);
+            tokens.push(t);
+        }
+        if (j.more)
+            more.push(slug);
+    }
+    const where = slugs.length === 1 ? slugs[0] : slugs.length === 0 ? "no organisation this login is an admin or an owner of" : `${slugs.length} organisations`;
+    const first = tokens[0];
+    const next = first !== undefined
+        ? [[`mason token revoke ${first.id} --org ${first.replica.split("/")[0]}`, "end one"], ["mason token create --replica <org>/<name>", "another"]]
+        : [["mason token create --replica <org>/<name>", "make one"]];
+    if (json) {
+        out(jsonText(TOKEN, { tokens, more: more.length > 0 }, next));
+        return 0;
+    }
+    const st = outStyle();
+    const head = tokens.length ? `${tokens.length} CI token${tokens.length === 1 ? "" : "s"} that act, in ${where}` : `No CI tokens that act, in ${where}`;
+    const lines = tokens.map((t) => `  ${t.id}   ${t.name}: ${t.replica}, ${t.scopes.join(" and ")}, until ${t.expiresAt}, last used ${t.lastUsedAt ?? "never"}${t.madeBy ? `, made by ${t.madeBy}` : ""}`);
+    const tips = more.map((o) => `${o} has more CI tokens than the service lists at once: its web app lists them all`);
+    const end = endText({ tips, next }, st);
+    out(strict(`${st.bold(head)}${lines.length ? `\n${lines.join("\n")}` : ""}${end ? `\n${end}` : ""}`, st));
+    return 0;
+}
+async function revoke(id, named, json) {
+    const s = signedIn("a CI token is revoked", `mason token revoke ${id}`, json);
+    if (isFailure(s))
+        return fail(s, json);
+    const { service, token: login } = s, secrets = [login];
+    let org = named;
+    if (org === null) {
+        const orgs = await loginOrgs(service, login, `mason token revoke ${id} --org <org>`, MAKERS);
+        if (isFailure(orgs))
+            return fail(orgs, json);
+        if (orgs.length !== 1) {
+            return fail({ message: orgs.length ? `this login is an admin or an owner of ${orgs.length} organisations: which one is the token of?` : "this login is an admin or an owner of no organisation",
+                code: orgs.length ? "usage" : "refused", why: "an admin or an owner of a token's organisation revokes it",
+                fix: orgs.length ? `name it: mason token revoke ${id} --org <org> (${orgs.map((o) => o.slug).join(", ")})` : "sign in as an admin or an owner of its organisation",
+                next: orgs.length ? orgs.slice(0, 3).map((o) => [`mason token revoke ${id} --org ${o.slug}`]) : [["mason login", `sign in as ${MAY}`]] }, json);
+        }
+        org = orgs[0].slug;
+    }
+    const again = [`mason token revoke ${id} --org ${org}`, "revoke it again"];
+    const a = await call(service, "POST", `/v1/tokens/${org}/${id}/revoke`, { token: login });
+    if (isFailure(a))
+        return fail({ ...a, why: `${a.why ?? "no answer"}; whether it was revoked is not known`, fix: `mason token list ${org} says whether it still acts; revoke it again if it does`, next: [listStep(org), again] }, json);
+    if (a.status !== 200)
+        return fail(refused(a, org, again, secrets, service, "a CI token was revoked"), json);
+    const j = a.json;
+    if (!obj(j) || !carriesNoSecret(j, secrets) || !obj(j.revoked) || j.revoked.id !== id || typeof j.revoked.name !== "string" || j.revoked.name.length > 200)
+        return fail(unexpected(service, a, "a CI token was revoked"), json);
+    const revoked = { org, id, name: serviceText(j.revoked.name, 64, secrets) };
+    const next = [listStep(org)];
+    if (json) {
+        out(jsonText(TOKEN, { revoked }, next));
+        return 0;
+    }
+    out(reportText({ headline: `Revoked the CI token ${id} of ${org}: it acts no more`, details: [["name", revoked.name]], next }, outStyle()));
+    return 0;
+}