@mason-data/cli 0.0.0-stage → 0.6.2

package/dist/src/cli/style.js

@@ -0,0 +1,187 @@
+/**
+ * COLOUR AND WIDTH, for a person at a terminal only (a little colour makes output easier to read and scan). One
+ * palette everywhere:
+ *
+ *   bold     a step's heading, the Next heading, a command's one-line headline
+ *   cyan     what you can type (a command, under Next and in `mason --help`)
+ *   dim      a description, a tip, a secondary fact
+ *   green / red / yellow   a state only: ok and ready, failed, under way or unsure
+ *
+ * and lines wrapped at the terminal's width with a hanging indent, so a long description continues under its own
+ * column instead of under the command names.
+ *
+ * Styled only when the stream is a terminal and NO_COLOR is unset (https://no-color.org); FORCE_COLOR forces it.
+ * Piped, redirected, under --json, or read by a coding agent, every command prints plain, unwrapped text — what an agent
+ * parses never changes. tests/conventions.test.ts refuses a colour code written anywhere else in src/cli.
+ */
+import * as fs from "node:fs";
+import { Worker } from "node:worker_threads";
+const sgr = (on, off) => (s) => s === "" ? s : `\x1b[${on}m${s}\x1b[${off}m`;
+const plainText = (s) => s;
+/** No colour, no wrapping: what a pipe, a file, a test and a coding agent read. */
+export const PLAIN = { bold: plainText, dim: plainText, cyan: plainText, green: plainText, red: plainText, yellow: plainText, width: null };
+const COLOUR = {
+    bold: sgr(1, 22), dim: sgr(2, 22), cyan: sgr(36, 39), green: sgr(32, 39), red: sgr(31, 39), yellow: sgr(33, 39),
+};
+/** Whether to colour `stream`: FORCE_COLOR (not "0") forces it, NO_COLOR (any value) or a non-terminal turns it off. */
+export function colourOn(stream, env = process.env) {
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0")
+        return true;
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    return stream.isTTY === true;
+}
+/** The style for a stream: colour when colourOn, and its width when it is a terminal that says one. */
+export function styleFor(stream, env = process.env) {
+    const width = stream.isTTY === true && stream.columns !== undefined && stream.columns >= 40 ? stream.columns : null;
+    return colourOn(stream, env) ? { ...COLOUR, width } : { ...PLAIN, width };
+}
+/** stdout's style (what a command prints) and stderr's (its progress), read when first asked. */
+export const out = () => styleFor(process.stdout);
+export const err = () => styleFor(process.stderr);
+/** A string's length as the terminal shows it: without its colour codes. */
+export function visibleLength(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+/**
+ * `text` wrapped at `width`, every line after the first indented by `indent` spaces — the first line's own prefix is the
+ * caller's (`  mason init      ` before a description). A word longer than a line is left whole. Null width: unwrapped.
+ */
+export function wrap(text, width, indent, firstUsed = indent) {
+    if (width === null)
+        return text;
+    const room = (used) => Math.max(20, width - used - 1);
+    const lines = [];
+    let line = "", used = firstUsed;
+    for (const word of text.split(" ")) {
+        if (line && visibleLength(line) + 1 + visibleLength(word) > room(used)) {
+            lines.push(line);
+            line = word;
+            used = indent;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    lines.push(line);
+    return lines.join(`\n${" ".repeat(indent)}`);
+}
+/** The spinner's frames, and how long a command may be quiet before it shows. */
+const FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏";
+export const SPIN_AFTER_MS = 300;
+export function spinUntilOutput(label, o = {}) {
+    const out = o.out ?? process.stdout, err = o.err ?? process.stderr;
+    if (err.isTTY !== true)
+        return () => { };
+    const s = styleFor(err, o.env);
+    const fd = o.fd ?? 2;
+    const writeOut = out.write, writeErr = err.write;
+    // the shared cell: [0] 0 turning / 1 stop asked / 2 stopped; [1] 1 once a frame was drawn
+    const state = new SharedArrayBuffer(8);
+    const flag = new Int32Array(state);
+    const frames = [...FRAMES].map((f) => `\r\x1b[2K${s.cyan(f)} ${s.dim(`${label} …`)}`);
+    const worker = new Worker(SPINNER_WORKER, { eval: true, workerData: { fd, frames, delayMs: o.delayMs ?? SPIN_AFTER_MS, state } });
+    worker.unref(); // the command's own end ends it: a worker never keeps mason alive
+    // a frame that cannot be written (the terminal went away: EBADF, EPIPE) is a frame nobody sees; the command's own
+    // output and exit code are untouched by it, so the worker's failure is logged nowhere and ends nothing
+    worker.on("error", () => { Atomics.store(flag, 0, 2); Atomics.notify(flag, 0); });
+    let done = false;
+    const stop = () => {
+        if (done)
+            return;
+        done = true;
+        out.write = writeOut;
+        err.write = writeErr;
+        Atomics.store(flag, 0, 1);
+        Atomics.notify(flag, 0);
+        // the worker's last frame, if one is being written, lands before the clear: wait for it to say it stopped
+        Atomics.wait(flag, 0, 1, 500);
+        if (Atomics.load(flag, 1) === 1)
+            fs.writeSync(fd, "\r\x1b[2K");
+        void worker.terminate();
+    };
+    // the command's first output stops it: the line is cleared, then the output written as it was given
+    const first = (write, target) => ((...a) => { stop(); return write.apply(target, a); });
+    out.write = first(writeOut, out);
+    err.write = first(writeErr, err);
+    return stop;
+}
+/** The worker: waits the delay (a stop in the meantime ends it with nothing drawn), then a frame every 80 ms until
+ *  asked to stop; it writes to the file descriptor it was given, never through a stream the main thread holds. */
+const SPINNER_WORKER = `
+const { workerData } = require("node:worker_threads");
+const fs = require("node:fs");
+const { fd, frames, delayMs, state } = workerData;
+const flag = new Int32Array(state);
+if (Atomics.wait(flag, 0, 0, delayMs) === "timed-out") {
+  let i = 0;
+  while (Atomics.load(flag, 0) === 0) {
+    try { fs.writeSync(fd, frames[i++ % frames.length]); } catch { break; }   // the terminal went away: stop drawing
+    Atomics.store(flag, 1, 1);
+    Atomics.wait(flag, 0, 0, 80);
+  }
+}
+Atomics.store(flag, 0, 2);
+Atomics.notify(flag, 0);
+`;
+/** A step that failed: what its runner throws, carrying what to tell and the exit code (the step's line is already ✘). */
+export class StepFailed extends Error {
+    exit;
+    constructor(message, exit) { super(message); this.exit = exit; }
+}
+/**
+ * STEPS AS THEY HAPPEN, drawn (the renderer under checklist, and what mason start's relay draws its run's steps with):
+ * `begin` turns a spinner beside the step's label (a terminal only), `done` and `fail` replace it with the step's line,
+ * `print` writes any other line above it without breaking the spinner. Anywhere but a terminal only the finished lines.
+ */
+export function stepRenderer(o) {
+    const s = o.style ?? PLAIN;
+    const live = o.live ?? null;
+    let label = null, frame = 0, timer;
+    const draw = () => { if (live && label !== null)
+        live.write(`\r\x1b[2K${s.cyan(FRAMES[frame++ % FRAMES.length])} ${label} …`); };
+    const clear = () => { if (live && label !== null)
+        live.write("\r\x1b[2K"); };
+    const end = (text) => { if (timer)
+        clearInterval(timer); timer = undefined; clear(); label = null; o.line(text); };
+    return {
+        begin(text) {
+            if (label !== null)
+                end(`${s.green(live ? "✔" : "✓")} ${label}`); // a step left open by the next one: it ended
+            label = text;
+            if (live) {
+                draw();
+                timer = setInterval(draw, 80);
+                timer.unref();
+            }
+        },
+        done(text) { end(`${s.green(live ? "✔" : "✓")} ${text ?? label ?? ""}`); },
+        fail(text) { end(`${s.red(live ? "✘" : "✗")} ${text ?? label ?? ""}`); },
+        print(text) { clear(); o.line(text); draw(); },
+        /** a step still turning: its label (null when none) */
+        open: () => label,
+    };
+}
+/**
+ * A CHECKLIST OF WHAT A COMMAND DOES (first `mason init`'s: each item it is doing, with a spinner left of it that turns
+ * into a checkmark when done, so it is seen working live, and the end result a checklist of what it did, all checked
+ * off). On a terminal each step turns (`⠋ Connecting to …`) until it ends, then becomes
+ * its line: `✔ Connected to …`, or `✘ Connecting to …` when it throws. Anywhere else only the finished lines are written
+ * (`✓ Connected to …`), one each, so a log or a coding agent reads the same checklist without the animation.
+ */
+export function checklist(o) {
+    const r = stepRenderer(o);
+    return {
+        async step(label, run, done = () => label) {
+            r.begin(label);
+            try {
+                const v = await run();
+                r.done(done(v));
+                return v;
+            }
+            catch (e) {
+                r.fail(label);
+                throw e;
+            }
+        },
+    };
+}

package/dist/src/cli/supervise.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * THE RUN'S SUPERVISOR (a run that crashed — `SELECT *` of 23 M rows ran it out of V8's heap — stayed dead,
+ * and the sync, the listener and every client's session with it). `mason start` in the background (src/cli/
+ * background.ts) starts THIS, detached, and this starts the run (`mason start … --attach`), its terminal the
+ * run's `dev.log` as before, and starts it again when it dies:
+ * - only AFTER IT WAS READY: a start that fails (a wrong password, a port held) is said and exits, as before;
+ * - only while its config still says it runs: `mason stop` sends SIGTERM and the run records `running: null` before it
+ *   exits, so a stop is never undone; neither is a run that exits 0 on its own;
+ * - never after a stop BETWEEN restarts (the Fable review of #517: the run is dead while it waits, so `mason stop` said
+ *   "not running" and the run came back seconds later): it records its pid in `.mason/supervisor.json`, `mason stop` and
+ *   `mason destroy` signal it when no run answers (`stopSupervisor`), and the config is read again after the wait;
+ * - never over a run `mason stop` KILLED because it did not answer (on the test server the kill was recorded
+ *   as a crash, "often the system out of memory"): stop signals the supervisor FIRST (`signalSupervisor`, no wait: the
+ *   supervisor is waiting for the run, which is hung), then ends the run, then waits for the supervisor (`supervisorGone`),
+ *   and the run's exit is a stop. The packaged CLI runs this file as `supervise.js` (cli/build.ts), and the supervisor is
+ *   known by EITHER name (`isSupervisorCommand`): known by `.ts` alone, no packaged stop ever found it;
+ * - never in a loop: after RESTART_LIMIT restarts within RESTART_WINDOW_MS it gives up, and says so;
+ * - on the same Postgres port, so a tool's saved connection still reaches it (the run chose it, or MASON_PG_PORT).
+ * Each restart is a line in the run's log and an entry in `.mason/restarts.json` (why, when, after how long up), which
+ * mason status shows. DuckDB recovers the copy from its write-ahead log: a restart costs seconds, never a fresh copy.
+ *
+ *   node supervise.ts <project's .mason dir> <dev.log> <the run's command…>
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { exitWhenWritten } from "../lib/exit-when-written.js";
+export const READY_LINE = "mason start: ready";
+export const RESTARTS_FILE = "restarts.json";
+export const SUPERVISOR_FILE = "supervisor.json";
+export const RESTART_LIMIT = 5;
+export const RESTART_WINDOW_MS = 10 * 60_000;
+/** the wait before each restart, by how many came before it in the window */
+const BACKOFF_MS = [1_000, 2_000, 5_000, 15_000, 30_000];
+/** The restarts recorded for a project's run, oldest first ([] when none; a file that cannot be read is said, not hidden). */
+export function readRestarts(home) {
+    const file = path.join(home, RESTARTS_FILE);
+    if (!fs.existsSync(file))
+        return [];
+    const v = JSON.parse(fs.readFileSync(file, "utf8"));
+    return Array.isArray(v.restarts) ? v.restarts : [];
+}
+/** Why a run died, in the words a person reads: V8's own fatal line when it printed one */
+export function crashReason(code, signal, fatal) {
+    // Mason's own fatal line (src/cli/dev.ts: the copy's thread stopped) is said as Mason said it
+    if (fatal !== null)
+        return /heap out of memory/i.test(fatal) && !fatal.startsWith("Mason: ") ? "it ran out of JavaScript heap (V8: heap out of memory)"
+            : fatal.startsWith("Mason: ") ? fatal.slice("Mason: ".length) : `V8: ${fatal}`;
+    if (signal === "SIGKILL")
+        return "it was killed (SIGKILL: often the system out of memory)";
+    if (signal !== null)
+        return `it crashed (${signal})`;
+    return `it exited with code ${code}`;
+}
+/** Whether a process's command line (ps) is a run's supervisor: this file, by its checkout name or its packaged one. */
+export function isSupervisorCommand(command) {
+    return /supervise\.[tj]s\b/.test(command);
+}
+/** The supervisor recorded for a project's run, when it is still alive and is a supervisor (a pid alone is no proof:
+ *  after a reboot the number is another process's, src/cli/runs.ts), else null. */
+export function supervisorOf(home) {
+    const file = path.join(home, SUPERVISOR_FILE);
+    if (!fs.existsSync(file))
+        return null;
+    let pid;
+    // a file that cannot be read names no process: nothing is signalled over it (ps below is what decides, never the file)
+    try {
+        pid = JSON.parse(fs.readFileSync(file, "utf8")).pid;
+    }
+    catch {
+        return null;
+    }
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return null;
+    const ps = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8" });
+    // ps exits 1 for a pid that is gone; its command line names this file for a supervisor (background.ts starts it so)
+    return ps.status === 0 && isSupervisorCommand(ps.stdout) ? pid : null;
+}
+/** Tells the project's supervisor to stop (SIGTERM: it passes it to the run and starts nothing after); its pid, or
+ *  null when there is none. It does not wait: a supervisor over a hung run leaves only once the run is ended. */
+export function signalSupervisor(home) {
+    const pid = supervisorOf(home);
+    if (pid === null)
+        return null;
+    process.kill(pid, "SIGTERM");
+    return pid;
+}
+/** Waits for a signalled supervisor to leave; one still there after `ms` is said, never reported gone. */
+export async function supervisorGone(home, pid, ms = 10_000) {
+    const until = Date.now() + ms;
+    while (supervisorOf(home) === pid && Date.now() < until)
+        await new Promise((r) => setTimeout(r, 100));
+    if (supervisorOf(home) === pid)
+        throw new Error(`the supervisor of Mason's run (pid ${pid}) is still running after ${ms / 1000} s: kill ${pid}`);
+}
+/** Stops the project's supervisor when one is waiting to start the run again; its pid, or null when there was none. */
+export async function stopSupervisor(home, ms = 10_000) {
+    const pid = signalSupervisor(home);
+    if (pid === null)
+        return null;
+    await supervisorGone(home, pid, ms);
+    return pid;
+}
+/** whether the run's config still says it runs (a stop records null first) */
+function stillRunning(home, note) {
+    try {
+        const c = JSON.parse(fs.readFileSync(path.join(home, "config.json"), "utf8"));
+        return c.running ?? null;
+    }
+    catch (e) {
+        // a config that cannot be read is no run that claims to be up: nothing is restarted over it, and it is said
+        note(`.mason/config.json could not be read (${e.message}): not starting the run again`);
+        return null;
+    }
+}
+/** What the run wrote to the log from `from` on: whether it said it was ready, and V8's fatal line if it printed one.
+ *  Read after it exits, in chunks: a run's log with every statement traced (MASON_PG_TRACE) runs to hundreds of MB. */
+export function scanLog(file, from) {
+    let ready = false;
+    let fatal = null;
+    const fd = fs.openSync(file, "r");
+    try {
+        const buf = Buffer.alloc(1 << 20);
+        let partial = "";
+        for (let at = from;;) {
+            const n = fs.readSync(fd, buf, 0, buf.length, at);
+            const lines = (partial + buf.toString("utf8", 0, n)).split("\n");
+            partial = n === 0 ? "" : lines.pop() ?? "";
+            for (const l of lines) {
+                if (l === READY_LINE)
+                    ready = true;
+                const f = /^FATAL ERROR: (.*)$/.exec(l.trim());
+                if (f)
+                    fatal = f[1];
+            }
+            if (n === 0)
+                break;
+            at += n;
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return { ready, fatal };
+}
+/** Runs the run until it stops for good; the exit code is the last run's (a start that failed: its own). */
+export async function supervise(o) {
+    const now = o.now ?? Date.now;
+    const sleep = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const fd = fs.openSync(o.logFile, "a", 0o600);
+    const note = (line) => { fs.writeSync(fd, `mason supervisor: ${line}\n`); };
+    let stopping = false;
+    let child = null;
+    let wake = () => undefined;
+    const stopped = new Promise((r) => { wake = r; });
+    // a signal to the supervisor (a shutdown, the terminal's group, mason stop between restarts) is the run's: passed on,
+    // the wait before a restart cut short, and nothing restarted after
+    const pass = (s) => () => { stopping = true; child?.kill(s); wake(); };
+    const handlers = ["SIGTERM", "SIGINT", "SIGHUP"].map((s) => [s, pass(s)]);
+    for (const [s, h] of handlers)
+        process.on(s, h);
+    const recent = [];
+    let env = {};
+    const mine = path.join(o.home, SUPERVISOR_FILE);
+    fs.writeFileSync(mine, `${JSON.stringify({ pid: process.pid })}\n`, { mode: 0o600 });
+    try {
+        for (;;) {
+            const started = now();
+            const from = fs.fstatSync(fd).size;
+            child = o.start(env, fd);
+            const c = child;
+            const { code, signal } = await new Promise((resolve) => c.once("exit", (code, signal) => resolve({ code, signal })));
+            const { ready, fatal } = scanLog(o.logFile, from);
+            if (stopping || !ready || (code === 0 && signal === null))
+                return code ?? 1;
+            const running = stillRunning(o.home, note);
+            if (running === null)
+                return code ?? 1;
+            // died after it was ready, while its config says it runs: a crash
+            const reason = crashReason(code, signal, fatal);
+            const upSeconds = Math.round((now() - started) / 1000);
+            while (recent.length > 0 && now() - recent[0] > RESTART_WINDOW_MS)
+                recent.shift();
+            if (recent.length >= RESTART_LIMIT) {
+                note(`the run stopped (${reason}) after ${upSeconds} s, its ${RESTART_LIMIT + 1}th crash in ${RESTART_WINDOW_MS / 60_000} minutes: not restarting again. mason logs --start shows why; mason start starts it`);
+                return code ?? 1;
+            }
+            const wait = BACKOFF_MS[Math.min(recent.length, BACKOFF_MS.length - 1)];
+            recent.push(now());
+            let before = [];
+            // the record is for mason status; one that cannot be read (cut short, edited) never costs the run its restart:
+            // said in the log, and the record starts again from this restart
+            try {
+                before = readRestarts(o.home);
+            }
+            catch (e) {
+                note(`${RESTARTS_FILE} could not be read (${e.message}): it is written again from this restart`);
+            }
+            const restarts = [...before, { at: new Date(now()).toISOString(), reason, upSeconds }].slice(-20);
+            fs.writeFileSync(path.join(o.home, RESTARTS_FILE), `${JSON.stringify({ restarts }, null, 2)}\n`, { mode: 0o600 });
+            note(`the run stopped (${reason}) after ${upSeconds} s: starting it again in ${wait / 1000} s (mason status shows each restart)`);
+            // the same Postgres port, so a client's saved connection reaches the new run
+            const port = running.postgresUrl === undefined ? "" : new URL(running.postgresUrl.replace(/^postgres(ql)?:/, "http:")).port;
+            env = port !== "" && !process.env.MASON_PG_PORT ? { MASON_PG_PORT: port } : {};
+            await Promise.race([sleep(wait), stopped]);
+            // a stop while it waited (a signal), or a config that no longer says it runs (mason destroy cleared it)
+            if (stopping || stillRunning(o.home, note) === null)
+                return code ?? 1;
+        }
+    }
+    finally {
+        for (const [s, h] of handlers)
+            process.off(s, h);
+        // only our own record goes: a new mason start may have started a supervisor of its own meanwhile
+        try {
+            if (JSON.parse(fs.readFileSync(mine, "utf8")).pid === process.pid)
+                fs.rmSync(mine);
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                note(`${SUPERVISOR_FILE} could not be removed (${e.message})`);
+        } // gone already: mason destroy emptied .mason/
+        fs.closeSync(fd);
+    }
+}
+function isMain() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    } // argv[1] names no file (node -e): not run as a script
+}
+if (isMain()) {
+    const [home, logFile, command, ...args] = process.argv.slice(2);
+    if (home === undefined || logFile === undefined || command === undefined) {
+        process.stderr.write("usage: supervise.ts <.mason dir> <dev.log> <the run's command…>\n");
+        exitWhenWritten(2);
+    }
+    else {
+        exitWhenWritten(await supervise({ home, logFile,
+            start: (env, fd) => spawn(command, args, { stdio: ["ignore", fd, fd], env: { ...process.env, ...env } }) }));
+    }
+}

package/dist/src/cli/sync.js

@@ -0,0 +1,94 @@
+/**
+ * `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`).
+ */
+import { failed, jsonText, parseCommand, reportText } from "./command.js";
+import { out as styleOut } from "./style.js";
+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";
+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.
+
+    mason sync orders
+    mason sync orders public.events
+
+  --json   as data: { syncedAt, tables: [{ table, changed, deleted, rows, ms }], 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)",
+    usage: SYNC_USAGE,
+    options: { json: { type: "boolean" } },
+    json: ["syncedAt", "tables", "next"],
+};
+export async function sync(argv) {
+    const f = parseCommand(SYNC, argv);
+    if (typeof f === "number")
+        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 w = await reach(SYNC, json);
+    if (w === null || !("run" in w))
+        return 1;
+    const run = w.run;
+    return guarded("sync", json, async () => {
+        const s = await readState(run);
+        const added = s.tables.filter((t) => t.added);
+        const picked = [];
+        for (const name of names) {
+            const t = findTable(added, name);
+            if (!("message" in t)) {
+                picked.push(t.table);
+                continue;
+            }
+            // a table of the database that is not added is told so, with the command that adds it
+            const db = findTable(s.tables, name);
+            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)}`,
+                    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",
+                next: [["mason status", "the added tables"], ["mason tables", "the database's tables"]] }, { json });
+        }
+        // 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";
+            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 });
+        }
+        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"]];
+        if (json) {
+            out(jsonText(SYNC, { syncedAt: b.at, tables: b.tables }, 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()));
+        return 0;
+    });
+}

package/dist/src/cli/ui.js

@@ -0,0 +1,107 @@
+/**
+ * `mason ui` — THE WEB PAGE OF THE RUNNING MASON, IN THE BROWSER (src/web/, docs/WEB-UI.md): what `mason status` says,
+ * refreshed while the tab is seen, and the users of `mason user`. 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
+ * 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.
+ *
+ * Before it prints anything it ASKS the page (`GET /` with the run's token as the commands send it), so a run that serves
+ * none (`mason serve`'s, or one from before the page) is said, never a URL that answers 404.
+ */
+import { spawn } from "node:child_process";
+import { failed, jsonText, parseCommand, reportText } from "./command.js";
+import { reach } from "./state.js";
+import { RunUnreachable } from "./control.js";
+const out = (m) => { process.stdout.write(`${m}\n`); };
+export const UI = {
+    needs: "run",
+    name: "ui",
+    summary: "the status page and the users, in your browser",
+    usage: `usage: mason ui [--no-open] [--json]
+
+  Opens the running Mason's web page in your browser: what mason status says (the database, each table's copy and
+  its progress, the slow and refused statements, whether it is ready), refreshed every 2 s while the tab is open, and
+  the users of mason user — add one (its password shown once, with the URL to paste) or remove one.
+
+  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. The page is mason start's: mason serve serves none (off this
+  machine it would need TLS and a login).
+
+    mason ui
+    mason ui --no-open        print the URL, open no browser
+    mason ui --json
+
+  --no-open   print the URL only
+  --json      as data: { url (with this run's token), port }, next; it never opens a browser
+`,
+    options: { "no-open": { type: "boolean", default: false }, json: { type: "boolean", default: false } },
+    json: ["url", "port", "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`). */
+export function openCommand(platform, url) {
+    if (platform === "darwin")
+        return ["open", [url]];
+    // start's first quoted argument is a window title: "" so the URL is the thing started
+    if (platform === "win32")
+        return ["cmd", ["/c", "start", "", url]];
+    return ["xdg-open", [url]];
+}
+/** Open `url` in the browser: null once the opener started, else why it could not (the URL is printed either way). */
+function openBrowser(url) {
+    const [command, args] = openCommand(process.platform, url);
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        child.once("error", (e) => resolve(`${command}: ${e.message}`));
+        child.once("spawn", () => { child.unref(); resolve(null); });
+    });
+}
+/** Whether the run serves the page: its `GET /` answered, with the token the commands send. */
+async function servesPage(run) {
+    let res;
+    try {
+        res = await fetch(`${run.control.url}/`, { headers: { Authorization: `Bearer ${run.control.token}` }, signal: AbortSignal.timeout(10_000) });
+    }
+    catch (e) {
+        throw new RunUnreachable(`Mason for ${run.name} (pid ${run.pid}) does not answer at ${run.control.url}`, e.cause?.code ?? e.message);
+    }
+    await res.arrayBuffer();
+    return res.status === 200 && /^text\/html/.test(res.headers.get("content-type") ?? "");
+}
+export async function ui(argv) {
+    const f = parseCommand(UI, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    if (f.positionals.length)
+        return failed("ui", { message: `mason ui takes no argument: ${f.positionals.join(" ")}`, code: "usage", usage: UI.usage }, { json });
+    const w = await reach(UI, json);
+    if (w === null || w.state !== "up")
+        return 1;
+    const run = w.run;
+    if (!await servesPage(run)) {
+        return failed("ui", { message: `Mason for ${run.name} serves no web page`, code: "refused",
+            why: "the page is mason start's: this is mason serve's run, or a run started by a Mason from before the page",
+            fix: "on your machine, mason stop && mason start runs it with the page; a server's Mason is read with mason status",
+            next: [["mason status", "what it is doing, in this terminal"]] }, { json });
+    }
+    const url = `${run.control.url}/?token=${encodeURIComponent(run.control.token)}`;
+    const port = Number(new URL(run.control.url).port);
+    if (json) {
+        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;
+    out(reportText({
+        headline: opened ? `Mason's web page, opened in your browser` : `Mason's web page`,
+        details: [["url", url], ["project", run.name]],
+        tips: [
+            ...(couldNot !== null ? [`Could not open a browser (${couldNot}): open the URL yourself.`] : []),
+            "The URL carries this run's token, traded for a cookie on the first visit: paste it nowhere else. After a restart, mason ui again.",
+        ],
+        next: NEXT,
+    }));
+    return 0;
+}