@mason-data/cli 0.6.2 → 0.7.0

package/dist/src/cli/preflight.js

@@ -25,7 +25,9 @@ export function maskedUrl(url) {
         return u.toString();
     }
     catch {
-        return url.replace(/:\/\/([^:@/]*):[^@/]*@/, "://$1:****@");
+        // not a URL: everything from the user's colon to the LAST @ is the password, whatever it holds (a / or an @ that
+        // was not encoded) — a host never holds an @
+        return url.replace(/:\/\/([^:@/]*):.*@/, "://$1:****@");
     }
 }
 /**
@@ -38,7 +40,8 @@ export function parseSource(url) {
         u = new URL(url);
     }
     catch {
-        return { problem: `${JSON.stringify(url)} is not a URL. The form is postgres://user:password@localhost:5432/your_app — a password ` +
+        // its password masked: the problem is printed (and, under mason mcp, kept in the MCP client's log)
+        return { problem: `${JSON.stringify(maskedUrl(url))} is not a URL. The form is postgres://user:password@localhost:5432/your_app — a password ` +
                 `containing @ : / # ? or % must be URL-encoded (encodeURIComponent; @ is %40).` };
     }
     if (u.protocol !== "postgres:" && u.protocol !== "postgresql:")
@@ -62,7 +65,7 @@ export function parseSource(url) {
     }
 }
 /** What a failed connection means, and what to change. */
