@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/api/postgres/translate.js

@@ -1,3 +1,17 @@
+/**
+ * WHAT A STATEMENT IS, from Postgres 18's own parse tree (parser.ts), decided by node kind, never by text:
+ *
+ *   - a SELECT that reads any table outside pg_catalog / information_schema: DuckDB's (`duckdb`), planned by the
+ *     catalog Postgres and rewritten (src/duck/plan.ts) — the text here is only what the plan is made from;
+ *   - a CATALOG statement (one that reads only `pg_catalog` / `information_schema`, or no table at all: `SELECT
+ *     version()`, `SELECT 1`): forwarded by the server to the Postgres inside the process (catalog.ts), which answers it
+ *     as Postgres;
+ *   - a SESSION statement (`SET`, `SHOW`, `BEGIN` / `COMMIT`, `DISCARD`, `DEALLOCATE`): the server's;
+ *   - an EXPLAIN: the statement it explains, classified as it would be alone (src/api/postgres/explain.ts);
+ *   - anything else: REFUSED BY NAME (`Unsupported`), with its position in the statement, a SQLSTATE and the way
+ *     out, never passed through on a guess. The switch has no default branch that accepts.
+ */
+import { gapMark } from "../../duck/gaps.js";
 /** A statement, or a part of one, this listener does not answer: named, placed, with a SQLSTATE and the way out. */
 export class Unsupported extends Error {
     /** 0-based offset into the statement's text, or null when the whole statement is meant */
@@ -5,11 +19,14 @@ export class Unsupported extends Error {
     /** `0A000` feature not supported; `42601` syntax; `25006` read only; `22023` an invalid value */
     sqlstate;
     hint;
-    constructor(message, offset, sqlstate = "0A000", hint) {
+    /** the registry entry that refused it (src/duck/gaps.ts): the request log's `gap`; null for any other refusal */
+    gap;
+    constructor(message, offset, sqlstate = "0A000", hint, gap = null) {
         super(message);
         this.offset = offset;
         this.sqlstate = sqlstate;
         this.hint = hint;
+        this.gap = gap;
     }
 }
 const kindOf = (n) => Object.keys(n)[0] ?? "";
@@ -38,8 +55,55 @@ function collect(n, kind, out = []) {
     }
     return out;
 }
+/**
+ * Whether a statement of no table has a construct that can order text, read off the raw tree: a sort (ORDER BY, a
+ * window's, an aggregate's or WITHIN GROUP's), <, >, <=, >= (BETWEEN, ANY / ALL and a subquery's among them),
+ * GREATEST / LEAST, min / max, upper / lower / initcap (which map case, issue 406), and a COLLATE (`'a' = 'A' COLLATE mason_ci`). One without (`SELECT 1`, `SELECT version()`, `current_setting(…)`, `'a' = 'A'`) is the
+ * catalog's without asking its analysis, which costs a statement several milliseconds (`ordersText`, issue 122): a
+ * statement it says may order is asked, so a false "may" costs time, never an answer.
+ */
+export function mayOrderText(n) {
+    if (Array.isArray(n))
+        return n.some(mayOrderText);
+    if (n === null || typeof n !== "object")
+        return false;
+    const named = (x) => collect(x ?? [], "String").map((s) => String(bodyOf(s).sval ?? ""));
+    for (const [k, v] of Object.entries(n)) {
+        if ((k === "sortClause" || k === "orderClause" || k === "agg_order") && Array.isArray(v) && v.length > 0)
+            return true;
+        if (k === "MinMaxExpr")
+            return true;
+        // a COLLATE names a collation the source declared, whose rules the catalog's copy of it does not hold: a
+        // nondeterministic one equates otherwise, and the synced data's plan refuses it by name (`ordersText` asks)
+        if (k === "CollateClause")
+            return true;
+        if ((k === "A_Expr" || k === "SubLink") && v !== null && typeof v === "object") {
+            const b = v;
+            if (typeof b.kind === "string" && b.kind.includes("BETWEEN"))
+                return true;
+            if (named(b.name ?? b.operName).some((o) => ORDERING_OPERATORS.has(o)))
+                return true;
+        }
+        // min / max order text; upper / lower / initcap map its case, which the catalog does by its own rules (issue 406)
+        if (k === "FuncCall" && v !== null && typeof v === "object" && COLLATED_CALLS.has((named(v.funcname).at(-1) ?? "").toLowerCase()))
+            return true;
+        if (mayOrderText(v))
+            return true;
+    }
+    return false;
+}
+const ORDERING_OPERATORS = new Set(["<", ">", "<=", ">="]);
+const COLLATED_CALLS = new Set(["min", "max", "upper", "lower", "initcap"]);
 const INFORMATION_SCHEMA = "information_schema";
 const PG_CATALOG = "pg_catalog";
+/** Postgres's IsTransactionExitStmt: what a failed block still accepts. `ROLLBACK TO` and `PREPARE TRANSACTION` are among
+ *  them, each then refused here for being what it is, a savepoint or a prepared transaction, never for the block. */
+export function endsFailedBlock(stmt) {
+    if (kindOf(stmt) !== "TransactionStmt")
+        return false;
+    const k = bodyOf(stmt).kind;
+    return k === "TRANS_STMT_COMMIT" || k === "TRANS_STMT_ROLLBACK" || k === "TRANS_STMT_ROLLBACK_TO" || k === "TRANS_STMT_PREPARE";
+}
 // ------------------------------------------------------------------ entry
 /** A statement other than a SELECT or an EXPLAIN (`duckTranslate` takes those): the session's, or refused by name. */
 function sessionStatement(stmt) {
@@ -51,10 +115,10 @@ function sessionStatement(stmt) {
             const k = bodyOf(stmt).kind;
             const tag = k === "TRANS_STMT_BEGIN" ? "BEGIN" : k === "TRANS_STMT_START" ? "START TRANSACTION" : k === "TRANS_STMT_COMMIT" ? "COMMIT" : k === "TRANS_STMT_ROLLBACK" ? "ROLLBACK" : null;
             if (tag === null)
-                throw new Unsupported(`${String(k).replace("TRANS_STMT_", "").toLowerCase()}: this connection is read-only and has no transactions; BEGIN, COMMIT and ROLLBACK are accepted and do nothing`, null);
+                throw new Unsupported(`${String(k).replace("TRANS_STMT_", "").toLowerCase()}: this connection is read-only and has no savepoints or prepared transactions; BEGIN, COMMIT and ROLLBACK are accepted, and a ROLLBACK undoes the block's SETs`, null);
             return { kind: "transaction", tag };
         }
-        case "DiscardStmt": return { kind: "discard" };
+        case "DiscardStmt": return { kind: "discard", target: String(bodyOf(stmt).target ?? "DISCARD_ALL").replace(/^DISCARD_/, "") };
         case "DeallocateStmt": return { kind: "deallocate" };
         case "InsertStmt":
         case "UpdateStmt":
@@ -73,7 +137,7 @@ function sessionStatement(stmt) {
         case "CreateFunctionStmt":
         case "CreateSchemaStmt":
         case "VacuumStmt":
-            throw new Unsupported(`${kind.replace(/Stmt$/, "").replace(/([a-z])([A-Z])/g, "$1 $2").toUpperCase()}: this is a read-only copy of the database's tables; only SELECT, SET, SHOW and the transaction no-ops are accepted`, null, "25006");
+            throw new Unsupported(`${kind.replace(/Stmt$/, "").replace(/([a-z])([A-Z])/g, "$1 $2").toUpperCase()}: these are the database's tables, synced and read-only; only SELECT, SET, SHOW and the transaction no-ops are accepted`, null, "25006");
         case "PrepareStmt":
         case "ExecuteStmt": throw new Unsupported(`${kind === "PrepareStmt" ? "PREPARE" : "EXECUTE"} is not supported: use the protocol's prepared statements (every driver does)`, null);
         default:
@@ -90,6 +154,9 @@ function sessionStatement(stmt) {
  * (a review finding).
  */
 export function duckTranslate(stmt, text) {
+    const configured = setConfig(stmt);
+    if (configured !== null)
+        return configured;
     const kind = kindOf(stmt);
     // an EXPLAIN is the statement it explains (src/api/postgres/explain.ts, src/duck/explain.ts): its options read, then
     // that statement classified as it would be alone, by the server
@@ -105,10 +172,53 @@ export function duckTranslate(stmt, text) {
     const ctes = (s.withClause?.ctes ?? []).map((n) => bodyOf(n));
     const names = new Set(ctes.map((c) => String(c.ctename ?? "")));
     const relations = collect(s, "RangeVar").map((n) => bodyOf(n)).filter((r) => r.schemaname !== undefined || !names.has(String(r.relname ?? "")));
+    if (relations.length === 0)
+        return mayOrderText(s) ? { kind: "catalog", fromless: { names: pgColumnNames(s) } } : { kind: "catalog" };
     if (relations.every(isCatalogRelation))
         return { kind: "catalog" };
     return { kind: "duckdb", sql: text, names: pgColumnNames(s) };
 }
+/**
+ * `set_config(name, value, is_local)` IS A SET, and a session's SET is the listener's: forwarded, it ran on the catalog's
+ * ONE connection, as its superuser, outside any transaction, so its value stayed for EVERY session — `set_config(
+ * 'search_path', 'zzz', false)` moved the catalog's resolution of `current_setting` and `version()` to Postgres's own,
+ * and a `myapp.x` one session set another read (a review finding of #46). So every call of it is the session's or
+ * refused, wherever it is in the statement (an EXPLAIN ANALYZE's included): alone in a SELECT of no table, its
+ * arguments literals (what a tool sends: pgAdmin's `bytea_output`, an ORM's `search_path`), it is `SET name = value`,
+ * or `SET LOCAL` under `is_local`, answered as the function's row; any other form is the `set-config-forms` gap. null:
+ * no call of it.
+ */
+function setConfig(stmt) {
+    const named = (n) => {
+        const parts = strings(bodyOf(n).funcname);
+        return parts[parts.length - 1] === "set_config" && (parts.length === 1 || (parts.length === 2 && parts[0] === PG_CATALOG));
+    };
+    const calls = collect(stmt, "FuncCall").filter(named);
+    if (calls.length === 0)
+        return null;
+    const refuse = (at) => {
+        throw new Unsupported(`set_config() is answered by Mason only alone in a SELECT, with literal arguments (${gapMark("set-config-forms")})`, at, "0A000", "write SET name = 'value', or SELECT set_config('name', 'value', false) on its own", "set-config-forms");
+    };
+    const at = loc(calls[0]);
+    if (kindOf(stmt) !== "SelectStmt")
+        return refuse(at);
+    const s = bodyOf(stmt);
+    if (Object.keys(s).some((k) => k !== "targetList" && k !== "limitOption" && k !== "op") || s.op !== "SETOP_NONE")
+        return refuse(at);
+    const targets = (s.targetList ?? []);
+    const target = targets.length === 1 ? bodyOf(targets[0]) : null;
+    if (target?.val === undefined || kindOf(target.val) !== "FuncCall" || !named(target.val))
+        return refuse(at);
+    const call = bodyOf(target.val);
+    if (Object.keys(call).some((k) => k !== "funcname" && k !== "args" && k !== "funcformat" && k !== "location"))
+        return refuse(at);
+    const args = (call.args ?? []).map((a) => kindOf(a) === "A_Const" ? bodyOf(a) : null);
+    const text = (c) => typeof c?.sval?.sval === "string" ? c.sval.sval : null;
+    const [name, value, local] = [text(args[0] ?? null), text(args[1] ?? null), args[2]?.boolval];
+    if (args.length !== 3 || name === null || value === null || local === undefined)
+        return refuse(at);
+    return { kind: "set_config", name: name.toLowerCase(), value, local: local.boolval === true, column: target.name ?? "set_config" };
+}
 /**
  * THE NAMES POSTGRES GIVES A SELECT'S RESULT COLUMNS (`FigureColname`, src/backend/parser/parse_target.c), where DuckDB
  * gives others (`count(*)` is `count_star()`, `sum(x)` is `sum(x)`; Postgres says `count`, `sum`): an alias as written,
@@ -212,12 +322,19 @@ function figureColname(n) {
 }
 function setStatement(s) {
     const name = String(s.name ?? "").toLowerCase();
-    if (s.kind === "VAR_RESET" || s.kind === "VAR_SET_DEFAULT")
-        return { kind: "set", name, value: null, local: s.is_local === true };
+    if (s.kind === "VAR_RESET")
+        return { kind: "set", name, value: null, local: false, tag: "RESET" };
+    if (s.kind === "VAR_SET_DEFAULT")
+        return { kind: "set", name, value: null, local: s.is_local === true, tag: "SET" };
     if (s.kind === "VAR_RESET_ALL")
-        return { kind: "set", name: "all", value: null, local: false };
-    if (s.kind === "VAR_SET_MULTI")
-        return { kind: "set", name, value: "", local: s.is_local === true }; // SET SESSION CHARACTERISTICS …
+        return { kind: "set", name: "all", value: null, local: false, tag: "RESET" };
+    // SET TRANSACTION is for the transaction alone, whichever way it is spelt; SET SESSION CHARACTERISTICS is the session's
+    // its value is the isolation level it names, '' for none (`READ ONLY` alone): the listener remembers the level
+    if (s.kind === "VAR_SET_MULTI") {
+        const level = (s.args ?? []).map((a) => a.DefElem).find((d) => d?.defname === "transaction_isolation");
+        const value = level?.arg !== undefined && kindOf(level.arg) === "A_Const" ? constText(bodyOf(level.arg)) : "";
+        return { kind: "set", name, value, local: name === "transaction", tag: "SET" };
+    }
     if (s.kind !== "VAR_SET_VALUE")
         throw new Unsupported(`SET ${name}: ${String(s.kind)} is not supported`, s.location ?? null);
     const parts = (s.args ?? []).map((a) => {
@@ -230,7 +347,7 @@ function setStatement(s) {
         }
         throw new Unsupported(`SET ${name}: a value of kind ${kindOf(a)} is not supported (a literal is)`, loc(a));
     });
-    return { kind: "set", name, value: parts.join(", "), local: s.is_local === true };
+    return { kind: "set", name, value: parts.join(", "), local: s.is_local === true, tag: "SET" };
 }
 function constText(c) {
     if (c.sval !== undefined)

package/dist/src/api/request-log.js

@@ -8,17 +8,30 @@
 import * as crypto from "node:crypto";
 /** Fail closed on the storage side: never let one request bloat the ledger. */
 export const MAX_STORED_PAYLOAD_BYTES = 64 * 1024;
+/** The SQLSTATE of a cancelled statement: a CancelRequest, `mason cancel`, or a statement_timeout (Postgres's 57014). */
+export const CANCELLED_SQLSTATE = "57014";
+/** The SQLSTATE classes whose fault is Mason's or the machine's: XX internal, 53 resources, 57 an operator's, 58 system. */
+export const FAILED_CLASSES = ["XX", "53", "57", "58"];
+export const OUTCOMES = ["ok", "refused", "failed", "cancelled"];
 /**
- * A Postgres-listener statement's outcome in a word, from the SQLSTATE it was sent: `failed` where the fault is Mason's
- * or the machine's (classes XX internal, 53 resources, 57 a timeout or a cancel, 58 system), `refused` for the
- * statement's own, `ok` for none. Read by the listener's refusal line (server.ts `refusalLine`) and the request log
- * (src/duck/requests.ts) alike.
+ * A Postgres-listener statement's outcome in a word, from the SQLSTATE it was sent: `cancelled` for 57014 (a cancel or a
+ * timeout), `failed` where the fault is Mason's or the machine's (FAILED_CLASSES), `refused` for the statement's own,
+ * `ok` for none. Read by the listener's refusal line (server.ts `refusalLine`) and the request log (src/duck/requests.ts)
+ * alike; the ledger's filter and summary read the SAME rule as SQL (`outcomeSql`), held equal by tests/duck-requests.test.ts.
  */
 export function outcomeOf(sqlstate) {
     if (sqlstate === null || sqlstate === undefined || sqlstate === "")
         return "ok";
-    return /^(XX|53|57|58)/.test(sqlstate) ? "failed" : "refused";
+    if (sqlstate === CANCELLED_SQLSTATE)
+        return "cancelled";
+    return FAILED_CLASSES.some((c) => sqlstate.startsWith(c)) ? "failed" : "refused";
 }
+/** `outcomeOf` as a SQL expression over a SQLSTATE column: the one rule, for the ledger's filters and summary. */
+export function outcomeSql(column) {
+    return `CASE WHEN ${column} IS NULL OR ${column} = '' THEN 'ok' WHEN ${column} = '${CANCELLED_SQLSTATE}' THEN 'cancelled' ` +
+        `WHEN left(${column}, 2) IN (${FAILED_CLASSES.map((c) => `'${c}'`).join(", ")}) THEN 'failed' ELSE 'refused' END`;
+}
+export const statusOf = (o) => o === "ok" ? "completed" : o === "cancelled" ? "cancelled" : "failed";
 /**
  * The caller's identity WITHOUT the credential: a truncated SHA-256 of what was presented. Distinct callers stay
  * distinguishable and repeat callers stay correlatable, while the secret itself is never written down — the log must

package/dist/src/cdc/poll.js

@@ -56,11 +56,11 @@ export function xminBeforeHolds(current, watermark) {
     return current >= watermark && current - watermark < 2n ** 30n;
 }
 /**
- * The wait before the next poll: MASON_POLL_MS, or four times what the last poll took when that is longer, so a
- * source whose tables take a while to read spends at most a fifth of its time on polls. Never sooner than either
- * (the test server: a cap of a minute polled a 22 M-row production table every 74 s for 6.5 hours under
- * MASON_POLL_MS=3600000, and a poll of 20 s every 60 s is a third of the source's time): the database's load decides,
- * and a slow poll's freshness is said by its own timing line.
+ * The wait before the next poll: the table's interval (its sync:, src/lib/table-sync.ts), or four times what the last
+ * poll took when that is longer, so a table that takes a while to read costs at most a fifth of the source's time.
+ * Never sooner than either (the test server: a cap of a minute polled a 22 M-row production table every 74 s for 6.5
+ * hours under an hourly interval, and a poll of 20 s every 60 s is a third of the source's time): the database's load
+ * decides, and a slow poll's freshness is said by its own timing line.
  */
 export function nextPollDelayMs(pollMs, lastPollMs) {
     return Math.max(pollMs, 4 * lastPollMs);

package/dist/src/cli/background.js

@@ -17,26 +17,34 @@ import * as path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { runnable } from "../lib/runnable.js";
+import { LogReader, logPath } from "../lib/log-read.js";
 import { READY, STEP_MARK } from "./dev.js";
 import { liveRun } from "./runs.js";
-import { projectSource, theProject } from "./project.js";
+import { projectSource, startSettingRefusal, theProject } from "./project.js";
 import { runListenerSettings } from "./pg-tls.js";
 import { demoChangesRefusal, demoPort } from "./demo.js";
+import { recordRefusal } from "./replication-mode.js";
+import { shownPath } from "./sources.js";
 import { endText, failed, jsonText, nextBlock } from "./command.js";
+import { historyDaysSetting } from "../duck/history.js";
+import { memoryProblems } from "../duck/store.js";
 import { DEV } from "./registry.js";
+import { UI } from "./ui.js";
 import { out as styleOut, stepRenderer } from "./style.js";
 import { postgresLink, withoutPlaceholders } from "./pg-url.js";
 const say = (m) => { process.stdout.write(`${m}\n`); };
-const MAIN = path.join(path.dirname(fileURLToPath(import.meta.url)), "main.ts");
+const MAIN = path.join(path.dirname(fileURLToPath(import.meta.url)), "mason.cjs");
 const SUPERVISE = path.join(path.dirname(fileURLToPath(import.meta.url)), "supervise.ts");
 /** The commands to run next, as `mason start` prints them once the run is up: one a line, what each does beside it
  *  (not `mason status | mason logs | mason stop` on one line). */
 export const NEXT_STEPS = [
+    // the web page first: a first-time user's most useful next step (the run serves it; mason ui opens it, signed in)
+    ["mason ui", UI.summary],
     ["mason tables", "the database's tables, and what you can add"],
-    ["mason add <table>", "copy a table into Mason"],
+    ["mason add <table>", "sync a table into Mason"],
     ["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"],
     ["mason status", "what Mason is doing"],
-    ["mason logs", "its log: every copy, poll and statement"],
+    ["mason logs", "its log: every sync, poll and statement"],
     ["mason stop", "stop Mason; the next mason start resumes where it stopped"],
 ];
 /** The ports a demo project's database takes (its URL's port, read as the run reads it), for the API's choice to avoid;
@@ -68,10 +76,32 @@ export async function devInBackground(args, o) {
         say(nextBlock([["mason status", "what it is doing"], ["mason stop", "stop it"]]));
         return 0;
     }
-    // a demo project with --replication (src/cli/demo.ts): refused here too, where it is read, before a run is spawned
-    const demoRefused = demoChangesRefusal(t.project.config, o.changes ?? null);
+    // a demo project whose sources file says sync: replication (src/cli/demo.ts): refused here too, where it is read,
+    // before a run is spawned — the sources file as the run reads it (a file it cannot read is the run's to say, in its checklist)
+    const src = projectSource(t.project);
+    const file = "message" in src ? null : src;
+    const shown = file === null ? "" : shownPath(t.project.root, file.file);
+    const demoRefused = demoChangesRefusal(t.project.config, file, shown);
     if (demoRefused)
         return failed("start", demoRefused, { json: o.json });
+    // a setting a start refuses, here where the person (or --json) reads it, by the run's own list (src/cli/project.ts)
+    const setting = startSettingRefusal(t.project, process.env, { serve: false });
+    if (setting !== null)
+        return failed("start", setting, { json: o.json });
+    // the history's days (MASON_HISTORY_DAYS, a number of days; the old MASON_REQUEST_LOG_DAYS refused), by the run's own
+    // check (src/duck/history.ts), refused here as in the run
+    const days = historyDaysSetting(process.env);
+    if (typeof days !== "number")
+        return failed("start", { code: "refused", ...days }, { json: o.json });
+    // MASON_DUCKDB_MEMORY not an amount (src/duck/store.ts memoryProblems), by the run's own check, refused here as in the
+    // run, before anything is spawned or opened; a size under the floor only warns, in the run (memoryWarning)
+    const memory = memoryProblems(process.env)[0];
+    if (memory !== undefined)
+        return failed("start", { code: "refused", ...memory }, { json: o.json });
+    // what the config records and the file does not say (src/cli/replication-mode.ts), in the run's order: settings first
+    const unsaid = file === null ? null : recordRefusal(t.project.config, file, process.env, shown, "mason start");
+    if (unsaid !== null)
+        return failed("start", unsaid, { json: o.json });
     // a MASON_PG_PORT that is no port, or is held, is refused HERE, where the person (or --json) reads it, before a run is
     // spawned; the run checks again for itself (choosePgPort, src/cli/ports.ts), since a port may be taken in between.
     // A demo project's database port (its URL's, src/cli/demo.ts demoPort) is avoided as the run avoids it
@@ -84,12 +114,13 @@ export async function devInBackground(args, o) {
         return failed("start", listen, { json: o.json });
     fs.mkdirSync(home, { recursive: true, mode: 0o700 });
     // the run's terminal: its setup URL carries the run's token and it prints the API key, so only the developer reads it
-    const logFile = path.join(home, "dev.log");
+    const logFile = logPath(home, "start");
     const fd = fs.openSync(logFile, "a", 0o600);
     fs.chmodSync(logFile, 0o600);
     const from = fs.fstatSync(fd).size;
     fs.writeSync(fd, `\n--- mason start ${new Date().toISOString()} ---\n`);
-    // the run is started IN the project's root, so it finds the same project
+    // the run is started IN the project's root, so it finds the same project. Its env carries the size this process
+    // set (src/cli/pool-size.cjs), and the supervisor between them inherits it too: it never uses that many
     const run = [process.execPath, runnable(MAIN), "start", ...args.filter((a) => a !== "--json"), "--attach"];
     const child = spawn(process.execPath, [runnable(SUPERVISE), home, logFile, ...run], { detached: true, stdio: ["ignore", fd, fd], cwd: t.project.root, env: process.env });
     fs.closeSync(fd);
@@ -106,25 +137,15 @@ export async function devInBackground(args, o) {
     line(st.bold(`Starting Mason for ${t.project.config.name}`));
     const steps = stepRenderer({ line, live: !o.json && process.stdout.isTTY ? { write: (x) => { process.stdout.write(x); } } : null, style: st });
     let begun = false;
-    let offset = from;
-    let partial = "";
+    // the run's terminal from this start on, through the one reader: a line is had whole, masked (src/lib/log-read.ts)
+    const reader = new LogReader(logFile, { from });
     let postgres = null;
     const since = []; // the run's lines after its last step: a failure's reasons
     try {
         for (;;) {
-            const size = fs.statSync(logFile).size;
-            if (size > offset) {
-                const buf = Buffer.alloc(size - offset);
-                const r = fs.openSync(logFile, "r");
-                try {
-                    fs.readSync(r, buf, 0, buf.length, offset);
-                }
-                finally {
-                    fs.closeSync(r);
-                }
-                offset = size;
-                const lines = (partial + buf.toString()).split("\n");
-                partial = lines.pop() ?? "";
+            for (let text = reader.read(); text !== null; text = reader.read()) {
+                const lines = text.split("\n");
+                lines.pop(); // every line read ends in its newline
                 for (const l of lines) {
                     if (l.startsWith("--- mason start "))
                         continue;
@@ -166,7 +187,7 @@ export async function devInBackground(args, o) {
                         continue;
                     }
                     if (/^\s+Web UI\s+mason ui\b/.test(l)) {
-                        steps.print(`  ${st.dim("Web UI".padEnd("Postgres API".length))}  ${st.cyan("mason ui")}  ${st.dim("(the status page and the users, in your browser)")}`);
+                        steps.print(`  ${st.dim("Web UI".padEnd("Postgres API".length))}  ${st.cyan("mason ui")}  ${st.dim(`(${UI.summary})`)}`);
                         continue;
                     }
                     // a demo project's line (src/cli/dev.ts: "Demo  a new order lands every <n> s: …"), in the same column
@@ -183,7 +204,8 @@ export async function devInBackground(args, o) {
             if (exited !== null) {
                 if (steps.open() !== null)
                     steps.fail();
-                if (partial)
+                const partial = reader.rest(); // the line it was writing, unended
+                if (partial.trim())
                     since.push(partial.trim());
                 // the run's own last words are the reason (a wrong password), already shown line by line to a person
                 return failed("start", { message: `the run stopped before it was ready (exit ${exited})`, code: "failed", why: o.json && since.length ? since.join("\n") : undefined,

package/dist/src/cli/bridge-stdin.js

@@ -0,0 +1,101 @@
+/**
+ * THE BRIDGE'S STDIN, READ ON A THREAD OF ITS OWN, AND ITS WATCHDOG (src/cli/ui-ssh.ts `bridge`, `StdinByWorker`).
+ *
+ * `mason ui --bridge` ends when its stdin ends: the laptop's ssh gone. Heard on the main thread, that end waits on the
+ * main event loop, and a loop that is blocked (a synchronous call that never returns, a hung native call, a busy loop)
+ * never hears it: the process would live on, holding the run's tunnel, with nobody left who can end it. So this thread
+ * owns fd 0, on an event loop of its own (Node's docs, worker_threads: "each Worker has its own event loop"), forwards
+ * its bytes to the main thread, and on its end arms a timer here; if the process is still alive when it fires, the main
+ * thread did not end it, so this one does, by SIGKILL to the process (`process.kill`, which a worker may call: a signal
+ * is delivered by the system, not by a loop, and SIGKILL cannot be caught or delayed by anything the process runs).
+ *
+ * THE FLOW CONTROL IS THIS THREAD'S, BY CREDIT: it hands the main thread at most `windowBytes` it has not acknowledged
+ * (`ack`: consumed, and FrameLink not paused), and stops reading at that bound (`stream.pause()`, so the pipe fills
+ * and the laptop's writes wait, as they did on `process.stdin`). Nothing is read into memory past it, whatever the main
+ * thread does. A stopped reader cannot hear stdin's end, so the main thread says it is alive (`beat`, every
+ * `BEAT_MS`): a main thread that is only waiting (on the run's page taking what was sent) keeps beating and the reader
+ * waits with it; one silent for `exitMs` with the window full is STUCK, and this thread then reads on and DROPS what it
+ * reads, so that the end is heard and the watchdog can fire. The stream it fed is then broken, which the main thread is
+ * told (`dropped`): if it ever runs again it ends the bridge, exit 1, never reads past the hole.
+ *
+ * fd 0 is opened as Node opens `process.stdin` for its kind (Node's docs, process.stdin, net.Socket `fd`, tty.ReadStream,
+ * fs.createReadStream `fd`): a pipe or a socket (ssh's, `docker exec -i`'s) as a `net.Socket`, a terminal (`ssh -t`) as a
+ * `tty.ReadStream`, anything else (a file, /dev/null) as a file stream, which always reaches its end. A read error is an
+ * end too (a terminal hung up reads EIO). A stdin that cannot be opened at all is said, and ends the bridge.
+ */
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as tty from "node:tty";
+import { parentPort, workerData } from "node:worker_threads";
+const { exitMs, windowBytes } = workerData;
+if (parentPort === null)
+    throw new Error("src/cli/bridge-stdin.ts is a worker thread's script, started by src/cli/ui-ssh.ts");
+const port = parentPort;
+let over = false;
+/** Bytes handed to the main thread that it has not acknowledged. */
+let owed = 0;
+let lastHeard = Date.now();
+let dropping = false;
+/** The end, once: said to the main thread, then the watchdog armed. */
+function finish(why, failed = false) {
+    if (over)
+        return;
+    over = true;
+    port.postMessage({ end: why, failed });
+    setTimeout(() => {
+        try {
+            fs.writeSync(2, `mason ui --bridge: its stdin closed ${exitMs / 1000} s ago and it had not ended (its main thread is blocked): ended now, and the tunnel with it\n`);
+        }
+        catch (e) {
+            void e; /* stderr gone too, as the laptop's ssh is: the kill below is what ends the process */
+        }
+        process.kill(process.pid, "SIGKILL");
+    }, exitMs);
+}
+function open() {
+    if (tty.isatty(0))
+        return new tty.ReadStream(0);
+    const kind = fs.fstatSync(0);
+    if (kind.isFIFO() || kind.isSocket())
+        return new net.Socket({ fd: 0, readable: true, writable: false });
+    return fs.createReadStream("", { fd: 0, autoClose: false });
+}
+let input = null;
+try {
+    input = open();
+}
+catch (e) {
+    finish(`its stdin cannot be read: ${e.message}`, true);
+}
+if (input !== null) {
+    const stream = input;
+    stream.on("data", (b) => {
+        if (dropping)
+            return;
+        const copy = Uint8Array.from(b);
+        port.postMessage({ data: copy }, [copy.buffer]);
+        owed += b.length;
+        if (owed >= windowBytes)
+            stream.pause();
+    });
+    stream.once("end", () => { finish(null); });
+    stream.once("error", (e) => { finish(`its stdin: ${e.message}`); });
+    stream.once("close", () => { finish(null); });
+    port.on("message", (m) => {
+        lastHeard = Date.now();
+        if (!("ack" in m) || dropping)
+            return;
+        owed -= m.ack;
+        if (owed < windowBytes && stream.isPaused())
+            stream.resume();
+    });
+    // a main thread silent for the bound while the window is full is stuck: read on, dropping, so the end is heard
+    const look = setInterval(() => {
+        if (dropping || over || owed < windowBytes || Date.now() - lastHeard < exitMs)
+            return;
+        dropping = true;
+        clearInterval(look);
+        port.postMessage({ dropped: owed });
+        stream.resume();
+    }, Math.min(250, exitMs));
+}

package/dist/src/cli/cancel.js

@@ -0,0 +1,75 @@
+/**
+ * `mason cancel <session>`: stops the statement a session of the Postgres API is running, exactly as a client's own
+ * cancel (the protocol's CancelRequest) stops it — the listener's one path (src/api/postgres/server.ts `interrupt`),
+ * through the run's `POST /api/cancel` (src/cli/run-server.ts). The client is told 57014 "canceling statement due to
+ * user request", and the request log records it as cancelled. `mason logs --running` lists the sessions.
+ */
+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 { guarded, oneLine, runFailure, spanText } from "./commands.js";
+const out = (m) => { process.stdout.write(`${m}\n`); };
+export const CANCEL_USAGE = `usage: mason cancel <session> [--statement <n>] [--json]
+
+  Stops the statement a session of the Postgres API is running now, as the client's own cancel would: the client is
+  told "canceling statement due to user request" (SQLSTATE 57014), its session stays open, and the request log keeps
+  the statement as cancelled. mason logs --running lists the statements running now, with their sessions and numbers.
+
+    mason logs --running
+    mason cancel 12 --statement 340
+    mason cancel 12
+
+  --statement <n>   only that statement (its number in mason logs --running): if it ended and the session runs
+                    another, nothing is cancelled and the answer says so. Without it, whatever the session runs now
+                    is stopped, as a client's own cancel stops it.
+  --json            as data: { cancelled: { session, statement, user, applicationName, method, startedAt, runningMs,
+                    rows, query, queryTruncated } (the statement it stopped), next }
+`;
+export const CANCEL = {
+    needs: "run",
+    name: "cancel",
+    summary: "stop the statement a session of the Postgres API is running, as the client's cancel would: mason cancel 12",
+    usage: CANCEL_USAGE,
+    options: { statement: { type: "string" }, json: { type: "boolean" } },
+    json: ["cancelled", "next"],
+};
+export async function cancel(argv) {
+    const f = parseCommand(CANCEL, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    const running = ["mason logs --running", "the statements running now, with their sessions"];
+    if (f.positionals.length !== 1 || !/^[1-9]\d*$/.test(f.positionals[0])) {
+        return failed("cancel", { message: f.positionals.length === 0 ? "name the session: mason cancel <session>" : `${f.positionals.join(" ")} is not a session's number`,
+            code: "usage", fix: "mason logs --running lists each statement running with its session", next: [running], usage: CANCEL_USAGE }, { json });
+    }
+    const session = Number(f.positionals[0]);
+    const statement = f.values.statement;
+    if (statement !== undefined && (typeof statement !== "string" || !/^[1-9]\d*$/.test(statement))) {
+        return failed("cancel", { message: `--statement ${String(statement)} is not a statement's number`, code: "usage",
+            fix: "mason logs --running lists each statement running with its number", next: [running], usage: CANCEL_USAGE }, { json });
+    }
+    const w = await reach(CANCEL, json);
+    if (w === null || !("run" in w))
+        return 1;
+    const run = w.run;
+    return guarded("cancel", json, async () => {
+        const r = await callRun(run, "POST", "/api/cancel", { session, ...(statement !== undefined ? { statement: Number(statement) } : {}) });
+        if (r.status !== 200)
+            return failed("cancel", runFailure(r, [running]), { json });
+        const c = r.body.cancelled;
+        const next = [[`mason logs --requests --outcome cancelled -n 5`, "the statements cancelled, this one among them once it ended"], running];
+        if (json) {
+            out(jsonText(CANCEL, { cancelled: c }, next));
+            return 0;
+        }
+        out(reportText({
+            headline: `Cancelled session ${c.session}'s statement: it ends now, and its client gets a "canceling statement" error.`,
+            details: [["Statement", oneLine(c.query) || "(no statement)"], ["Client", `${c.applicationName || "(no application_name)"}${c.user ? ` (user ${c.user})` : ""}`],
+                ["Running", `${spanText(c.runningMs / 1000)}, ${c.rows.toLocaleString("en-US")} row${c.rows === 1 ? "" : "s"} sent`]],
+            next,
+        }, styleOut()));
+        return 0;
+    });
+}