@mason-data/cli 0.6.2 → 0.7.0

package/dist/src/cli/commands.js

@@ -1,7 +1,8 @@
 /**
  * THE COMMANDS BESIDE `mason start` (an interface as good for people as for coding agents).
- * Each one finds the run it means (src/cli/runs.ts), asks its command server (src/cli/control.ts), and prints
- * it for a person — or, with `--json`, as data a program reads. Exit codes are part of each command's contract:
+ * Each one finds the run it means (src/cli/runs.ts) and asks its command server (src/cli/control.ts) — or, for what
+ * needs only the project's files and its database (tables; add and remove while Mason is down), reads them itself — and
+ * prints it for a person or, with `--json`, as data a program reads. Exit codes are part of each command's contract:
  *
  *   mason status [--json]                 what the run is doing: its database, its tables and their copies, the Postgres API
  *   mason tables [<table>…] [--json]      the database's tables, their columns, keys and foreign keys
@@ -13,17 +14,19 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { endText, errorJson, failed, jsonText, nextBlock, parseCommand, reportText, withEnd } from "./command.js";
+import { asFailure, endText, errorJson, failed, jsonText, nextBlock, parseCommand, reportText, withEnd } from "./command.js";
 import { err as styleErr, out as styleOut, stepRenderer, wrap } from "./style.js";
-import { alive, endRun, END_GRACE_MS, theRun } from "./runs.js";
+import { alive, endRun, END_GRACE_MS, notAnswering, runState, theRun } from "./runs.js";
 import { version } from "./version.js";
 import { readRestarts, signalSupervisor, stopSupervisor, supervisorGone } from "./supervise.js";
-import { DUCK_FILE, isProject, projectSource, readProject, theProject, writeConfig } from "./project.js";
+import { DEMO_DIR, DUCK_FILE, STATE_DIR, isProject, projectSource, readProject, theProject, writeConfig } from "./project.js";
 import { callRun, RunUnreachable } from "./control.js";
 import { withPlaceholders, postgresLink } from "./pg-url.js";
 import { listenerText } from "./pg-tls.js";
 import { SLOW_MS } from "./run-server.js";
 import { catalogTable, entryName, looksSecret, tableNameProblem } from "./sources.js";
+import { addEntry, Refusal, removeEntries, sourceToEdit } from "./source-edit.js";
+import { changesOf } from "./replication-mode.js";
 import { connectSource, maskedUrl, parseSource, readSourceFacts } from "./preflight.js";
 import { reach } from "./state.js";
 import { copyingText, copyProgress, duration, readiness } from "./readiness.js";
@@ -200,10 +203,18 @@ const STATUS_USAGE = `usage: mason status [--json]
   --json   as data: { running, pid, postgres: { url, host, port, database, sslmode (require when it is TLS), listener:
            { host (what it is bound to), tls (certificate, self-signed or null), fingerprint } }, source: { name (the
            source's: its sources file's), file (the sources file), url, database, remote, version, standby, changes,
-           replication }, warnings, folder, project, tables: [{ table, rows, bytes, key, added, addedColumns, copy, error,
-           … }], engine: { file, bytes, pollSeconds, restarts (each time its supervisor started the
-           run again: { at, reason, upSeconds }) }, slowQueries, refusedQueries, refusedTotal (how many in all),
-           readiness (what mason wait waits on), ui (whether this run serves the web page: mason ui), next }; with Mason stopped: { running: false, project, source: { name,
+           replication, demo (the demo database this run hosts) }, warnings, folder, project, tables: [{ table, rows,
+           bytes, key, added, addedColumns, copy, error, unsynced: { reason, asOf } (copied and served, not kept
+           current by the poll), kept, … }], engine: { file, bytes, pollSeconds, restarts (each time its supervisor
+           started the run again: { at, reason, upSeconds }) }, slowQueries, refusedQueries, refusedTotal (how many in
+           all), readiness (what mason wait waits on), ui (whether this run serves the web page: mason ui), next }.
+           Each table's kept is how its copy is kept current now (absent for a table the sync does not hold):
+           { by: poll, polledAt (its last copy or poll), unsynced (only when it applies: why the passes leave it as
+           copied, mason sync polls it), pending (only when it applies: why the copy is not kept current now, its
+           phase included: waiting for its copy, being copied, its copy failed, to be copied again, caught up first) }
+           or { by: recopy, copiedAt, pending (only when it applies, as the poll's) }
+           or { by: replication, slot, state (streamed, catching-up, waiting, left-out), why, position, lastCommit,
+           notRunning (why the stream is not running, null when it is) }; with Mason stopped: { running: false, project, source: { name,
            file, url, error (the sources file's problem, or null) }, engine, tables: [{ table }], lastRun, lastStop:
            { at, how } or null, next }; hung: the same with hung: { pid, problem, why },
            exit 1. In replication mode stream: { slot, publication, running, failure, position,
@@ -327,10 +338,11 @@ export async function status(argv) {
 export function sourceRows(s) {
     return [
         ...(s.source.file ? [["Source", `${s.source.file} (the tables it names are added)`]] : []),
-        ["Database", `${s.source.url} · Postgres ${s.source.version}${s.source.standby ? " · a read replica" : ""}`],
+        ["Database", s.source.demo ? `the demo database Mason hosts (${s.source.url} · Postgres ${s.source.version})`
+                : `${s.source.url} · Postgres ${s.source.version}${s.source.standby ? " · a read replica" : ""}`],
         ["Changes", s.source.replication ? `logical replication: slot ${s.source.replication.slot}, publication ${s.source.replication.publication} ` +
                 `(${s.source.replication.owned ? "Mason's own" : "named: read as it is, never altered"}) · mason start --poll goes back to polling`
-                : `polling with SELECTs (xmin), every ${s.engine.pollSeconds} s · mason start --replication reads the database's change log instead`],
+                : `polling with SELECTs (xmin), every ${s.engine.pollSeconds} s · ${s.source.demo ? "the demo database is read by polling only" : "mason start --replication reads the database's change log instead"}`],
     ];
 }
 /** An SQL statement on one line, cut at `max` characters (the whole of it is mason logs --requests --json's). */
