@mason-data/cli 0.0.0-stage → 0.6.2

package/dist/src/cli/replication-mode.js

@@ -0,0 +1,148 @@
+/**
+ * `mason start --replication` (the journey to production, item 6): a project's run reading its database's
+ * change log as production does — a publication, a replication slot, `wal_level = logical` — instead of polling it with
+ * SELECTs (src/cdc/poll.ts). A developer then meets the setup production needs on their own database first. The mode is
+ * the project's (`.mason/config.json` `changes`), kept between starts until `--poll` takes it back.
+ *
+ * What it costs the developer's database, said where it happens: Mason creates its slot there (`mason_<deployment>`), and
+ * a slot holds WAL while nobody reads it — so `mason stop` says so, and `mason destroy`, or going back to polling, drops
+ * it (`dropOwnReplication`), verified gone, by the name the start that made it RECORDED (`madeReplication`), never one
+ * computed again. The PUBLICATION is Mason's own (`mason_<deployment>`, made and dropped with
+ * the slot) unless the operator names one (`--publication <name>`, else `PG_PUBLICATION`, else the one
+ * an earlier start recorded): that one is the database owner's, read as it is and never created, altered or dropped
+ * (src/duck/publication.ts) — on a read replica it is the only way, since CREATE PUBLICATION is refused on a standby.
+ *
+ * In the ClickHouse service this was cut from, the two modes kept row versions that could not continue each other (a
+ * counter per table against WAL positions): a switch was a copy from scratch, which that service did by itself. The DuckDB
+ * prototype keeps its copies through a switch: each table is caught up by one poll from its watermark (src/duck/sync.ts
+ * `prepareReplication`), and `mason start` says so.
+ */
+import { createHash } from "node:crypto";
+import { replicationNames } from "../cdc/source.js";
+import { connectSource, systemIdentifier } from "./preflight.js";
+import { readServerFacts, readSlotFacts, replicationChecks } from "./replication-checks.js";
+/** Postgres's longest identifier (NAMEDATALEN - 1): a longer slot name is refused, a longer publication's cut with a notice. */
+export const PG_NAME_BYTES = 63;
+/**
+ * THE NAME A SOURCE'S SLOT AND PUBLICATION ARE MADE FROM, `dev_<project>_<source>` (src/cdc/source.ts replicationNames
+ * puts `mason_` before it): one per project AND source, the source the sources file's name, since a project will sync
+ * several databases, each with a slot of its own. Lower case, `_` for any other character, as a slot's name must be. A
+ * project (48 at most) and a source (48) can pass Postgres's 63 bytes: then a readable prefix and `_` and 8 hex
+ * characters of the whole name's sha256, so two names sharing a long prefix never meet and none is ever cut silently.
+ */
+export function deploymentOf(project, source) {
+    const full = `dev_${project}_${source}`.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+    const room = PG_NAME_BYTES - "mason_".length;
+    if (full.length <= room)
+        return full;
+    return `${full.slice(0, room - 9)}_${createHash("sha256").update(full).digest("hex").slice(0, 8)}`;
+}
+/**
+ * The publication and slot a project's run reads: the publication `named` (the flag, `PG_PUBLICATION` or the recorded
+ * one: `namedPublication`), else Mason's own — by the change reader's own rule (src/cdc/source.ts `replicationNames`),
+ * which also says whether it is Mason's to make. The slot is always the project's own.
+ */
+export function projectReplication(name, source, named = null) {
+    const { publication, slot, owned } = replicationNames(named ? { PG_PUBLICATION: named } : {}, deploymentOf(name, source));
+    return { publication, slot, owned };
+}
+/**
+ * WHAT REPLICATION MODE MADE ON THE DATABASE, as the start that made it recorded it (`config.json` `replication`): what
+ * `--poll` and `mason destroy` drop. Recorded, never computed again, so a name that changes since — the sources file
+ * renamed, the naming rule — never leaves a slot that nobody drops, holding the database's WAL for ever. A project with
+ * no record (none started in replication mode since it was kept) has the names the rule gives now.
+ */
+export function madeReplication(cfg, source) {
+    return cfg.replication ?? projectReplication(cfg.name, source, cfg.publication ?? null);
+}
+/** The publication an operator named, and where: `--publication`, else `PG_PUBLICATION`, else the one an earlier start
+ *  of this copy recorded (`config.json` `publication`), else none (Mason's own). */
+export function namedPublication(flag, env, recorded) {
+    if (flag)
+        return { name: flag, from: "flag" };
+    if (env.PG_PUBLICATION)
+        return { name: env.PG_PUBLICATION, from: "env" };
+    if (recorded)
+        return { name: recorded, from: "recorded" };
+    return null;
+}
+/** The mode a start runs: the flag, else the project's, else polling. */
+export function changesOf(flag, recorded) {
+    return flag ?? recorded ?? "poll";
+}
+/**
+ * Whether the developer's database can be read by replication: what refuses it (wal_level, the role — REPLICATION, a
+ * superuser, or RDS's rds_replication membership, as `replicationChecks` reads them — a free slot and WAL sender, a
+ * standby before 16, and a standby with no publication named: Mason cannot make its own there), and what is only worth
+ * saying (the WAL cap), from the production checks' own rules.
+ */
+export function readinessVerdict(facts, slot, slotFacts, repl) {
+    const checks = replicationChecks(facts, slot, slotFacts);
+    // a standby takes no CREATE PUBLICATION (it is read-only): the publication must be the primary's, named
+    if (facts.standby && repl.owned) {
+        checks.push({ name: "publication", ok: false, detail: `this database is a read replica, where Mason cannot make its publication ${repl.publication} (CREATE ` +
+                "PUBLICATION is refused on a standby). Create one on the primary for the tables you add, then name it: mason start --replication --publication <name>" });
+    }
+    // a laptop's database has no cap on its slots by default: worth saying, never a reason to refuse a dev run
+    return { refused: checks.filter((x) => x.ok === false && x.name !== "WAL cap"), warnings: checks.filter((x) => (x.name === "WAL cap" && x.ok === false) || x.warn === true) };
+}
+export async function replicationReadiness(source, repl) {
+    const c = await connectSource(source);
+    if ("failure" in c)
+        return { failure: c.failure.message };
+    try {
+        return readinessVerdict(await readServerFacts(c.pg), repl.slot, await readSlotFacts(c.pg, repl.slot), repl);
+    }
+    finally {
+        c.pg.close();
+    }
+}
+/** The statements that remove what replication mode made, for a person to run when Mason could not: the slot, and the
+ *  publication only when it is Mason's own (a named one is its owner's). */
+export function dropStatements(o) {
+    return `SELECT pg_drop_replication_slot('${o.slot}') FROM pg_replication_slots WHERE slot_name = '${o.slot}' AND NOT active;` +
+        (o.owned ? ` DROP PUBLICATION IF EXISTS ${o.publication};` : "");
+}
+/**
+ * Drop what replication mode made on the developer's database — the slot, and the publication when it is Mason's own,
+ * never one the operator named — and verify it is gone: what was dropped, in words. A slot a reader still holds is never
+ * dropped (the run must be stopped first): that is a failure.
+ */
+export async function dropOwnReplication(source, o, from = null) {
+    const c = await connectSource(source);
+    if ("failure" in c)
+        throw new Error(`could not connect to drop them: ${c.failure.message}`);
+    const pg = c.pg;
+    const lit = (s) => `'${s.replace(/'/g, "''")}'`;
+    try {
+        // the server the copy came from (its system identifier, recorded at the copy): another one has none of its slot
+        if (from?.systemIdentifier) {
+            const now = await systemIdentifier(pg);
+            if (now !== null && now !== from.systemIdentifier) {
+                throw new Error(`${source.database} on ${source.host} is another server than the copy came from (system identifier ${now}, the copy's ${from.systemIdentifier}), where the slot is: put that server's URL back in the sources file and run mason destroy again, or drop them there by hand`);
+            }
+        }
+        const dropped = [];
+        const slot = await readSlotFacts(pg, o.slot);
+        if (slot) {
+            if (slot.active)
+                throw new Error(`replication slot ${o.slot} is in use by a reader: stop it first`);
+            await pg.query(`SELECT pg_drop_replication_slot(${lit(o.slot)})`);
+            dropped.push(`replication slot ${o.slot}`);
+        }
+        const hasPub = async () => (await pg.query(`SELECT 1 FROM pg_publication WHERE pubname = ${lit(o.publication)}`)).rows.length > 0;
+        if (o.owned && await hasPub()) {
+            await pg.query(`DROP PUBLICATION IF EXISTS "${o.publication.replace(/"/g, '""')}"`);
+            dropped.push(`publication ${o.publication}`);
+        }
+        // verified, never assumed: a slot left behind holds the database's WAL for ever
+        if (await readSlotFacts(pg, o.slot))
+            throw new Error(`replication slot ${o.slot} is still there after pg_drop_replication_slot`);
+        if (o.owned && await hasPub())
+            throw new Error(`publication ${o.publication} is still there after DROP PUBLICATION`);
+        return dropped;
+    }
+    finally {
+        pg.close();
+    }
+}

