@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/cli/serve.js

@@ -0,0 +1,301 @@
+/**
+ * `mason serve` (deploying quickly to a server — one's own or a managed platform — must be as easy as possible,
+ * wherever the Postgres database is): the DuckDB run of `mason start --attach` (src/cli/dev.ts), for a server or a
+ * container. Whatever a platform gives a process, and nothing else:
+ *
+ *   - ITS SETTINGS FROM THE ENVIRONMENT (`serveSettings`): the database's URL, the API key the tokens are minted with,
+ *     the project folder (the team's `mason/`, committed: its sources file names the database and the tables copied,
+ *     its URL `${DATABASE_URL}` from this environment) and the data folder.
+ *     Nothing is asked; every setting missing or wrong is said at once, each with what to set (one report).
+ *   - ITS STATE ON ONE VOLUME: the data folder's `.mason/` — the config this command writes from the environment at
+ *     every start (`serveConfig`), the DuckDB file, the logs. A restart resumes the copy; a new volume copies again.
+ *   - IN THE FOREGROUND, ITS LOG ON STDOUT: a container's log is its stdout. A run that cannot start exits 1, so the
+ *     platform restarts it; there is no supervisor of its own (src/cli/supervise.ts is `mason start`'s).
+ *   - A HEALTH ENDPOINT (`healthBody`): `GET /healthz` on MASON_HEALTH_PORT, 503 while it starts and stops, 200 once it
+ *     answers. It needs no credential, so it names nothing of the database: counts only.
+ *   - A CLEAN STOP ON SIGTERM: the run's own stop (a copy in flight interrupted and rolled back, DuckDB closed).
+ *
+ * The commands beside it work as on a laptop, in the data folder: `docker compose exec mason mason add orders`.
+ */
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as path from "node:path";
+import { failed, parseCommand } from "./command.js";
+import { dev } from "./dev.js";
+import { parseSource } from "./preflight.js";
+import { NAME_RE, newConfig, readProject, STATE_DIR, writeConfig } from "./project.js";
+import { newSourceText, OLD_TABLES_DIR, parseSourceText, readSource, sourceFileNames, sourceNameFor, sourcesDir } from "./sources.js";
+import { appEnvValue } from "../lib/dotenv.js";
+import { version } from "./version.js";
+export const SERVE = {
+    name: "serve",
+    summary: "run Mason on a server or in a container, in the foreground, configured by the environment",
+    usage: `usage: mason serve [--json]
+
+  Runs Mason as mason start --attach does, for a server or a container: nothing asked, its settings from the
+  environment, its state in one folder (a volume), its log on stdout, GET /healthz for the platform's health check,
+  and a clean stop on SIGTERM. The tables it copies are the ones the project folder's sources file names
+  (sources/<name>.yml): make it with mason init and mason add on a laptop and commit it, or with mason add beside the
+  running server. A project folder with no sources file gets one, url: \${DATABASE_URL}, with no table yet.
+
+    DATABASE_URL=postgres://mason:…@db.internal:5432/app MASON_API_KEY=… mason serve
+    docker compose exec mason mason add public.orders     beside it, in its container
+
+  Settings (the environment):
+    DATABASE_URL            the database to copy from, as the sources file's url: \${DATABASE_URL} names it (the variable
+                            the file names is required); read-only: SELECTs, or a replication slot
+    MASON_API_KEY           what the users' passwords are made with (mason user add), at least 32 characters (required)
+    MASON_PROJECT           the project folder: sources/, mason.yml (default ./mason)
+    MASON_DATA              the folder whose .mason/ holds the copy and the state: the volume (default .)
+    MASON_NAME              the project's name, the database name clients connect to (default mason)
+    MASON_CHANGES           poll (SELECTs, the default) or replication (the change log; PG_PUBLICATION names one)
+    MASON_HEALTH_PORT       /healthz's port (default 4140), on MASON_HEALTH_HOST (default 0.0.0.0)
+    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     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)
+
+  --json   a refusal to start as data: { error, next }; once it serves, its output is its log
+
+  Exit status: 0 stopped by SIGTERM or SIGINT; 1 it could not start (said); 2 a wrong command line.
+`,
+    options: { json: { type: "boolean", default: false } },
+    json: ["next"],
+};
+const MIN_API_KEY = 32;
+/** THE SETTINGS, OR EVERY ONE MISSING OR WRONG AT ONCE: a platform's deploy is slow, and one variable a deploy wastes it. */
+export function serveSettings(env, cwd) {
+    const wrong = [];
+    const project = path.resolve(cwd, env.MASON_PROJECT || "mason");
+    const data = path.resolve(cwd, env.MASON_DATA || ".");
+    // the database's URL, with the rest: the variable the sources file names (DATABASE_URL for the one a serve writes)
+    wrong.push(...urlSettingProblems(project, data, env));
+    const apiKey = env.MASON_API_KEY ?? "";
+    if (!apiKey)
+        wrong.push("MASON_API_KEY is not set: what the users' passwords are made with (mason user add; openssl rand -hex 24 makes one)");
+    else if (apiKey.length < MIN_API_KEY)
+        wrong.push(`MASON_API_KEY is ${apiKey.length} characters: at least ${MIN_API_KEY}, as openssl rand -hex 24 makes`);
+    const name = env.MASON_NAME || "mason";
+    if (!NAME_RE.test(name))
+        wrong.push(`MASON_NAME=${JSON.stringify(name)} is not a project name: lower case letters, digits, - and _, at most 48`);
+    const changes = env.MASON_CHANGES || null;
+    if (changes !== null && changes !== "poll" && changes !== "replication")
+        wrong.push(`MASON_CHANGES=${JSON.stringify(changes)}: poll or replication`);
+    const selfSigned = env.MASON_PG_SELF_SIGNED_TLS || "0";
+    if (selfSigned !== "0" && selfSigned !== "1")
+        wrong.push(`MASON_PG_SELF_SIGNED_TLS=${JSON.stringify(selfSigned)}: 1, or 0 (the default)`);
+    const portText = env.MASON_HEALTH_PORT || "4140";
+    const port = Number(portText);
+    if (!/^\d+$/.test(portText) || port < 1 || port > 65_535)
+        wrong.push(`MASON_HEALTH_PORT=${JSON.stringify(portText)}: a port number, 1-65535`);
+    if (wrong.length) {
+        return { message: `${wrong.length === 1 ? "a setting is" : `${wrong.length} settings are`} missing or wrong: ${wrong.join("; ")}`, code: "bad_config",
+            why: "mason serve reads its settings from the environment, and asks nothing",
+            fix: "set them in the environment (a compose file's .env, the platform's variables), then start it again",
+            next: [["mason serve --help", "every setting, with its default"]] };
+    }
+    return {
+        name, apiKey, changes: changes, selfSignedTls: selfSigned === "1",
+        project, data,
+        health: { host: env.MASON_HEALTH_HOST || "0.0.0.0", port },
+    };
+}
+/**
+ * THE DATABASE'S URL AS A SETTING (the review of the sources file: an unset URL was found only after the other
+ * settings passed, two deploys for two variables): the variable the project's sources file names — DATABASE_URL when it
+ * has none yet (serveSource writes one naming it) — set and a postgres:// URL, read from the environment first (a .env in
+ * the data folder never overrides the platform's). The file's own mistakes are serveSource's, on its own report.
+ */
+function urlSettingProblems(project, data, env) {
+    const names = sourceFileNames(project);
+    let variable = "DATABASE_URL";
+    if (names.length === 0) {
+        if (fs.existsSync(path.join(project, OLD_TABLES_DIR)))
+            return []; // refused by readSource, with the way out
+        if (!env.DATABASE_URL)
+            return [`DATABASE_URL is not set, and the project folder (${project}) has no sources file to name the database another way`];
+    }
+    else if (names.length === 1) {
+        const file = path.join(sourcesDir(project), names[0]);
+        let text;
+        // a file that cannot be read is serveSource's to say (readSource), with the file and the error, on its own report
+        try {
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            return [];
+        }
+        const parsed = parseSourceText(text, names[0].replace(/\.ya?ml$/, ""), file);
+        if ("problems" in parsed || "literal" in parsed.url)
+            return [];
+        variable = parsed.url.env;
+    }
+    else
+        return [];
+    const found = appEnvValue(data, variable, env, { shellFirst: true });
+    if (found === null)
+        return [`${variable} is not set: the database to copy from, as the sources file's url: \${${variable}} names it`];
+    const p = parseSource(found.value);
+    return "problem" in p ? [`${variable}: ${p.problem}`] : [];
+}
+/**
+ * THE CONFIG A SERVE RUNS ON, written from its settings at every start, over what the runs before recorded (the server
+ * the copy was taken from, the publication, the certificate): the environment is the operator's, the rest the run's. A
+ * project `mason init` made is a developer's and is never taken over; a name that moved would be another slot and
+ * another database name over the same copy, so it is refused.
+ */
+export function serveConfig(s, existing) {
+    const dir = path.join(s.data, STATE_DIR);
+    if (existing === null) {
+        const config = { ...newConfig(s.name, s.project, true), apiKey: s.apiKey, served: true };
+        return { config, said: [`a new copy in ${dir}`] };
+    }
+    if ("broken" in existing) {
+        return { message: `the state in ${dir} cannot be read: ${existing.file}: ${existing.broken}`, code: "bad_config",
+            fix: `MASON_DATA names a folder of its own for mason serve; move ${dir} aside to copy again` };
+    }
+    const was = existing.config;
+    if (was.served !== true) {
+        return { message: `${dir} is a project mason init made, and mason serve keeps its own state`, code: "refused",
+            why: "its config is a developer's (its database, its key), which a serve would overwrite from the environment",
+            fix: "point MASON_DATA at an empty folder (the volume), or run mason start here" };
+    }
+    if (was.name !== s.name) {
+        return { message: `the copy in ${dir} is the project ${was.name}, and MASON_NAME says ${s.name}`, code: "refused",
+            why: "the name is the database name clients connect to and names the replication slot: another name over the same copy is another project",
+            fix: `set MASON_NAME=${was.name} again, or give the new name a new MASON_DATA (an empty volume), which copies again` };
+    }
+    const said = [`the copy in ${dir}, resumed`];
+    if (was.apiKey !== s.apiKey)
+        said.push("MASON_API_KEY changed: every mason user is removed (mason user add each again)");
+    // the source is the sources file's; a database restored elsewhere, or another one, is the run's to see (sourceMove)
+    const { source: _old, ...kept } = was;
+    return { config: { ...kept, apiKey: s.apiKey, folder: s.project, remote: true, served: true }, said };
+}
+/**
+ * THE PROJECT FOLDER'S SOURCES FILE, for a serve: one there is checked as the run reads it (src/cli/sources.ts
+ * readSource: its URL resolved from this environment, every mistake on one report); a folder with none gets the file
+ * `mason init` writes, `url: ${DATABASE_URL}` and no table, when DATABASE_URL is set — else what to set is said.
+ */
+export function serveSource(s, env) {
+    let wrote = null;
+    if (sourceFileNames(s.project).length === 0 && !fs.existsSync(path.join(s.project, OLD_TABLES_DIR))) {
+        const url = env.DATABASE_URL ?? "";
+        if (!url) {
+            return { message: "DATABASE_URL is not set, and the project folder has no sources file to name the database another way", code: "bad_config",
+                fix: "set DATABASE_URL=postgres://user:password@host:5432/app (the sources file mason init writes names it), or mount the project folder with its sources/ (MASON_PROJECT)",
+                next: [["mason serve --help", "every setting, with its default"]] };
+        }
+        const p = parseSource(url);
+        const file = path.join(sourcesDir(s.project), `${sourceNameFor("source" in p ? p.source.database : "")}.yml`);
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, newSourceText());
+        }
+        catch (e) {
+            return { message: `the project folder has no sources file, and one cannot be written: ${e.message}`, code: "refused",
+                fix: `MASON_PROJECT names the project folder (sources/, mason.yml): mount it there with its sources file, or make ${file} in it` };
+        }
+        wrote = file;
+    }
+    const r = readSource(s.project, s.data, env, { shellFirst: true });
+    return "message" in r ? r : { wrote };
+}
+/**
+ * /healthz's answer: 200 once the run answers, whatever its copies are doing (a table still copying, or one that failed,
+ * leaves the rest served: the counts say it); 503 while it starts and stops. Counts only, never a table's name: the
+ * endpoint takes no credential.
+ */
+export function healthBody(state, startedAt, now = Date.now()) {
+    const base = { status: state.phase, version: version(), uptimeSeconds: Math.floor((now - startedAt) / 1000) };
+    if (state.phase !== "ready")
+        return { status: 503, body: base };
+    const counts = { total: 0, copied: 0, copying: 0, waiting: 0, failed: 0 };
+    for (const t of state.tables()) {
+        counts.total++;
+        counts[t.phase]++;
+    }
+    return { status: 200, body: { ...base, tables: counts } };
+}
+/** The health endpoint: GET /healthz, nothing else. */
+export function healthServer(state, startedAt) {
+    return http.createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://health");
+        if (url.pathname !== "/healthz") {
+            res.writeHead(404, { "content-type": "text/plain" }).end("GET /healthz\n");
+            return;
+        }
+        if (req.method !== "GET" && req.method !== "HEAD") {
+            res.writeHead(405, { allow: "GET, HEAD" }).end();
+            return;
+        }
+        const h = healthBody(state(), startedAt);
+        res.writeHead(h.status, { "content-type": "application/json", "cache-control": "no-store" }).end(`${JSON.stringify(h.body)}\n`);
+    });
+}
+const say = (m) => { process.stdout.write(`${m}\n`); };
+export async function serve(argv) {
+    const f = parseCommand(SERVE, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    if (f.positionals.length)
+        return failed("serve", { message: "it takes no arguments: its settings are the environment's", code: "usage", usage: SERVE.usage }, { json });
+    const s = serveSettings(process.env, process.cwd());
+    if ("message" in s)
+        return failed("serve", s, { json });
+    // the project folder: its sources file is the list of what is copied, one with no table written when there is none
+    const made = serveSource(s, process.env);
+    if ("message" in made)
+        return failed("serve", made, { json });
+    const c = serveConfig(s, readProject(s.data));
+    if ("message" in c)
+        return failed("serve", c, { json });
+    try {
+        writeConfig(path.join(s.data, STATE_DIR), c.config);
+    }
+    catch (e) {
+        return failed("serve", { message: `the state cannot be written to ${path.join(s.data, STATE_DIR)}: ${e.message}`, code: "refused",
+            fix: "MASON_DATA names a folder this user can write: the volume's mount point" }, { json });
+    }
+    const startedAt = Date.now();
+    let state = { phase: "starting" };
+    const health = healthServer(() => state, startedAt);
+    const listening = await new Promise((resolve) => {
+        health.once("error", resolve);
+        health.listen(s.health.port, s.health.host, () => resolve(null));
+    });
+    if (listening !== null) {
+        return failed("serve", { message: `the health endpoint cannot listen on ${s.health.host}:${s.health.port}: ${listening.message}`, code: "refused",
+            fix: "MASON_HEALTH_PORT names a port free on this machine" }, { json });
+    }
+    say(`mason serve: ${s.name}, the project in ${s.project}, the state in ${path.join(s.data, STATE_DIR)}`);
+    if (made.wrote)
+        say(`  wrote ${made.wrote}: the database (url: \${DATABASE_URL}), no table yet (mason add beside it adds one)`);
+    for (const l of c.said)
+        say(`  ${l}`);
+    say(`  health    http://${s.health.host}:${s.health.port}/healthz`);
+    // the run reads the project of the folder it runs in (src/cli/project.ts): the data folder's
+    process.chdir(s.data);
+    let code;
+    try {
+        code = await dev({ port: 4039, version: version(), changes: s.changes, publication: null, selfSignedTls: s.selfSignedTls,
+            serve: { log: say, ready: (run) => { state = { phase: "ready", tables: run.tables }; }, stopping: () => { state = { phase: "stopping" }; } } });
+    }
+    finally {
+        // a platform's health check may hold a keep-alive connection open, which close() alone would wait for
+        health.closeAllConnections();
+        await new Promise((resolve) => health.close(() => resolve()));
+    }
+    if (code !== 0)
+        return failed("serve", { message: "Mason did not start: what stopped it is said above", code: "failed",
+            fix: "fix what it says, then start it again (a platform restarts it by itself)" }, { json: false });
+    return 0;
+}

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 };
+}