@mason-data/cli 0.0.0-stage → 0.7.0

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

@@ -0,0 +1,311 @@
+/**
+ * THE RUN'S COMMAND SERVER (`mason start`; a server for the `mason` command alone, the CLI's UI part dropped
+ * completely). `mason status`, `mason wait`, `mason sync`, `mason logs --requests`, and `mason add` and `mason remove`
+ * while it is up, 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/source-edit.ts, the check-and-write the commands call themselves while Mason is
+ * down) — 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 { catalogTable, shownPath } from "./sources.js";
+import { addEntry, Refusal, removeEntries, sourceToEdit } from "./source-edit.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 } : {}),
+            // how the run keeps the copy current NOW, as the sync derives it once (src/duck/sync.ts KeptCurrent, `keptOf`):
+            // what `unsynced` and the stream's tables say for mason status, and EXPLAIN says over the wire, as data
+            ...(c?.kept ? { kept: c.kept } : {}),
+            ...(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, demo: ctx.demo === true,
+            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 (src/cli/source-edit.ts sourceToEdit) — and the database it names NOW must be
+ *  the one this run copies: its catalog is what an edit is checked against. */
+function sourceOnDisk(ctx) {
+    const at = sourceToEdit(ctx.folder(), ctx.root, ctx.readSource);
+    if (at.read.resolved !== ctx.runUrl) {
+        throw new Refusal(409, `${shownPath(ctx.root, at.file)}: url: now names ${maskedUrl(at.read.resolved)} (${at.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 at;
+}
+/** The database this run copies, as an edit is checked against it: the catalog it last read, and how it reads changes. */
+const catalogOf = (ctx) => ({ tables: ctx.facts().tables, database: ctx.source.database, replication: ctx.changes === "replication" });
+/**
+ * ADD A TABLE: the check-and-write every entrance shares (src/cli/source-edit.ts addEntry), against the file on disk and
+ * this run's catalog; the caller tells the run the file changed, and the sync starts the copy.
+ */
+export function pick(ctx, table, columns = ["*"], key = null) {
+    return addEntry(sourceOnDisk(ctx), catalogOf(ctx), table, columns, key);
+}
+/** REMOVE TABLES: the check-and-write every entrance shares (src/cli/source-edit.ts removeEntries); the run then drops their copies. */
+export function removeTables(ctx, names) {
+    return removeEntries(sourceOnDisk(ctx), catalogOf(ctx), names);
+}
+/** The HTTP status of a Failure by its code: src/cli/source-edit.ts codeOf 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 = 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 = 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 = 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 };
+}

package/dist/src/cli/security.js

@@ -0,0 +1,86 @@
+/**
+ * THE LOCAL SERVERS' GUARD (security comes first here). `mason start` serves the command server
+ * on the developer's machine, which reads the database and WRITES the sources file of a folder for the `mason`
+ * commands, and its web page (`mason ui`, src/web/), whose users section adds and removes the project's users. Any
+ * website the developer visits can make their browser send requests to 127.0.0.1, so each request must prove it comes
+ * from the run itself (a command) or from a page the run served:
+ *
+ *   - LOOPBACK ONLY: the servers bind 127.0.0.1.
+ *   - A TOKEN: 32 random bytes, made per run and printed in the URL `mason ui` opens. The first request trades it
+ *     for an HttpOnly, SameSite=Strict cookie and is redirected to a URL without it; every request after needs the
+ *     cookie. A page on another site cannot read it, and SameSite=Strict keeps the browser from sending it on a
+ *     request another site starts.
+ *   - THE HOST HEADER must name this server (127.0.0.1:<port> or localhost:<port>): a DNS-rebinding page reaches
+ *     127.0.0.1 under its own name, and is refused by that name.
+ *   - THE ORIGIN of every request that changes something (anything but GET / HEAD) must be this server's own: a
+ *     cross-site form or fetch carries the other site's origin.
+ *   - No CORS headers, `frame-ancestors 'none'` (no other page may frame these), and `Referrer-Policy: no-referrer`
+ *     (the token URL never leaks as a referrer).
+ *
+ * THE COMMAND LINE (`mason status`, `mason add`, …; src/cli/control.ts) sends the same token as `Authorization: Bearer`,
+ * read from the run's settings file, which only the developer can read (0600 in a 0700 folder). It needs no cookie and
+ * no Origin: a browser sends an Authorization header across sites only after a CORS preflight, which these servers
+ * never approve, so a page on another site cannot send one at all.
+ *
+ * Cookies are per host, not per port, so one cookie serves every page of a run; a page of another run, or one
+ * the token does not match, is refused. Pure over the request's headers, so the refusals are unit-tested
+ * (tests/cli-security.test.ts).
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+export const COOKIE = "mason_dev";
+export function newToken() { return randomBytes(32).toString("hex"); }
+/** Constant-time string equality (a token compared byte by byte leaks its prefix through timing). */
+export function sameSecret(a, b) {
+    const x = Buffer.from(a), y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+export function cookieOf(header, name = COOKIE) {
+    for (const part of (header ?? "").split(";")) {
+        const eq = part.indexOf("=");
+        if (eq > 0 && part.slice(0, eq).trim() === name)
+            return decodeURIComponent(part.slice(eq + 1).trim());
+    }
+    return null;
+}
+export function setCookieHeader(token) {
+    return `${COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/`;
+}
+/** Whether `req` may be served by the server on `port` whose run token is `token`. */
+export function guard(req, port, token) {
+    const hosts = [`127.0.0.1:${port}`, `localhost:${port}`];
+    if (!req.host || !hosts.includes(req.host.toLowerCase())) {
+        return { ok: false, status: 421, reason: `this server answers only as ${hosts[0]} (the request named ${JSON.stringify(req.host ?? "")})` };
+    }
+    if (req.authorization !== undefined) {
+        const bearer = /^Bearer\s+(\S+)$/i.exec(req.authorization)?.[1];
+        return bearer !== undefined && sameSecret(bearer, token) ? { ok: true }
+            : { ok: false, status: 403, reason: "the Authorization header does not carry this run's token" };
+    }
+    const url = new URL(req.url, `http://${req.host}`);
+    const offered = url.searchParams.get("token");
+    if (offered !== null) {
+        if (!sameSecret(offered, token))
+            return { ok: false, status: 403, reason: "the token in the URL is not this run's" };
+        url.searchParams.delete("token");
+        return { ok: false, status: 303, location: url.pathname + (url.search || "") + url.hash, setCookie: setCookieHeader(token) };
+    }
+    const cookie = cookieOf(req.cookie);
+    if (cookie === null || !sameSecret(cookie, token)) {
+        return { ok: false, status: 403, reason: "this is mason start's command server for the mason command: a request carries the run's token (Authorization: Bearer, from .mason/config.json)" };
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") {
+        const own = hosts.map((h) => `http://${h}`);
+        if (!req.origin || !own.includes(req.origin.toLowerCase())) {
+            return { ok: false, status: 403, reason: `a change must come from this page (Origin ${JSON.stringify(req.origin ?? "")})` };
+        }
+    }
+    return { ok: true };
+}
+/** The headers every response of a guarded server carries. */
+export const SECURITY_HEADERS = {
+    "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'none'; form-action 'self'",
+    "X-Frame-Options": "DENY",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+    "Cache-Control": "no-store",
+};

package/dist/src/cli/self-signed-cert.js

@@ -0,0 +1,64 @@
+/**
+ * A SELF-SIGNED X.509 CERTIFICATE, MADE WITH NODE ALONE (`mason start --self-signed-tls`, src/cli/pg-tls.ts).
+ * `node:crypto` generates the key and signs, but has no API that writes a certificate, and the tree has no library that
+ * does — so the certificate is DER written here: one shape, no extensions, nothing parsed. RFC 5280 §4.1:
+ *
+ *   Certificate     ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signature BIT STRING }
+ *   TBSCertificate  ::= SEQUENCE { [0] version v3, serialNumber, signature, issuer, validity, subject, subjectPublicKeyInfo }
+ *
+ * RSA 2048 with SHA-256: the key every TLS client takes (a hosted BI tool's JVM included); ECDSA would do for most.
+ * Node's own `X509Certificate` reads it back and verifies its signature (tests/pg-tls.test.ts), and a real handshake
+ * against the Postgres listener uses it. What a self-signed certificate gives is ENCRYPTION — a client with
+ * `sslmode=require` checks no certificate — never proof of whose server it is: that is a certificate a CA signed.
+ */
+import * as crypto from "node:crypto";
+const tlv = (tag, content) => {
+    const n = content.length;
+    if (n < 0x80)
+        return Buffer.concat([Buffer.from([tag, n]), content]);
+    const len = [];
+    for (let m = n; m > 0; m >>= 8)
+        len.unshift(m & 0xff);
+    return Buffer.concat([Buffer.from([tag, 0x80 | len.length, ...len]), content]);
+};
+const seq = (...parts) => tlv(0x30, Buffer.concat(parts));
+function oid(dotted) {
+    const [a, b, ...rest] = dotted.split(".").map(Number);
+    const bytes = [40 * a + b];
+    for (const n of rest) {
+        const groups = [];
+        for (let m = n;; m = Math.floor(m / 128)) {
+            groups.unshift(m % 128);
+            if (m < 128)
+                break;
+        }
+        bytes.push(...groups.map((g, i) => (i < groups.length - 1 ? g | 0x80 : g)));
+    }
+    return tlv(0x06, Buffer.from(bytes));
+}
+/** a positive INTEGER from its big-endian bytes */
+const integer = (bytes) => tlv(0x02, bytes[0] & 0x80 ? Buffer.concat([Buffer.from([0]), bytes]) : bytes);
+/** UTCTime through 2049, GeneralizedTime from 2050 (RFC 5280 §4.1.2.5) */
+function time(d) {
+    const iso = d.toISOString(); // 2026-10-26T12:34:56.789Z
+    const digits = iso.slice(0, 19).replace(/[-T:]/g, "");
+    return d.getUTCFullYear() < 2050 ? tlv(0x17, Buffer.from(`${digits.slice(2)}Z`)) : tlv(0x18, Buffer.from(`${digits}Z`));
+}
+const name = (commonName) => seq(tlv(0x31, seq(oid("2.5.4.3"), tlv(0x0c, Buffer.from(commonName, "utf8")))));
+const pem = (label, der) => `-----BEGIN ${label}-----\n${der.toString("base64").replace(/.{1,64}/g, "$&\n")}-----END ${label}-----\n`;
+/** A new RSA key and a certificate for it, signed by itself, valid from an hour ago (a client's clock behind) for
+ *  `years`; both PEM. */
+export function selfSignedCertificate(commonName, o = {}) {
+    const now = o.now ?? new Date();
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("rsa", { modulusLength: 2048 });
+    const serial = crypto.randomBytes(16);
+    serial[0] = (serial[0] & 0x7f) | 0x40; // positive, and never a leading zero byte
+    const notAfter = new Date(now);
+    notAfter.setUTCFullYear(notAfter.getUTCFullYear() + (o.years ?? 10));
+    const sha256WithRsa = seq(oid("1.2.840.113549.1.1.11"), tlv(0x05, Buffer.alloc(0)));
+    const tbs = seq(tlv(0xa0, integer(Buffer.from([2]))), // [0] EXPLICIT version: v3
+    integer(serial), sha256WithRsa, name(commonName), seq(time(new Date(now.getTime() - 3_600_000)), time(notAfter)), name(commonName), publicKey.export({ type: "spki", format: "der" }));
+    const signature = crypto.sign("sha256", tbs, privateKey); // PKCS#1 v1.5, the algorithm named above
+    const der = seq(tbs, sha256WithRsa, tlv(0x03, Buffer.concat([Buffer.from([0]), signature])));
+    return { cert: pem("CERTIFICATE", der), key: privateKey.export({ type: "pkcs8", format: "pem" }).toString() };
+}