package/dist/src/cli/run-server.js

@@ -0,0 +1,388 @@
+/**
+ * THE RUN'S COMMAND SERVER (`mason start`; a server for the `mason` command alone, the CLI's UI part dropped
+ * completely). `mason tables`, `mason add`, `mason status`, `mason wait`, `mason sync` and
+ * `mason logs --requests` ask it (src/cli/control.ts): it reads the database's catalog, writes the tables added and
+ * removed into the project's sources file (src/cli/sources.ts) — the sync, told of the change, starts copying a table at
+ * once — and says where everything is.
+ *
+ * Every request passes the run's guard (src/cli/security.ts): loopback, the Host header, and the run's token, which
+ * the commands send as `Authorization: Bearer` from the run's settings file.
+ *
+ * What it knows it reads where the run keeps it: the copies from the sync (src/duck/sync.ts), the statements from the
+ * request log (src/duck/requests.ts). Added is a fact about the project's files: a table is added when its sources file
+ * names it.
+ *
+ * THE WEB PAGE (src/web/, `mason ui`, docs/WEB-UI.md): under `mason start` it also serves one page and its two files,
+ * from an allowlist read when it starts (`pageFiles`), and the users the page manages (`/api/users`, the functions
+ * `mason user` calls). The page reads the same JSON the commands read; a refusal carries `failure`, the CLI's Failure
+ * shape (message, why, fix, next), so the page says it as the command would. `mason serve`'s run serves no page.
+ */
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readBody, sendJson } from "../lib/http-json.js";
+import { projectFingerprint } from "../lib/project-files.js";
+import { guard, SECURITY_HEADERS } from "./security.js";
+import { maskedUrl } from "./preflight.js";
+import { errorJson, nextJson } from "./command.js";
+import { readiness } from "./readiness.js";
+import { addedNext, addUser, listUsers, removeUser, REMOVED_NEXT } from "./user.js";
+import { postgresLink } from "./pg-url.js";
+import { addedTables, catalogTable, chooseColumns, entryName, entryProblems, findEntry, parseSourceText, shownPath, sourceFailure, sourceFileNames, sourcesDir, unaddableReason, withoutTable, withTable } from "./sources.js";
+import { PollRefused } from "../duck/sync.js";
+/** A statement answered in this many milliseconds or more is slow: what mason status lists (src/duck/requests.ts slow). */
+export const SLOW_MS = 1000;
+/**
+ * The run's state, in the shape mason status / wait read (`RunState`, src/cli/commands.ts): each table of the database,
+ * added or not, and each added one's copy as the sync has it, so `mason wait` is ready exactly when every added table is
+ * copied.
+ */
+export function runState(ctx, copies, stream) {
+    const folder = ctx.folder();
+    const sources = ctx.sources();
+    const by = new Map(copies.map((c) => [c.source, c]));
+    const project = folder && fs.existsSync(folder) ? projectFingerprint(folder) : null;
+    const facts = ctx.facts();
+    const tables = facts.tables.map((t) => {
+        const c = by.get(t.source);
+        return {
+            ...catalogTable(t, sources.file?.tables.find((e) => e.table === t.source)),
+            // a table the sync has not reached is waiting for its copy (no copy yet), never "copying 0"
+            // a copy in a retired layout (src/duck/sync.ts RETIRED_LAYOUT) serves until it is copied again: done, and said
+            copy: c && c.phase !== "waiting" ? { phase: (c.phase === "copied" ? "done" : c.phase === "failed" ? "failed" : "copying"),
+                rowsCopied: c.phase === "copied" ? c.rows ?? 0 : c.rowsSoFar ?? 0, updatedAt: c.copiedAt ?? "",
+                // while its chunks are read: the chunks done and reading, the measured rate, the time left (src/duck/sync.ts
+                // copyProgressNow), so mason wait and status move between two commits
+                ...(c.phase === "copying" && c.progress !== undefined ? { progress: c.progress } : {}),
+                ...(c.phase === "copied" && c.retired !== undefined ? { retired: c.retired } : {}) } : null,
+            error: c?.phase === "failed" ? c.error : null,
+            // copied and served, but not kept current by the poll (src/duck/sync.ts POLL_ROW_LIMIT): mason status and wait say so
+            ...(c?.unsynced ? { unsynced: c.unsynced } : {}),
+            ...(c ? { duck: { rows: c.rows, bytes: c.bytes, seconds: c.seconds, copiedAt: c.copiedAt, error: c.error } } : {}),
+        };
+    });
+    return {
+        // what mason wait waits on and mason status prints last (src/cli/readiness.ts): said by the run, so the page and the
+        // commands say one thing
+        readiness: readiness({ tables }),
+        // the run serves the web page (mason ui): mason status prints its URL
+        ui: ctx.page,
+        source: { url: maskedUrl(ctx.source.url), host: ctx.source.host, database: ctx.source.database, remote: ctx.source.remote,
+            version: facts.versionText, standby: facts.standby, changes: ctx.changes, name: sources.file?.name ?? null, file: sources.file?.file ?? null,
+            ...(ctx.publication ? { replication: { slot: ctx.slot, publication: ctx.publication.name, owned: ctx.publication.owned } } : {}) },
+        // a sources file edited into a mistake while the run is up: the run copies what it read last, and says so
+        warnings: [...ctx.warnings, ...(sources.problem ? [`${sources.problem} (Mason copies the tables it read before; mason start reads the file again)`] : [])],
+        folder, project, tables,
+        engine: { name: "duckdb", file: ctx.duck.file, bytes: fileBytes(ctx.duck.file), pollSeconds: ctx.duck.pollSeconds },
+        jsonPaths: ctx.duck.jsonPaths?.() ?? [],
+        // replication mode: where the stream is, its lag and what it applied (mason status and wait render it, streamLines)
+        ...(stream !== null ? { stream } : {}),
+    };
+}
+/** a file's size, or null where it cannot be read (the run's own DuckDB file: it exists while the run does) */
+function fileBytes(file) {
+    try {
+        return fs.statSync(file).size;
+    }
+    catch {
+        return null;
+    } // a size is a nicety of mason status: unknown, not an error
+}
+async function state(ctx) {
+    return runState(ctx, ctx.duck.copies(), await ctx.duck.stream());
+}
+/** The sources file as it is on disk now, its text and what it says — or why the command server cannot edit it. */
+function sourceOnDisk(ctx) {
+    const folder = ctx.folder();
+    if (!folder)
+        throw new Refusal(409, "choose the project's folder first");
+    const names = sourceFileNames(folder);
+    if (names.length !== 1)
+        throw new Refusal(409, `${path.relative(ctx.root, sourcesDir(folder)) || sourcesDir(folder)}/ has ${names.length ? `${names.length} source files` : "no source file"}: one source per project for now`);
+    const file = path.join(sourcesDir(folder), names[0]);
+    const text = fs.readFileSync(file, "utf8");
+    const parsed = parseSourceText(text, names[0].replace(/\.ya?ml$/, ""), file);
+    if ("problems" in parsed) {
+        const f = sourceFailure(file, ctx.root, parsed.problems);
+        throw new Refusal(409, `${f.message}${f.why ? `\n${f.why}` : ""} — fix it first`);
+    }
+    // the database the file names NOW must be the one this run copies: its catalog is what an edit is checked against
+    const read = ctx.readSource();
+    if ("message" in read)
+        throw new Refusal(409, `${read.message}${read.why ? `\n${read.why}` : ""} — fix it first`);
+    if (read.resolved !== ctx.runUrl) {
+        throw new Refusal(409, `${shownPath(ctx.root, file)}: url: now names ${maskedUrl(read.resolved)} (${read.from}), and this run copies ${maskedUrl(ctx.runUrl)}: ` +
+            "mason stop && mason start copies from the new one, then add or remove the table");
+    }
+    return { file, text, parsed };
+}
+/** The file's other entries against the database: an edit is never written over a file the run would not take. */
+function othersHold(ctx, parsed, without, then) {
+    const others = { ...parsed, tables: parsed.tables.filter((e) => !without.includes(e.table)) };
+    const held = addedTables(others, ctx.facts().tables, ctx.source.database, ctx.root, { replication: ctx.changes === "replication" });
+    if (!Array.isArray(held))
+        throw new Refusal(409, `${held.message}${held.why ? `\n${held.why}` : ""} — fix it first, then ${then}`);
+}
+/**
+ * ADD A TABLE: its entry in the sources file, written — after the last one, or in place of the table's own (`withTable`):
+ * every other byte of the file as it was. `columns` are the ones asked (`["*"]`: every one); `key` the columns a table
+ * with no primary key is copied by. The file's other entries must hold against the database first: an edit is never
+ * written over a file the next start would refuse.
+ */
+export async function pick(ctx, table, columns = ["*"], key = null) {
+    const { file, text, parsed } = sourceOnDisk(ctx);
+    const facts = ctx.facts();
+    const t = facts.tables.find((x) => x.source === table);
+    if (!t)
+        throw new Refusal(404, `${table} is not a table of ${ctx.source.database} that this user can read`);
+    if (key !== null && t.key.length)
+        throw new Refusal(400, `${table} has a primary key (${t.key.join(", ")}), which Mason copies it by: leave --key out`);
+    if (key === null && !t.key.length)
+        throw new Refusal(409, `${table} cannot be added: ${unaddableReason(t)}`);
+    if (key !== null && ctx.changes === "replication")
+        throw new Refusal(409, `${table} has no primary key, and logical replication cannot apply its changes by --key: copy it by polling (mason start --poll), then add it`);
+    const chosen = chooseColumns(t, columns, key);
+    if ("problem" in chosen)
+        throw new Refusal(400, chosen.problem);
+    othersHold(ctx, parsed, [table], `add ${entryName(table)}`);
+    const was = parsed.tables.find((e) => e.table === table);
+    const entry = { name: was?.name ?? entryName(table), table, columns: chosen.columns, exclude: chosen.exclude, key: key === null ? null : [...key] };
+    // the entry itself, as the run will read it: a --key that does not tell the rows apart is refused here, not at the copy
+    const own = entryProblems(t, entry, facts.tables, ctx.source.database, { replication: ctx.changes === "replication" });
+    if (own.length)
+        throw new Refusal(400, own.join("; "));
+    const same = was !== undefined && JSON.stringify([was.columns, was.exclude, was.key]) === JSON.stringify([entry.columns, entry.exclude, entry.key]);
+    if (!same) {
+        const r = withTable(text, entry);
+        if ("problem" in r)
+            throw new Refusal(409, `${path.relative(ctx.root, file)} cannot be edited: ${r.problem}`);
+        fs.writeFileSync(file, r.text);
+    }
+    return { table, file, entry: entry.name, columns: entry.columns, exclude: entry.exclude, key: entry.key, addedKey: chosen.addedKey, skippedSecrets: chosen.skipped, already: same };
+}
+/**
+ * REMOVE TABLES from the sources file: each one's entry cut (`withoutTable`), every other byte of the file as it was; the
+ * run then drops its copy. A name the file does not have is refused with the closest one it has.
+ */
+export async function removeTables(ctx, names) {
+    const { file, text, parsed } = sourceOnDisk(ctx);
+    const entries = names.map((n) => {
+        const e = findEntry(parsed, n);
+        if ("problem" in e)
+            throw new Refusal(e.usage ? 400 : 404, e.problem);
+        return e;
+    });
+    // what stays must hold: else the run's re-read refuses the file, keeps the removed table and goes on copying it
+    othersHold(ctx, parsed, entries.map((e) => e.table), `remove ${names.join(" ")}`);
+    let out = text;
+    for (const e of entries) {
+        const r = withoutTable(out, e.table);
+        if (r === null)
+            continue;
+        if ("problem" in r)
+            throw new Refusal(409, `${path.relative(ctx.root, file)} cannot be edited: ${r.problem}`);
+        out = r.text;
+    }
+    fs.writeFileSync(file, out);
+    return { removed: [...new Set(entries.map((e) => e.table))], file };
+}
+/** A refusal the command shows as it is; `failure` is how the web page says it (the CLI's Failure: why, fix, next), by
+ *  default the message alone under the status's code. */
+export class Refusal extends Error {
+    status;
+    failure;
+    constructor(status, message, failure) { super(message); this.status = status; this.failure = failure ?? { message, code: codeOf(status) }; }
+}
+/** The FAILURE_CODES code (src/cli/command.ts) of a refusal by its HTTP status. */
+const codeOf = (status) => status === 400 ? "usage" : status === 404 ? "not_found" : status >= 500 ? "failed" : "refused";
+/** The HTTP status of a Failure by its code: the other way round. */
+const statusOf = (f) => f.code === "usage" ? 400 : f.code === "not_found" ? 404 : f.code === "failed" ? 500 : 409;
+/**
+ * EVERY ERROR ANSWER: `error`, the sentence a command prints (src/cli/control.ts reads it), and `failure`, the same
+ * refusal in the CLI's Failure shape — { code, message, why?, fix?, next: [{ command, what }] }, what `--json` prints
+ * — which the web page renders as the CLI does.
+ */
+export function sendFailure(res, status, f, extra = {}) {
+    sendJson(res, status, { error: f.message, ...extra, failure: { ...errorJson(f), next: nextJson(f.next) } });
+}
+/** THE WEB PAGE'S ROUTES, AND THE FILE EACH IS: the only files the server ever reads for a URL. */
+export const PAGE_ROUTES = {
+    "/": ["index.html", "text/html; charset=utf-8"],
+    "/app.js": ["app.js", "text/javascript; charset=utf-8"],
+    "/app.css": ["app.css", "text/css; charset=utf-8"],
+};
+/**
+ * The web page's files, READ ONCE when the server starts (src/web/ beside src/cli/, in a checkout and in the package
+ * alike: cli/build.ts copies them): a map of route to bytes. A request's path is looked up in it, never joined onto a
+ * folder, so no URL can name another file. A file missing is a broken install, said with the path.
+ */
+export function pageFiles(dir = fileURLToPath(new URL("../web/", import.meta.url))) {
+    return new Map(Object.entries(PAGE_ROUTES).map(([route, [file, type]]) => {
+        const at = path.join(dir, file);
+        let body;
+        try {
+            body = fs.readFileSync(at);
+        }
+        catch (e) {
+            throw new Error(`the web page's ${file} cannot be read (${at}: ${e.message}): this Mason is installed incompletely — npm i -g @mason-data/cli again`);
+        }
+        return [route, { body, type }];
+    }));
+}
+export function createRunServer(ctx) {
+    const saidErrors = new Set();
+    // read once, here: nothing a request names is ever read from disk (mason serve's run serves no page)
+    const page = ctx.page ? pageFiles() : new Map();
+    return http.createServer((req, res) => {
+        for (const [k, v] of Object.entries(SECURITY_HEADERS))
+            res.setHeader(k, v);
+        const v = guard({ method: req.method ?? "GET", url: req.url ?? "/", host: req.headers.host, origin: req.headers.origin, cookie: req.headers.cookie, authorization: req.headers.authorization }, ctx.port, ctx.token);
+        if (!v.ok) {
+            if (v.status === 303) {
+                res.writeHead(303, { Location: v.location, "Set-Cookie": v.setCookie }).end();
+                return;
+            }
+            res.writeHead(v.status, { "Content-Type": "text/plain; charset=utf-8" }).end(`${v.reason}\n`);
+            return;
+        }
+        const url = new URL(req.url ?? "/", `http://127.0.0.1:${ctx.port}`);
+        void (async () => {
+            try {
+                const file = req.method === "GET" || req.method === "HEAD" ? page.get(url.pathname) : undefined;
+                if (file !== undefined) {
+                    res.writeHead(200, { "Content-Type": file.type, "Content-Length": file.body.length }).end(req.method === "HEAD" ? undefined : file.body);
+                }
+                else if (req.method === "GET" && url.pathname === "/api/ping") {
+                    // what proves a run is up (src/cli/runs.ts answers): this token answered, by this process
+                    sendJson(res, 200, { pid: process.pid });
+                }
+                else if (req.method === "GET" && url.pathname === "/api/state") {
+                    sendJson(res, 200, await state(ctx));
+                }
+                else if (req.method === "GET" && url.pathname === "/api/slow") {
+                    // the last day's slow statements, from the request log (src/duck/requests.ts)
+                    sendJson(res, 200, { slow: await ctx.duck.requests.slow(SLOW_MS), slowMs: SLOW_MS });
+                }
+                else if (req.method === "GET" && url.pathname === "/api/refused") {
+                    sendJson(res, 200, await ctx.duck.requests.refused());
+                }
+                else if (req.method === "GET" && url.pathname === "/api/requests") {
+                    const limit = Number(url.searchParams.get("limit") ?? 40);
+                    if (!Number.isInteger(limit) || limit < 1 || limit > 10_000)
+                        throw new Refusal(400, "limit is a whole number of requests, 1 to 10000");
+                    sendJson(res, 200, { requests: await ctx.duck.requests.recent({ limit, failed: url.searchParams.get("failed") === "1" }), keptDays: ctx.duck.requests.days });
+                }
+                else if (req.method === "POST" && url.pathname === "/api/pick") {
+                    const body = JSON.parse(await readBody(req, 64 * 1024));
+                    if (typeof body.table !== "string" || typeof body.picked !== "boolean")
+                        throw new Refusal(400, "send { table, picked, columns?, key? }");
+                    if (body.columns !== undefined && !(Array.isArray(body.columns) && body.columns.every((c) => typeof c === "string")))
+                        throw new Refusal(400, "columns is a list of column names, or [\"*\"]");
+                    if (body.key !== undefined && !(Array.isArray(body.key) && body.key.length > 0 && body.key.every((c) => typeof c === "string")))
+                        throw new Refusal(400, "key is a list of column names");
+                    if (body.picked) {
+                        const r = await pick(ctx, body.table, body.columns ?? ["*"], body.key ?? null);
+                        if (!r.already)
+                            ctx.log(`added ${r.table} to ${r.file}`);
+                        ctx.sourcesChanged();
+                        sendJson(res, 200, { ...r, state: await state(ctx) });
+                    }
+                    else {
+                        const r = await removeTables(ctx, [body.table]);
+                        for (const t of r.removed)
+                            ctx.log(`removed ${t} from ${r.file}`);
+                        ctx.sourcesChanged();
+                        sendJson(res, 200, { ...r, state: await state(ctx) });
+                    }
+                }
+                else if (req.method === "GET" && url.pathname === "/api/users") {
+                    // mason user list --json's shape: the users, and whether each connects
+                    const r = listUsers(ctx.users.file, ctx.users.apiKey);
+                    if ("message" in r) {
+                        sendFailure(res, statusOf(r), r);
+                        return;
+                    }
+                    sendJson(res, 200, { ...r, next: nextJson([["mason user add <name>", "a user for a tool: its password and URL, printed once"]]) });
+                }
+                else if (req.method === "POST" && url.pathname === "/api/users") {
+                    const body = JSON.parse(await readBody(req, 64 * 1024));
+                    if (typeof body.name !== "string")
+                        throw new Refusal(400, "send { name }: the user's name");
+                    // mason user add --json's shape: its password, once, and the URL to paste (this run is up, so it has one)
+                    const r = addUser(ctx.users.file, ctx.users.apiKey, body.name, { link: postgresLink(ctx.users.postgresUrl), database: ctx.users.database });
+                    if ("message" in r) {
+                        sendFailure(res, statusOf(r), r);
+                        return;
+                    }
+                    const { replaced, ...added } = r;
+                    ctx.log(`user ${added.user} added${replaced ? " (in place of one the API key's rotation had removed)" : ""}`);
+                    sendJson(res, 200, { ...added, next: nextJson(addedNext(added.user, true)) });
+                }
+                else if (req.method === "DELETE" && url.pathname.startsWith("/api/users/")) {
+                    let name;
+                    try {
+                        name = decodeURIComponent(url.pathname.slice("/api/users/".length));
+                    }
+                    catch {
+                        throw new Refusal(400, `${url.pathname} does not name a user: DELETE /api/users/<name>`);
+                    }
+                    const r = removeUser(ctx.users.file, name);
+                    if ("message" in r) {
+                        sendFailure(res, statusOf(r), r);
+                        return;
+                    }
+                    ctx.log(`user ${r.removed.name} removed`);
+                    sendJson(res, 200, { ...r, next: nextJson(REMOVED_NEXT) });
+                }
+                else if (req.method === "POST" && url.pathname === "/api/sync") {
+                    const body = JSON.parse(await readBody(req, 64 * 1024));
+                    if (!Array.isArray(body.tables) || !body.tables.length || !body.tables.every((x) => typeof x === "string"))
+                        throw new Refusal(400, "send { tables: [schema.table, …] }");
+                    try {
+                        sendJson(res, 200, await ctx.duck.poll(body.tables));
+                    }
+                    catch (e) {
+                        if (e instanceof PollRefused) {
+                            sendFailure(res, e.code === "not_found" ? 404 : 409, { message: e.message, code: e.code }, { code: e.code });
+                            return;
+                        }
+                        throw e;
+                    }
+                }
+                else if (req.method === "POST" && url.pathname === "/api/remove") {
+                    const body = JSON.parse(await readBody(req, 64 * 1024));
+                    if (!Array.isArray(body.tables) || !body.tables.length || !body.tables.every((m) => typeof m === "string"))
+                        throw new Refusal(400, "send { tables: [name, …] }");
+                    const r = await removeTables(ctx, body.tables);
+                    // the sync stops copying a removed table, and drops its copy
+                    ctx.sourcesChanged();
+                    for (const t of r.removed)
+                        ctx.log(`removed ${t} from ${r.file}`);
+                    sendJson(res, 200, { ...r, state: await state(ctx) });
+                }
+                else {
+                    sendFailure(res, 404, { message: `no ${req.method} ${url.pathname}: this is mason start's server for the mason command (mason --help)`, code: "not_found" });
+                }
+            }
+            catch (e) {
+                if (e instanceof Refusal) {
+                    sendFailure(res, e.status, e.failure);
+                    return;
+                }
+                if (e instanceof SyntaxError) {
+                    sendFailure(res, 400, { message: `the body is not JSON: ${e.message}`, code: "usage" });
+                    return;
+                }
+                // said ONCE per distinct reason: a command may ask every second, and a stack a second buried the terminal
+                const why = (e.message.split("\n---\n").pop() ?? String(e)).split("\n")[0];
+                const key = `${url.pathname} ${why}`;
+                if (!saidErrors.has(key)) {
+                    saidErrors.add(key);
+                    ctx.log(`command server: ${req.method} ${url.pathname} failed: ${why}`);
+                }
+                sendFailure(res, 500, { message: e.message, code: "failed", next: [["mason logs", "the run's log: what it was doing"]] });
+            }
+        })();
+    });
+}