-export function explainConnectError(e, s) {
+export function explainConnectError(e, s, o = {}) {
     const where = `${s.host}:${s.port}`;
     const msg = e?.message ?? String(e);
     if (e instanceof PgError) {
@@ -82,6 +85,9 @@ export function explainConnectError(e, s) {
         return { message: `${where}: ${msg}`, hints: [] };
     }
     if (/ECONNREFUSED/.test(msg)) {
+        // the demo database is served by the project's own run: nothing else could be listening there
+        if (o.demo)
+            return { message: `the demo database is not running on ${where}`, hints: ["the demo database runs inside mason start: start it first"] };
         return {
             message: `nothing is listening on ${where}`,
             hints: [
@@ -106,13 +112,13 @@ export function explainConnectError(e, s) {
     return { message: `${where}: ${msg}`, hints: [] };
 }
 /** Connect as the service will. The failure is explained; for a missing database, the ones that exist are listed. */
-export async function connectSource(s) {
+export async function connectSource(s, o = {}) {
     const opts = { host: s.host, port: s.port, database: s.database, user: s.user, password: s.password, sslmode: s.sslmode, connectTimeoutMs: 10_000, applicationName: "mason-dev" };
     try {
         return { pg: await PgConnection.connect(opts) };
     }
     catch (e) {
-        const failure = explainConnectError(e, s);
+        const failure = explainConnectError(e, s, o);
         if (e instanceof PgError && e.code === "3D000") {
             try {
                 const pg = await PgConnection.connect({ ...opts, database: "postgres" });
@@ -156,17 +162,20 @@ export const TABLES_SQL = `SELECT json_agg(t ORDER BY t.schema, t.table)::text F
       THEN (SELECT coalesce(sum(pg_total_relation_size(pt.relid)), 0) FROM pg_partition_tree(c.oid) pt WHERE pt.isleaf)
       ELSE pg_total_relation_size(c.oid) END AS bytes,
     obj_description(c.oid, 'pg_class') AS comment,
+    -- the primary key: only a valid index enforces it
     (SELECT coalesce(json_agg(a.attname ORDER BY k.n), '[]'::json)
       FROM pg_index i CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, n)
       JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
-      WHERE i.indrelid = c.oid AND i.indisprimary) AS key,
+      WHERE i.indrelid = c.oid AND i.indisprimary AND i.indisvalid) AS key,
     (SELECT coalesce(json_agg(json_build_object('name', ic.relname, 'constraint', EXISTS (SELECT FROM pg_constraint u WHERE u.conindid = i.indexrelid AND u.contype = 'u'),
         -- indnullsnotdistinct is Postgres 15's: read through the row, which an older server's lacks
         'nulls_not_distinct', coalesce((to_jsonb(i) ->> 'indnullsnotdistinct')::boolean, false),
         'columns', (SELECT json_agg(a.attname ORDER BY k.n) FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, n)
           JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum)) ORDER BY ic.relname), '[]'::json)
       FROM pg_index i JOIN pg_class ic ON ic.oid = i.indexrelid
-      WHERE i.indrelid = c.oid AND i.indisunique AND NOT i.indisprimary AND i.indpred IS NULL AND i.indexprs IS NULL
+      -- an INVALID index (a CREATE UNIQUE INDEX CONCURRENTLY that failed, its duplicates still in the table) enforces
+      -- nothing: never declared to the catalog, never a key: Mason accepts
+      WHERE i.indrelid = c.oid AND i.indisunique AND i.indisvalid AND NOT i.indisprimary AND i.indpred IS NULL AND i.indexprs IS NULL
         AND i.indnkeyatts = i.indnatts) AS unique_keys,
     (SELECT coalesce(json_agg(json_build_object('name', a.attname, 'type', format_type(a.atttypid, a.atttypmod),
         'not_null', a.attnotnull, 'comment', col_description(c.oid, a.attnum), 'type_oid', a.atttypid,

package/dist/src/cli/project.js

@@ -26,6 +26,8 @@ const CONFIG = "config.json";
 export const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,47}$/;
 /** The copy of the data, a DuckDB file in the project's `.mason/`: kept by mason stop, deleted by mason destroy. */
 export const DUCK_FILE = "duck.db";
+/** The demo database's folder in the project's `.mason/` (`mason init demo`): hosted by mason start, deleted by mason destroy. */
+export const DEMO_DIR = "demo";
 /** A name from a folder's: lower case, the rest of it dashes. */
 export function nameFromFolder(dir) {
     const n = path.basename(path.resolve(dir)).toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^[-_]+|[-_]+$/g, "").slice(0, 48);
@@ -97,8 +99,8 @@ export function writeConfig(dir, c) {
     fs.chmodSync(file, 0o600);
 }
 /** A new project's config: the secrets made here, once. */
-export function newConfig(name, folder, remote) {
-    return { name, folder, remote, apiKey: randomBytes(24).toString("hex"), sourceServer: null, running: null, lastRun: null };
+export function newConfig(name, folder, remote, o = {}) {
+    return { name, folder, remote, ...(o.demo ? { demo: true } : {}), apiKey: randomBytes(24).toString("hex"), sourceServer: null, running: null, lastRun: null };
 }
 /**
  * THE PROJECT A COMMAND MEANS: the nearest at or above `cwd`; or the sentence that says why there is none, with the
@@ -110,7 +112,7 @@ export function theProject(cwd) {
         return brokenProblem(p);
     if (p)
         return { project: p };
-    return { problem: "no Mason project here or above", code: "no_project", fix: "cd into a project's folder, or make this folder one",
+    return { problem: "no Mason project here or above", code: "no_project", fix: "cd into a project's folder, or make this folder one (mason init demo: a demo database, nothing to install)",
         next: [["mason init", "make this folder a project (DATABASE_URL from .env, or mason init postgres://…)"]] };
 }
 /** Whether `root`'s .gitignore already ignores `.mason/`. */

package/dist/src/cli/registry.js

@@ -8,6 +8,7 @@ import { dev } from "./dev.js";
 import { devInBackground } from "./background.js";
 import { ADD, LOGS, REMOVE, STATUS, STOP, TABLES, WAIT, add, logs, remove, status, stop, tables, wait } from "./commands.js";
 import { USER, user } from "./user.js";
+import { MCP, mcp } from "./mcp.js";
 import { UI, ui } from "./ui.js";
 import { GUIDES, guideText } from "./guides.js";
 import { DOCTOR, NODE_MIN, doctor } from "./doctor.js";
@@ -97,7 +98,7 @@ async function runDev(argv) {
     if (!Number.isInteger(port) || port < 1 || port > 65_535)
         return failed("start", { message: `--port must be a port number (1-65535), not ${JSON.stringify(v.port)}`, code: "usage" }, { json: v.json });
     if (!v.attach)
-        return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"] });
+        return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"], changes: v.replication ? "replication" : v.poll ? "poll" : null });
     return dev({ port, version: version(), changes: v.replication ? "replication" : v.poll ? "poll" : null, publication: v.publication ?? null, selfSignedTls: v["self-signed-tls"] });
 }
 export const HELP = {
@@ -151,7 +152,7 @@ export const STEPS = [
     ["Learn", [{ ...HELP, run: runHelp }]],
     ["Set up", [{ ...DOCTOR, run: (argv) => doctor(argv) }, { ...INIT, run: (argv) => init(argv) }, { ...DEV, run: runDev }]],
     ["Add your tables", [{ ...TABLES, run: tables }, { ...ADD, run: add }, { ...REMOVE, run: remove }, { ...WAIT, run: wait }]],
-    ["Connect", [{ ...USER, run: user }]],
+    ["Connect", [{ ...USER, run: user }, { ...MCP, run: mcp }]],
     ["Run", [{ ...STATUS, run: status }, { ...UI, run: ui }, { ...SYNC, run: sync }, { ...LOGS, run: logs }, { ...STOP, run: stop }, { ...DESTROY, run: (argv) => destroy(argv) }]],
     ["Go to production", [{ ...SERVE, run: serve }]],
 ];
@@ -171,7 +172,9 @@ export async function orientation(cwd, s = styleOut()) {
         ? [["Project", `${project.config.name}, files in ${project.folder}`], ["Mason", run ? `running (pid ${run.pid})` : "not running"]]
         : [["Project", "none here: mason init makes this folder one"]];
     const next = !project
-        ? [["mason init", "make this folder a project (DATABASE_URL from .env, or mason init postgres://…)"], ["mason doctor", "what this machine needs for Mason, and whether it has it"]]
+        ? [["mason init", "make this folder a project (DATABASE_URL from .env, or mason init postgres://…)"],
+            ["mason init demo", "or try it on a demo database Mason makes itself: nothing to install"],
+            ["mason doctor", "what this machine needs for Mason, and whether it has it"]]
         : !run ? [["mason start", "start Mason for this project, in the background"], ["mason status", "the project and its tables"]]
             : [["mason status", "what Mason is doing: its tables, and the last day's slow and refused statements"], ["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"]];
     return `${reportText({ headline: "Mason: your Postgres tables, copied and served to BI tools and your app.", details: rows,
@@ -202,14 +205,14 @@ export function topUsage(s = styleOut()) {
         `${s.bold("usage:")} mason <command> [options]`,
         "",
         para("Mason: your Postgres tables, copied and served to BI tools and your app. Make your app's folder a project (mason init), " +
-            `start Mason (mason start), add tables, connect a tool (mason user add). It needs Node ${NODE_MIN} or later; mason doctor checks.`),
+            `add tables (mason add, before or after the start), start Mason (mason start), connect a tool (mason user add). It needs Node ${NODE_MIN} or later; mason doctor checks.`),
         para(PROJECT_LINE),
         "",
         listed.map(([step, es]) => `  ${s.bold(step)}\n${block(es)}`).join("\n\n"),
         "",
         para("mason <command> --help (or mason help <command>) says how to use one, with examples; the guides are offline and short enough to read whole."),
         para("A command means the project of the folder it runs in (or above it)."),
-        para("Every command but help takes --json: one JSON object for a program, always with next (what to run " +
+        para("Every command but help and mcp (whose stdout is the MCP protocol's) takes --json: one JSON object for a program, always with next (what to run " +
             "next); a failure is { error: { code, message, why, fix }, next }. The exit code says how it went: 0 done, 1 failed " +
             "with the reason, 2 a wrong command line, 124 mason wait timed out. Driving Mason from a coding agent: mason help agent."),
         "",

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

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * 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.
@@ -29,7 +29,8 @@ 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 { 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;
@@ -59,6 +60,9 @@ export function runState(ctx, copies, stream) {
             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 } } : {}),
         };
     });
@@ -68,7 +72,7 @@ export function runState(ctx, copies, stream) {
         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,
+        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
@@ -92,111 +96,30 @@ function fileBytes(file) {
 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. */
+/** 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 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)}: ` +
+    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 { 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 };
+    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" });
 /**
- * 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.
+ * 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 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 };
+export function pick(ctx, table, columns = ["*"], key = null) {
+    return addEntry(sourceOnDisk(ctx), catalogOf(ctx), table, columns, key);
 }
-/** 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) }; }
+/** 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 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. */
+/** 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
@@ -282,14 +205,14 @@ export function createRunServer(ctx) {
                     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);
+                        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 = await removeTables(ctx, [body.table]);
+                        const r = removeTables(ctx, [body.table]);
                         for (const t of r.removed)
                             ctx.log(`removed ${t} from ${r.file}`);
                         ctx.sourcesChanged();
@@ -354,7 +277,7 @@ export function createRunServer(ctx) {
                     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);
+                    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)

package/dist/src/cli/serve.js

@@ -53,7 +53,12 @@ export const SERVE = {
     MASON_PG_HOST, MASON_PG_PORT   the Postgres API's address (default 127.0.0.1:5433)
     MASON_PG_TLS_CERT, MASON_PG_TLS_KEY   its certificate, required off loopback; or MASON_PG_SELF_SIGNED_TLS=1
                             for one made in .mason/, or MASON_PG_PLAIN=1 behind a TLS proxy of your own
-    MASON_DUCKDB_MEMORY, MASON_POLL_MS, MASON_STATEMENT_TIMEOUT, MASON_STORE_JSON_PATHS   as for mason start
+    MASON_DUCKDB_MEMORY     the copy's memory, 4GB or 512MiB (default half the container's memory limit, else half the
+                            machine's RAM; mason doctor says it); a statement past it fails alone with 53200
+    MASON_POLL_MS           how often the poll reads the tables' changes, in ms (default 5000)
+    MASON_STATEMENT_TIMEOUT   each statement's limit, as Postgres's statement_timeout (default 5min; 0 for none)
+    MASON_REQUEST_LOG_DAYS  how long the request log keeps a statement, in days (default 7)
+    MASON_STORE_JSON_PATHS  on (the default) stores the JSON paths statements keep reading as columns; off stores none
     MASON_COPY_PARALLEL     a copy's chunks read at once, each a backend on the database (1 to 8, default 3)
     MASON_COPY_CHUNK_SECONDS   how long each chunk takes to read, at the rate measured (1 to 300, default 12)
 

package/dist/src/cli/source-edit.js

@@ -0,0 +1,116 @@
+/**
+ * `mason add` AND `mason remove`, CHECKED AND WRITTEN — ONE GRAMMAR AT EVERY ENTRANCE. The run's command server
+ * (`POST /api/pick`, `/api/remove`, src/cli/run-server.ts: the commands with Mason up, and the web page) and the commands
+ * themselves with Mason down (src/cli/commands.ts: the file is the list, so `mason init && mason add orders && mason
+ * start` is a natural order) call these functions, so a refusal is worded ONCE and both entrances say it alike
+ * (tests/cli-commands.test.ts holds the two equal). What differs is only what each does after: the run starts or drops the
+ * copy and reads the file again; the command says the copy begins at `mason start`.
+ *
+ * Each takes the sources file as it is on disk now (`sourceToEdit`), the database's catalog as `readSourceFacts` reads it
+ * (`EditCatalog`), and the request; it checks the entry and the file's other entries against the catalog (an edit is never
+ * written over a file the next read would refuse), splices the one entry in or out (`withTable` / `withoutTable`: every
+ * other byte as it was), writes the file, and answers what it did — or throws a `Refusal`, the sentence a command shows.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { addedTables, chooseColumns, entryName, entryProblems, findEntry, parseSourceText, sourceFailure, sourceFileNames, sourcesDir, unaddableReason, withoutTable, withTable } from "./sources.js";
+/** 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 project's sources file as it is on disk NOW, its text and what it says — or why it cannot be edited: no folder, not
+ * exactly one file, a file with mistakes of its own, a URL that cannot be resolved (`read`, the file read as the run reads
+ * it: src/cli/sources.ts readSource).
+ */
+export function sourceToEdit(folder, root, read) {
+    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(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, root, parsed.problems);
+        throw new Refusal(409, `${f.message}${f.why ? `\n${f.why}` : ""} — fix it first`);
+    }
+    const r = read();
+    if ("message" in r)
+        throw new Refusal(409, `${r.message}${r.why ? `\n${r.why}` : ""} — fix it first`);
+    return { root, file, text, parsed, read: r };
+}
+/** The file's other entries against the database: an edit is never written over a file the run would not take. */
+function othersHold(at, db, without, then) {
+    const others = { ...at.parsed, tables: at.parsed.tables.filter((e) => !without.includes(e.table)) };
+    const held = addedTables(others, db.tables, db.database, at.root, { replication: db.replication });
+    if (!Array.isArray(held))
+        throw new Refusal(409, `${held.message}${held.why ? `\n${held.why}` : ""} — fix it first, then ${then}`);
+}
+/**
+ * ADD A TABLE (`table`: schema.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 entry and the file's other entries must hold against
+ * the database first: an edit is never written over a file the next read would refuse.
+ */
+export function addEntry(at, db, table, columns = ["*"], key = null) {
+    const t = db.tables.find((x) => x.source === table);
+    if (!t)
+        throw new Refusal(404, `${table} is not a table of ${db.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 && db.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(at, db, [table], `add ${entryName(table)}`);
+    const was = at.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, db.tables, db.database, { replication: db.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(at.text, entry);
+        if ("problem" in r)
+            throw new Refusal(409, `${path.relative(at.root, at.file)} cannot be edited: ${r.problem}`);
+        fs.writeFileSync(at.file, r.text);
+    }
+    return { table, file: at.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. A
+ * name the file does not have is refused with the closest one it has; the entries that stay must hold against the
+ * database — else the run's re-read refuses the file, keeps the removed table and goes on copying it while the command
+ * said "Removed".
+ */
+export function removeEntries(at, db, names) {
+    const entries = names.map((n) => {
+        const e = findEntry(at.parsed, n);
+        if ("problem" in e)
+            throw new Refusal(e.usage ? 400 : 404, e.problem);
+        return e;
+    });
+    othersHold(at, db, entries.map((e) => e.table), `remove ${names.join(" ")}`);
+    let out = at.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(at.root, at.file)} cannot be edited: ${r.problem}`);
+        out = r.text;
+    }
+    fs.writeFileSync(at.file, out);
+    return { removed: [...new Set(entries.map((e) => e.table))], file: at.file };
+}

package/dist/src/cli/sources.js

@@ -201,8 +201,9 @@ export function sourceFileNames(folder) {
         return [];
     return fs.readdirSync(dir).filter((f) => /\.ya?ml$/.test(f) && !f.startsWith(".")).sort();
 }
-/** The file `mason init` writes: the database, then its tables (none yet). */
-export function newSourceText(url = "${DATABASE_URL}") {
+/** The file `mason init` writes: the database, then its tables — none yet, but for `mason init demo`'s, which names the
+ *  demo database's tables (`tables`, each copied whole: `{}`), so its first start copies them and shows something. */
+export function newSourceText(url = "${DATABASE_URL}", tables = []) {
     return "# The database this project copies from, and which of its tables. Yours to commit; the URL stays out of it.\n" +
         "kind: postgres\n" +
         `url: ${url}${ENV_REF.test(url) ? "   # from .env.local, .env or the shell; a literal postgres:// URL works too" : ""}\n` +
@@ -210,7 +211,7 @@ export function newSourceText(url = "${DATABASE_URL}") {
         "# One entry per table, a bare name in public, else schema.table: {} copies every column, columns: [id, status]\n" +
         "# those, exclude: [payload] every column but those; key: [a, b] names the columns that tell its rows apart, for a\n" +
         "# table with no primary key. mason add and mason remove edit this list; so can you.\n" +
-        "tables: {}\n";
+        (tables.length ? `tables:\n${tables.map((t) => `  ${t}: {}\n`).join("")}` : "tables: {}\n");
 }
 /** A source's name from its database's: the file is named for it, else `app`. */
 export function sourceNameFor(database) {
@@ -299,7 +300,8 @@ export function entryProblems(t, e, all, database, o) {
  * A `key:` MUST TELL THE ROWS APART, AS THE DATABASE ENFORCES IT (the review of the sources file: a key with
  * duplicates failed the copy's distinct-key check as "Mason bug", retried for ever, and duplicates after the copy made the
  * poll's update and delete by key change both rows): every column NOT NULL, and a unique index of the table over some of
- * them — then no two rows can share the key. Partial and expression indexes are not read (src/cli/preflight.ts).
+ * them — then no two rows can share the key. Partial, expression and INVALID indexes are not read (src/cli/preflight.ts
+ * TABLES_SQL: a failed CREATE UNIQUE INDEX CONCURRENTLY leaves an invalid one, its duplicates still in the table).
  */
 function keyProblems(t, key, at) {
     const cols = key.filter((c) => t.columns.some((x) => x.name === c));