@@ -537,9 +549,8 @@ export async function tables(argv) {
     if (!f.positionals.length && !f.values.all) {
         const w = Math.max(...shown.map((t) => t.table.length));
         for (const t of shown) {
-            const size = t.rows === null ? "rows unknown" : `~${n(t.rows)} rows`;
-            out(`${t.table.padEnd(w)}  ${size.padStart(18)}  ${t.key.length ? `key ${t.key.join(", ")}` : "no key"}` +
-                `${t.added ? "  · added" : t.reason ? `  · cannot be added as it is: ${t.reason}` : ""}`);
+            const l = tableFacts(t);
+            out(`${t.table.padEnd(w)}  ${l.size.padStart(18)}  ${l.key}${l.state ? `  · ${l.state}` : ""}`);
         }
         out(nextBlock(next));
         return 0;
@@ -566,22 +577,35 @@ export async function tables(argv) {
         out(nextBlock(next).slice(1));
     return 0;
 }
+/** A table's line in `mason tables`: its size, its key, and added or why it cannot be added as it is (the web page's
+ *  tables say the same, src/web/app.js; tests/web-page.test.ts holds the two equal). */
+export function tableFacts(t) {
+    return { size: t.rows === null ? "rows unknown" : `~${n(t.rows)} rows`, key: t.key.length ? `key ${t.key.join(", ")}` : "no key",
+        state: t.added ? "added" : t.reason ? `cannot be added as it is: ${t.reason}` : null };
+}
 /**
- * THE PROJECT'S DATABASE'S TABLES, READ BY THE COMMAND ITSELF (the hands-on review of #451, item 15: `mason tables`
- * answered "Mason is not running", though it reads only Postgres): the database's catalog (preflight.ts
- * readSourceFacts, what mason start reads), each table as the run's state says it against the sources file
- * (sources.ts catalogTable). A file that cannot be read, or a database that does not answer, is said with why and the way out.
+ * THE PROJECT'S DATABASE'S CATALOG, READ BY THE COMMAND ITSELF (the hands-on review of #451, item 15: `mason tables`
+ * answered "Mason is not running", though it reads only Postgres): the sources file as the run reads it, and the
+ * database's catalog (preflight.ts readSourceFacts, what mason start reads) — what `mason tables` lists, and what `mason
+ * add` and `mason remove` check an edit against while Mason is down. A file that cannot be read, or a database that does
+ * not answer, is said with why and the way out.
  */
-async function databaseTables(p) {
+async function readCatalog(p) {
     const src = projectSource(p);
     if ("message" in src)
         return src;
+    const demo = p.config.demo === true;
     const fix = `change the URL where it is (${src.from}) when the database's password or host changed`;
     const parsed = parseSource(src.resolved);
     if ("problem" in parsed)
         return { message: `the database's URL (${src.from}): ${parsed.problem}`, code: "bad_source", fix };
-    const connected = await connectSource(parsed.source);
+    const connected = await connectSource(parsed.source, { demo });
     if ("failure" in connected) {
+        // the demo database's way out is its run (src/cli/demo.ts): its hint is the fix, mason start the next command
+        if (demo) {
+            return { message: `could not connect to ${maskedUrl(parsed.source.url)}: ${connected.failure.message}`, code: "unreachable",
+                fix: connected.failure.hints.join("; ") || "mason start hosts the demo database", next: [["mason start", "the demo database and Mason, in the background"]] };
+        }
         return { message: `could not connect to ${maskedUrl(parsed.source.url)}: ${connected.failure.message}`, code: "unreachable",
             ...(connected.failure.hints.length ? { why: connected.failure.hints.join("; ") } : {}), fix,
             next: [["mason doctor", "checks the machine and the project's database"]] };
@@ -598,7 +622,59 @@ async function databaseTables(p) {
     finally {
         connected.pg.close();
     }
-    return { database: parsed.source.database, name: src.name, file: src.file, tables: facts.tables.map((t) => catalogTable(t, src.tables.find((e) => e.table === t.source))) };
+    return { src, database: parsed.source.database, facts: facts.tables };
+}
+/** `mason tables` without the run: the database's tables, each as the run's state says it against the sources file
+ *  (sources.ts catalogTable). */
+async function databaseTables(p) {
+    const c = await readCatalog(p);
+    if ("message" in c)
+        return c;
+    return { database: c.database, name: c.src.name, file: c.src.file, tables: c.facts.map((t) => catalogTable(t, c.src.tables.find((e) => e.table === t.source))) };
+}
+/**
+ * MASON DOWN, `mason add` AND `mason remove` EDIT THE FILE THEMSELVES (the file is the list: `mason init && mason add
+ * orders && mason start` is a natural order, and `mason init demo` already writes entries before any run) — through
+ * the same check-and-write the run's command server calls (src/cli/source-edit.ts), against the catalog the command
+ * reads itself (`readCatalog`), so a refusal is worded alike from both. A run alive and silent (hung) still holds the
+ * file: refused, with mason stop as the way out, as is a run that came up since the command looked. Null once the
+ * failure is said.
+ */
+async function withoutRun(cmd, p, json) {
+    const st = await runState(p);
+    // a hung run is Mason running and not answering: FAILURE_CODES' unreachable
+    if (st.kind === "hung") {
+        failed(cmd, { ...asFailure(notAnswering(p, st.run)), code: "unreachable" }, { json });
+        return null;
+    }
+    if (st.kind === "up") {
+        failed(cmd, { message: `Mason started for ${p.config.name} while mason ${cmd} ran`, code: "refused", fix: `run mason ${cmd} again: it asks the run, which copies at once` }, { json });
+        return null;
+    }
+    const c = await readCatalog(p);
+    if ("message" in c) {
+        failed(cmd, c, { json });
+        return null;
+    }
+    return { db: { tables: c.facts, database: c.database, replication: changesOf(null, p.config.changes) === "replication" },
+        tables: c.facts.map((t) => catalogTable(t, c.src.tables.find((e) => e.table === t.source))), file: c.src.file,
+        edit: () => sourceToEdit(p.folder, p.root, () => projectSource(p)) };
+}
+function edited(f) {
+    try {
+        return { ok: f() };
+    }
+    catch (e) {
+        // a refusal is the edit's answer, said as the run's is; anything else is a bug, and goes on up
+        if (e instanceof Refusal)
+            return { status: e.status, error: e.message };
+        throw e;
+    }
+}
+/** The run's command server's answer, as an edit's (`Edited`): what `/api/pick` or `/api/remove` answered. */
+async function viaRun(run, route, body) {
+    const r = await callRun(run, "POST", route, body);
+    return r.status === 200 ? { ok: r.body } : { status: r.status, error: String(r.body.error) };
 }
 // ------------------------------------------------------------------ mason add
 const ADD_USAGE = `usage: mason add <table>… [--columns <column>,…] [--include <column>,…] [--key <column>,…] [--json]
@@ -616,8 +692,10 @@ const ADD_USAGE = `usage: mason add <table>… [--columns <column>,…] [--inclu
   it is written as exclude: [password_hash], since anyone with a user's password can read every copied column. Name
   one with --columns or --include to have it.
 
-  The copy starts at once; mason wait returns when it is done and the table is served. Adding a table again with
-  other columns changes its entry, and the table is copied again with them.
+  With Mason running the copy starts at once; mason wait returns when it is done and the table is served. Before
+  mason start (mason init && mason add orders && mason start) the entry is written, checked against the database as
+  the run checks it, and the copy begins at mason start. Adding a table again with other columns changes its entry,
+  and the table is copied again with them.
 
   --columns <a,b,…>   only these columns (one table at a time: the list is that table's)
   --include <a,b,…>   these columns as well as every other one — a column that looks like a secret, named on purpose
@@ -629,7 +707,8 @@ const ADD_USAGE = `usage: mason add <table>… [--columns <column>,…] [--inclu
                       exit 1 when a table could not be added
 `;
 export const ADD = {
-    needs: "run",
+    // the project, not the run: the sources file is the list, so a table is added before mason start as well as after
+    needs: "project",
     name: "add",
     summary: "copy tables into Mason, adding them to the sources file: mason add orders (--columns id,status: those only)",
     usage: ADD_USAGE,
@@ -672,94 +751,119 @@ export async function add(argv) {
     const specs = addSpecs(f.positionals, f.values.columns, f.values.include, f.values.key);
     if (typeof specs === "string")
         return failed("add", { message: specs, code: "usage", usage: ADD_USAGE }, { json });
-    const run = await runOr(ADD, json);
-    if (!run)
+    const where = await reach(ADD, json);
+    // (a state with no project never meets the need: reach said it)
+    if (where === null || where.project === null)
         return 1;
-    return guarded("add", json, async () => {
-        const s = await readState(run);
-        const results = [];
-        const added = [];
-        let file = s.source.file ?? null;
-        // the tables that could not be added, each with its reason and code: the command's failure, in the failure shape
-        const refused = [];
-        // A CHECKLIST, a line per table (it reads best as a list of completed actions): a spinner
-        // while it is added, ✔ with what was written, its notes under it; ✘ with the reason when it could not be
-        const st = styleOut();
-        const steps = stepRenderer({ line: out, live: !json && process.stdout.isTTY ? { write: (t) => { process.stdout.write(t); } } : null, style: st });
-        const note = (text) => { if (!json)
-            steps.print(st.dim(`    ${wrap(text, st.width, 4)}`)); };
-        const shown = (p) => { const rel = path.relative(process.cwd(), p); return rel.startsWith("..") ? p : rel; };
-        for (const spec of specs) {
-            const t = findTable(s.tables, spec.table);
-            // a table the database lacks is a failed line of the checklist, its reason under it, like a table Mason refused
-            if (!("table" in t)) {
-                refused.push({ table: spec.table, message: t.message, code: t.code });
-                results.push({ table: spec.table, error: t.message });
-                if (!json) {
-                    steps.begin(`Adding ${spec.table}`);
-                    steps.fail(`Adding ${spec.table}`);
-                    note(`${t.message}${t.fix ? `: ${t.fix}` : ""}${t.next?.length ? ` (${t.next[0][0]})` : ""}`);
-                }
-                continue;
-            }
-            if (!json)
-                steps.begin(`Adding ${t.table}`);
-            const r = await callRun(run, "POST", "/api/pick", { table: t.table, picked: true, columns: spec.columns, ...(spec.key ? { key: spec.key } : {}) });
-            if (r.status !== 200) {
-                refused.push({ table: t.table, message: String(r.body.error), code: r.status === 404 ? "not_found" : "refused" });
-                results.push({ table: t.table, error: String(r.body.error) });
-                if (!json) {
-                    steps.fail(`Adding ${t.table}`);
-                    note(String(r.body.error));
-                }
-                continue;
+    if (where.state === "up") {
+        // Mason up: the run adds it (the copy starts now, and the run's own re-read never races the file's write)
+        const run = where.run;
+        return guarded("add", json, async () => {
+            const s = await readState(run);
+            return addTables({ tables: s.tables, file: s.source.file ?? null,
+                pick: (table, columns, key) => viaRun(run, "/api/pick", { table, picked: true, columns, ...(key ? { key } : {}) }),
+                next: (n) => [["mason wait", `until ${n === 1 ? "its copy finishes" : "their copies finish"} (the copy has started)`], READY_STEPS[0]] }, specs, json);
+        });
+    }
+    // Mason down: the command writes the entry itself, checked as the run checks it; the copy begins at mason start
+    const down = await withoutRun("add", where.project, json);
+    if (down === null)
+        return 1;
+    return addTables({ tables: down.tables, file: down.file,
+        pick: async (table, columns, key) => edited(() => addEntry(down.edit(), down.db, table, columns, key)),
+        next: () => [["mason start", "Mason in the background, for this project: the copy of every added table begins"],
+            ["mason wait", "then, until every added table is copied and served"]] }, specs, json);
+}
+/** `mason add`'s checklist and answer, the same whichever way the tables are added (`AddWay`). */
+async function addTables(way, specs, json) {
+    const results = [];
+    const added = [];
+    let file = way.file;
+    // the tables that could not be added, each with its reason and code: the command's failure, in the failure shape
+    const refused = [];
+    // A CHECKLIST, a line per table (it reads best as a list of completed actions): a spinner
+    // while it is added, ✔ with what was written, its notes under it; ✘ with the reason when it could not be
+    const st = styleOut();
+    const steps = stepRenderer({ line: out, live: !json && process.stdout.isTTY ? { write: (t) => { process.stdout.write(t); } } : null, style: st });
+    const note = (text) => { if (!json)
+        steps.print(st.dim(`    ${wrap(text, st.width, 4)}`)); };
+    const shown = (p) => { const rel = path.relative(process.cwd(), p); return rel.startsWith("..") ? p : rel; };
+    for (const spec of specs) {
+        const t = findTable(way.tables, spec.table);
+        // a table the database lacks is a failed line of the checklist, its reason under it, like a table Mason refused
+        if (!("table" in t)) {
+            refused.push({ table: spec.table, message: t.message, code: t.code });
+            results.push({ table: spec.table, error: t.message });
+            if (!json) {
+                steps.begin(`Adding ${spec.table}`);
+                steps.fail(`Adding ${spec.table}`);
+                note(`${t.message}${t.fix ? `: ${t.fix}` : ""}${t.next?.length ? ` (${t.next[0][0]})` : ""}`);
             }
-            const b = r.body;
-            file = b.file;
-            results.push({ table: b.table, entry: b.entry, columns: b.columns, exclude: b.exclude, key: b.key, addedKey: b.addedKey, skippedSecrets: b.skippedSecrets, already: b.already });
-            added.push(b.table);
-            if (json)
-                continue;
-            const copies = b.columns === null ? (b.exclude.length ? `every column but ${b.exclude.join(", ")}` : "every column") : b.columns.join(", ");
-            steps.done(`Added ${t.table} to ${shown(b.file)}: ${copies}${b.key ? `, copied by ${b.key.join(", ")}` : ""}${b.already ? " (already so)" : ""}`);
-            if (b.addedKey.length)
-                note(`key added: ${b.addedKey.join(", ")} (a copy always has its key)`);
-            // a secret is readable by anyone with a user's password: left out, and said, with the way to include one
-            if (b.skippedSecrets.length)
-                note(`left out ${b.skippedSecrets.join(", ")}: ${b.skippedSecrets.length === 1 ? "it looks" : "they look"} like ${b.skippedSecrets.length === 1 ? "a secret" : "secrets"}, ` +
-                    `which anyone with a user's password could read (--include ${b.skippedSecrets[0]} adds it)`);
+            continue;
         }
-        const next = added.length ? [
-            ["mason wait", `until ${added.length === 1 ? "its copy finishes" : "their copies finish"} (the copy has started)`],
-            READY_STEPS[0],
-        ] : [];
-        if (refused.length) {
-            // A TABLE NOT ADDED IS THE COMMAND'S FAILURE, in the shape every failure has (found by the CLI session test of the private repo:
-            // exit 1 with no error, and nothing on stderr): what is wrong, each table's reason, and next — the added ones' too
-            const f = {
-                message: specs.length === 1 ? `${refused[0].table} was not added` : `${refused.length} of ${specs.length} tables were not added: ${refused.map((x) => x.table).join(", ")}`,
-                code: refused.every((x) => x.code === "not_found") ? "not_found" : refused.every((x) => x.code === "usage") ? "usage" : "refused",
-                why: refused.map((x) => specs.length === 1 ? x.message : `${x.table}: ${x.message}`).join("; "),
-                next: [...next, ["mason tables", "the database's tables, as this user reads them"]],
-            };
-            if (json) {
-                out(jsonText(ADD, { added: results, file, error: errorJson(f) }, f.next));
-                return 1;
+        if (!json)
+            steps.begin(`Adding ${t.table}`);
+        const r = await way.pick(t.table, spec.columns, spec.key);
+        if (!("ok" in r)) {
+            refused.push({ table: t.table, message: r.error, code: r.status === 404 ? "not_found" : "refused" });
+            results.push({ table: t.table, error: r.error });
+            if (!json) {
+                steps.fail(`Adding ${t.table}`);
+                note(r.error);
             }
-            return failed("add", f, { json: false });
+            continue;
         }
+        const b = r.ok;
+        file = b.file;
+        results.push({ table: b.table, entry: b.entry, columns: b.columns, exclude: b.exclude, key: b.key, addedKey: b.addedKey, skippedSecrets: b.skippedSecrets, already: b.already });
+        added.push(b.table);
         if (json)
-            out(jsonText(ADD, { added: results, file }, next));
-        else
-            out(endText({ next }, st));
-        return 0;
-    });
+            continue;
+        const l = addedLines(b, shown(b.file));
+        steps.done(l.line);
+        for (const x of l.notes)
+            note(x);
+    }
+    const next = added.length ? way.next(added.length) : [];
+    if (refused.length) {
+        // A TABLE NOT ADDED IS THE COMMAND'S FAILURE, in the shape every failure has (found by the CLI session test of the private repo:
+        // exit 1 with no error, and nothing on stderr): what is wrong, each table's reason, and next — the added ones' too
+        const f = {
+            message: specs.length === 1 ? `${refused[0].table} was not added` : `${refused.length} of ${specs.length} tables were not added: ${refused.map((x) => x.table).join(", ")}`,
+            code: refused.every((x) => x.code === "not_found") ? "not_found" : refused.every((x) => x.code === "usage") ? "usage" : "refused",
+            why: refused.map((x) => specs.length === 1 ? x.message : `${x.table}: ${x.message}`).join("; "),
+            next: [...next, ["mason tables", "the database's tables, as this user reads them"]],
+        };
+        if (json) {
+            out(jsonText(ADD, { added: results, file, error: errorJson(f) }, f.next));
+            return 1;
+        }
+        return failed("add", f, { json: false });
+    }
+    if (json)
+        out(jsonText(ADD, { added: results, file }, next));
+    else
+        out(endText({ next }, st));
+    return 0;
+}
+/** What `mason add` prints for a table added: its line (✔ …), then its notes under it (the web page says the same,
+ *  src/web/app.js; tests/web-page.test.ts holds the two equal). `file` is the sources file as the reader is shown it. */
+export function addedLines(b, file) {
+    const copies = b.columns === null ? (b.exclude.length ? `every column but ${b.exclude.join(", ")}` : "every column") : b.columns.join(", ");
+    const s = b.skippedSecrets;
+    return { line: `Added ${b.table} to ${file}: ${copies}${b.key ? `, copied by ${b.key.join(", ")}` : ""}${b.already ? " (already so)" : ""}`, notes: [
+            ...(b.addedKey.length ? [`key added: ${b.addedKey.join(", ")} (a copy always has its key)`] : []),
+            // a secret is readable by anyone with a user's password: left out, and said, with the way to include one
+            ...(s.length ? [`left out ${s.join(", ")}: ${s.length === 1 ? "it looks" : "they look"} like ${s.length === 1 ? "a secret" : "secrets"}, ` +
+                    `which anyone with a user's password could read (--include ${s[0]} adds it)`] : []),
+        ] };
 }
 // ------------------------------------------------------------------ mason remove
 const REMOVE_USAGE = `usage: mason remove <table>… [--json]
 
   Takes tables out of the project: each one's entry in the sources file (mason/sources/<name>.yml) is removed, the
-  rest of the file as it was. Mason then stops copying it and drops its copy.
+  rest of the file as it was. With Mason running it stops copying the table and drops its copy at once; with Mason
+  stopped, a copy an earlier run made is dropped at the next mason start.
 
     mason remove customers
     mason remove customers billing.invoices     several at once
@@ -767,7 +871,8 @@ const REMOVE_USAGE = `usage: mason remove <table>… [--json]
   --json   as data: { removed (the tables, schema.table), file (the sources file), next }
 `;
 export const REMOVE = {
-    needs: "run",
+    // the project, not the run, as mason add
+    needs: "project",
     name: "remove",
     summary: "take tables out of the sources file: mason remove customers (its copy is dropped)",
     usage: REMOVE_USAGE,
@@ -782,30 +887,53 @@ export async function remove(argv) {
     const names = [...new Set(f.positionals)];
     if (!names.length)
         return failed("remove", { message: "name a table: mason remove customers (mason status lists the added ones)", code: "usage", usage: REMOVE_USAGE }, { json });
-    const run = await runOr(REMOVE, json);
-    if (!run)
+    const where = await reach(REMOVE, json);
+    // (a state with no project never meets the need: reach said it)
+    if (where === null || where.project === null)
         return 1;
-    return guarded("remove", json, async () => {
-        // the run's own removal (src/cli/run-server.ts removeTables): one path, so nothing can disagree with it
-        const r = await callRun(run, "POST", "/api/remove", { tables: names });
-        if (r.status !== 200) {
-            const message = String(r.body.error);
-            return failed("remove", { message: `${names.join(", ")} ${names.length === 1 ? "was" : "were"} not removed`, code: r.status === 404 ? "not_found" : r.status === 400 ? "usage" : "refused", why: message,
-                next: [["mason status", "the tables added"]] }, { json });
-        }
-        const b = r.body;
-        const next = [["mason status", "the tables left"]];
-        if (json) {
-            out(jsonText(REMOVE, { removed: b.removed, file: b.file }, next));
-            return 0;
-        }
-        const rel = path.relative(process.cwd(), b.file);
-        out(reportText({ headline: `Removed ${b.removed.join(", ")}`, details: [["from", rel.startsWith("..") ? b.file : rel]],
-            tips: [`Mason stops copying ${b.removed.length === 1 ? "it" : "them"} and drops ${b.removed.length === 1 ? "its copy" : "their copies"}`], next }, styleOut()));
+    if (where.state === "up") {
+        // Mason up: the run removes it and drops the copy at once (src/cli/run-server.ts removeTables)
+        const run = where.run;
+        return guarded("remove", json, async () => removedAnswer(await viaRun(run, "/api/remove", { tables: names }), names, true, json));
+    }
+    // Mason down: the command cuts the entries itself, checked as the run checks them (src/cli/source-edit.ts removeEntries)
+    const down = await withoutRun("remove", where.project, json);
+    if (down === null)
+        return 1;
+    return removedAnswer(edited(() => removeEntries(down.edit(), down.db, names)), names, false, json);
+}
+/** `mason remove`'s answer, the same whichever way the entries were cut; `running`: Mason is up, and dropped the copies. */
+function removedAnswer(r, names, running, json) {
+    if (!("ok" in r)) {
+        return failed("remove", { message: `${names.join(", ")} ${names.length === 1 ? "was" : "were"} not removed`, code: r.status === 404 ? "not_found" : r.status === 400 ? "usage" : "refused", why: r.error,
+            next: [["mason status", "the tables added"]] }, { json });
+    }
+    const b = r.ok;
+    const next = running ? [["mason status", "the tables left"]]
+        : [["mason start", "Mason in the background, for this project: it copies the tables left"], ["mason status", "the tables left"]];
+    if (json) {
+        out(jsonText(REMOVE, { removed: b.removed, file: b.file }, next));
         return 0;
-    });
+    }
+    const rel = path.relative(process.cwd(), b.file);
+    out(reportText({ ...removedReport(b.removed, rel.startsWith("..") ? b.file : rel, { running }), next }, styleOut()));
+    return 0;
+}
+/** What `mason remove` prints for the tables removed, `file` the sources file as the reader is shown it (the web page
+ *  says the same, src/web/app.js; tests/web-page.test.ts holds the two equal). */
+export function removedReport(removed, file, o = {}) {
+    const one = removed.length === 1;
+    return { headline: `Removed ${removed.join(", ")}`, details: [["from", file]],
+        // Mason down (the web page always has a run): a copy an earlier run made is dropped by the next start's sync
+        tips: [o.running === false ? `a copy an earlier run made of ${one ? "it" : "them"} is dropped at the next mason start`
+                : `Mason stops copying ${one ? "it" : "them"} and drops ${one ? "its copy" : "their copies"}`] };
 }
 // ------------------------------------------------------------------ mason wait
+/** An added table as mason wait --json says it: its copy, its error, and how it is kept current, as the run's state has
+ *  them (mason status --json's own fields, never derived again here) */
+export function waitTable(t) {
+    return { table: t.table, copy: t.copy, error: t.error, ...(t.unsynced ? { unsynced: t.unsynced } : {}), ...(t.kept ? { kept: t.kept } : {}) };
+}
 const WAIT_USAGE = `usage: mason wait [--timeout <seconds>] [--json]
 
   Waits until every added table is copied and served, showing every added table on a line of its own: 100% for the
@@ -815,9 +943,11 @@ const WAIT_USAGE = `usage: mason wait [--timeout <seconds>] [--json]
     mason wait --timeout 3600     a large table: wait up to an hour
 
   --timeout <seconds>   how long to wait (default 600); the copy goes on after, and mason wait again picks it up
-  --json                as data, once it ends: { ready, failed, waiting, timedOut, tables: [{ table, copy, error }]
-                        (copy: { phase, rowsCopied, progress: the chunks done, reading and for how long, the rate, the
-                        seconds left, while its chunks are read }),
+  --json                as data, once it ends: { ready, failed, waiting, timedOut, tables: [{ table, copy, error,
+                        unsynced, kept }] (copy: { phase, rowsCopied, progress: the chunks done, reading and for how
+                        long, the rate, the seconds left, while its chunks are read }; unsynced: { reason, asOf }
+                        and kept as mason status --json says them — kept's pending, when it applies, says why the
+                        copy is not kept current now, its phase included),
                         stream (replication mode: where the stream is, as mason status --json says it), error (on a
                         failure or a timeout: { code, message, next }), next }
 
@@ -889,7 +1019,7 @@ export async function wait(argv) {
                         next: [["mason wait", "keep waiting (--timeout <seconds> for longer)"], ["mason status", "what Mason is doing"]] }
                     : null;
             if (json && (done || failure)) {
-                out(jsonText(WAIT, { ...r, timedOut: !done, tables: picked.map((t) => ({ table: t.table, copy: t.copy, error: t.error, ...(t.unsynced ? { unsynced: t.unsynced } : {}) })),
+                out(jsonText(WAIT, { ...r, timedOut: !done, tables: picked.map(waitTable),
                     ...(s.stream ? { stream: s.stream } : {}), ...(failure ? { error: errorJson(failure) } : {}) }, failure ? failure.next ?? [] : readyNext));
             }
             // the block as it ends, too: every table at 100% beside Ready (when the last change was not printed yet)
@@ -1133,11 +1263,13 @@ export async function stop(argv) {
     const recorded = readProject(run.root);
     const replicating = isProject(recorded) && recorded.config.changes === "replication";
     const named = isProject(recorded) ? recorded.config.publication ?? null : null;
+    // a demo project's database (src/cli/demo.ts) stays too, as the copy does: said where a person reads the stop
+    const demo = isProject(recorded) && recorded.config.demo === true;
     if (json) {
         out(jsonText(STOP, { stopped: [run.name] }, next));
         return 0;
     }
-    out(reportText({ headline: `Stopped ${run.name}`, details: [["kept", "its copy of the data and its state"],
+    out(reportText({ headline: `Stopped ${run.name}`, details: [["kept", `its copy of the data and its state${demo ? ` and the demo database (${STATE_DIR}/${DEMO_DIR})` : ""}`],
             ...(replicating ? [["slot", `its replication slot stays on the database, holding WAL until the next mason start (mason destroy drops it)`],
                 ["publication", named ? `${named}, its owner's: read as it is, never altered (mason destroy leaves it)` : "Mason's own (mason destroy drops it)"]] : [])] }));
     out(endText({ next }));