package/dist/src/cli/runs.js

@@ -0,0 +1,120 @@
+/**
+ * WHETHER MASON IS RUNNING FOR A PROJECT, and how a command reaches it (one run per project).
+ * `mason start` writes what its commands need into the project's config (`.mason/config.json` `running`, src/cli/project.ts):
+ * its pid, its Postgres API, and the command server it answers on with the run's token.
+ *
+ * UP MEANS IT ANSWERS: a pid alone is not proof — after a reboot the operating system hands the number to
+ * another process, and a `mason start` then refused as "already running" a run that did not exist. A run is up when
+ * its command server answers `/api/ping` with the run's own token and pid (`answers`).
+ *
+ * ALIVE AND SILENT IS A THIRD STATE (on the test server a run hung — its main thread blocked — with every port
+ * held; `mason stop` read the silence as "not running" and `mason destroy` deleted the copy under it, which the hung
+ * process kept open). A pid that is alive, whose command line is a Mason run's (`masonProcess`: after a reboot the
+ * number is another process's), and that does not answer is HUNG (`runState`): a command says so and names the way
+ * out, `mason stop` ends it (`endRun`: SIGTERM, then SIGKILL), and `mason destroy` removes nothing under it.
+ */
+import { spawnSync } from "node:child_process";
+import { theProject } from "./project.js";
+/** Whether process `pid` is alive (signal 0 tests without signalling). */
+export function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    } // alive, and someone else's: still running
+}
+/** The run a project's config says is up (its pid alive), or null. Whether it ANSWERS is `answers`'. */
+export function runOf(p, isAlive = alive) {
+    const r = p.config.running;
+    if (!r || !isAlive(r.pid))
+        return null;
+    return { name: p.config.name, root: p.root, home: p.dir, folder: p.folder, pid: r.pid, apiKey: p.config.apiKey,
+        control: { url: r.controlUrl, token: r.token }, postgresUrl: r.postgresUrl, postgresListener: r.postgresListener };
+}
+/** What the run's command server says of itself (`/api/ping`: its pid), or null when nothing answers with the run's token. */
+export async function ping(run) {
+    try {
+        const res = await fetch(`${run.control.url}/api/ping`, { headers: { Authorization: `Bearer ${run.control.token}` }, signal: AbortSignal.timeout(3_000) });
+        if (res.status !== 200)
+            return null;
+        return await res.json();
+    }
+    catch {
+        // nothing listening, a timeout, a body that is not JSON: not this run (whatever holds the port now). "Not up" is
+        // the answer the question wants: a command then says Mason is not running, with mason start as the way out
+        return null;
+    }
+}
+/** Whether the run answers with its own token and pid: the only proof it is up. */
+export async function answers(run) {
+    return (await ping(run))?.pid === run.pid;
+}
+/** What a command that needs Mason running says when it is not. */
+export function notRunning(p) {
+    return { problem: `Mason is not running for ${p.config.name} (${p.root})`, code: "not_running", next: [["mason start", "start it, in the background"]] };
+}
+/** How long a hung run is given to leave on SIGTERM before SIGKILL (the test server's ignored SIGTERM for 15 s). */
+export const END_GRACE_MS = 15_000;
+/** What a command says of a run that is alive and does not answer: what to run, since nothing else reaches it. */
+export function notAnswering(p, run) {
+    return { problem: `Mason for ${p.config.name} is running (pid ${run.pid}) but does not answer its commands (${run.control.url}, 3 s)`, code: "not_answering",
+        why: "a statement may be holding its main thread",
+        next: [["mason stop", `end it (SIGTERM, then SIGKILL after ${END_GRACE_MS / 1000} s); its copy stays and the next mason start resumes`], ["mason logs", "what it was doing"]] };
+}
+/** Whether `pid` is a Mason run, by its command line (`mason start … --attach`, src/cli/background.ts). ps exits 1 for a pid that is gone. */
+export function masonProcess(pid) {
+    const ps = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8" });
+    return ps.status === 0 && / start\b.*--attach\b/.test(ps.stdout);
+}
+/** The project's run: up (it answers), hung (alive, a Mason run, and silent), or none. */
+export async function runState(p, isAlive = alive, ask = answers, isMason = masonProcess) {
+    const r = runOf(p, isAlive);
+    if (r === null)
+        return { kind: "none", run: null };
+    if (await ask(r))
+        return { kind: "up", run: r };
+    return isMason(r.pid) ? { kind: "hung", run: r } : { kind: "none", run: null };
+}
+/** The project's run when it is up and answers; null when Mason is not running for it (a hung run is not up). */
+export async function liveRun(p, isAlive = alive, ask = answers) {
+    const st = await runState(p, isAlive, ask);
+    return st.kind === "up" ? st.run : null;
+}
+/**
+ * ENDS A RUN THAT DOES NOT ANSWER: SIGTERM, then SIGKILL once `graceMs` has passed with it still alive (a blocked main
+ * thread never sees SIGTERM), and the pid waited for. `killed` says whether SIGKILL was needed; a pid alive after it
+ * is said, never reported ended.
+ */
+export async function endRun(pid, deps = {}) {
+    const kill = deps.kill ?? ((p, sig) => process.kill(p, sig));
+    const isAlive = deps.isAlive ?? alive;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const grace = deps.graceMs ?? END_GRACE_MS;
+    kill(pid, "SIGTERM");
+    const until = Date.now() + grace;
+    while (isAlive(pid) && Date.now() < until)
+        await sleep(250);
+    if (!isAlive(pid))
+        return { killed: false };
+    kill(pid, "SIGKILL");
+    const gone = Date.now() + 10_000;
+    while (isAlive(pid) && Date.now() < gone)
+        await sleep(250);
+    if (isAlive(pid))
+        throw new Error(`pid ${pid} is still running after SIGKILL: it may be another user's, or the system is not reaping it (ps -p ${pid})`);
+    return { killed: true };
+}
+/** The run a command means: its project's (src/cli/project.ts theProject), up and answering; else why there is none. */
+export async function theRun(cwd) {
+    const t = theProject(cwd);
+    if ("problem" in t)
+        return { ...t, project: null };
+    const st = await runState(t.project);
+    if (st.kind === "up")
+        return { run: st.run, project: t.project };
+    if (st.kind === "hung")
+        return { ...notAnswering(t.project, st.run), project: t.project, hung: st.run };
+    return { ...notRunning(t.project), project: t.project };
+}