@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/lib/project-version.js

@@ -7,10 +7,11 @@
  *
  * Before 1.0 a minor version may change the project's format with no compatibility (CLAUDE.md "No backwards
  * compatibility before v1.0"), so a project written for 0.5 and run by 0.6 would fail on whatever key moved, in words
- * that never say the versions differ. The pin turns that into one refusal that does: the image of the ClickHouse stack
- * this was cut from refused to start on a project of another minor version, or of a newer patch than itself
- * (`imagePinProblem` below), and `mason init` / `mason start` refuse a CLI that is (src/cli/pin.ts). The way out is
- * always the same pair: run the version the project names, or read the release notes and move the pin.
+ * that never say the versions differ. The pin turns that into one refusal that does: the image refuses to start on a
+ * project of another release line, or of a newer patch than itself (`imagePinProblem` below), and the mason command
+ * refuses one too (src/cli/pin.ts: `mason init`, `mason start`, and `mason serve` run from the package). ONE rule (`pinProblem`), in
+ * each reader's words. The way out is always the same pair: run the version the project names, or read the release notes
+ * and move the pin.
  *
  * A build that is no release (`dev` from a checkout, `main-<sha>` from main) checks nothing: it has no version to hold
  * a project to. A project with no `mason.yml` (made by an older `mason init`) is unpinned and runs; `mason start` writes one.
@@ -40,37 +41,36 @@ export function sameLine(a, b) {
 const older = (a, b) => a.major !== b.major ? a.major < b.major : a.minor !== b.minor ? a.minor < b.minor : a.patch < b.patch;
 /**
  * Why `running` (what reads the project: the image, or the CLI) may not run a project pinned to `pin`, or null.
- * Allowed: the same release line, at the pin's patch or later. `what` names the reader in the message ("the mason
- * image", "this mason command"); `run` says how to run the pinned version instead.
+ * Allowed: the same release line, at the pin's patch or later.
  */
-export function pinProblem(pin, running, file, what, run) {
+function pinProblem(pin, running, file, reader) {
     if (sameLine(pin, running) && !older(running, pin))
         return null;
-    const p = versionText(pin), r = versionText(running);
+    const p = versionText(pin), r = versionText(running), { what } = reader, run = reader.run(p);
     if (sameLine(pin, running)) {
-        return `${file} pins Mason ${p}, and ${what} is ${r}, older than it: the project may use a fix or a key ${r} does not have. ${run}`;
+        return { problem: `${file} pins Mason ${p}, and ${what} is ${r}, older than it: the project may use a fix or a key ${r} does not have`, ways: [run] };
     }
     const line = pin.major > 0 ? `${pin.major}.x` : `${pin.major}.${pin.minor}.x`;
     return older(running, pin)
-        ? `${file} pins Mason ${p}, and ${what} is ${r}: the project is written for a newer Mason. ${run}`
-        : `${file} pins Mason ${p}, and ${what} is ${r}, a newer release line than ${line}, which may read the project differently. ` +
-            `${run} Or upgrade the project: read the release notes of every version after ${p} up to ${r} (their "Before you upgrade"), ` +
-            `change what they say, then set version: ${r} in ${path.basename(file)}.`;
+        ? { problem: `${file} pins Mason ${p}, and ${what} is ${r}: the project is written for a newer Mason`, ways: [run] }
+        : { problem: `${file} pins Mason ${p}, and ${what} is ${r}, a newer release line than ${line}, which may read the project differently`,
+            ways: [run, `upgrade the project: read the release notes of every version after ${p} up to ${r} (their "Before you upgrade"), ` +
+                    `change what they say, then set version: ${r} in ${path.basename(file)}`] };
 }
 /**
- * The image's check, as the ClickHouse stack's service ran it at its start: the project's pin against the image's
- * MASON_VERSION, or null.
- * An image that is no release (`dev`, `main-<sha>`) holds no project to a version.
+ * THE ONE CHECK: the project's pin against the version of what reads it, or null. A build that is no release (`dev`,
+ * `main-<sha>`) holds no project to a version, and reads no mason.yml.
  */
-export function imagePinProblem(project, imageVersion) {
-    const running = parseVersion(imageVersion ?? "");
+export function projectPinProblem(project, version, reader) {
+    const running = parseVersion(version);
     if (running === null)
         return null;
     const read = readPin(project);
     if ("problem" in read)
-        return read.problem;
-    if (read.pin === null)
-        return null;
-    const p = versionText(read.pin);
-    return pinProblem(read.pin, running, read.file, "this mason image", `Run the image the project names (ghcr.io/embeddable-hq/mason-data:${p}).`);
+        return { problem: read.problem, ways: [] };
+    return read.pin === null ? null : pinProblem(read.pin, running, read.file, reader);
+}
+/** The image's check: the words of someone running a container. */
+export function imagePinProblem(project, imageVersion) {
+    return projectPinProblem(project, imageVersion, { what: "this mason image", run: (p) => `run the image the project names (ghcr.io/embeddable-hq/mason-data:${p})` });
 }

package/dist/src/lib/secret-mask.js

@@ -0,0 +1,142 @@
+/**
+ * AN ERROR'S WORDS, AS MASON REPEATS THEM (issue 599: the engine's error repeated the connection string, `password='…'`
+ * included, into the log, the ledger, `mason status` and the web page).
+ *
+ * WHERE THE PASSWORD CAN STILL REACH AN ERROR decides how wide this is. The engine is given the password in ONE
+ * statement, the TEMPORARY SECRET (src/duck/sync.ts `sourceSecretSql`), whose own error is never repeated (its code
+ * alone); the ATTACH's path holds no credential (`attachPath`), so the extension's `Unable to connect to Postgres at
+ * "<path>"` cannot hold it; the sync's own Postgres client sends it only inside its auth messages (src/cdc/pg-wire.ts),
+ * never in a string. So no error the sync meets holds the password, and the one form a regression would bring back is
+ * the one the old string leaked: a libpq `password=` keyword's value. That alone is masked.
+ *
+ * NEVER A SUBSTRING OF THE PASSWORD (the reviews of PR 620): an error's words carry identifiers — a table's name, the
+ * user's, the database's, a slot's, a row's value — and a mask that cut the password out of them showed where it sat
+ * (`public.****_archive` under `orders2024`, `for user "****"` under a password equal to the user's name), while a
+ * branch matching the words flipped (a catch-up's wider numeric, a ROLLBACK's `no transaction is active`). A
+ * `password=` value is no identifier, so masking it shows nothing of the password and changes no word a branch reads;
+ * and no branch reads these words at all: a decision reads `messageOf`, the raw words, which are never shown.
+ * tests/secret-mask.test.ts holds both rules over src/duck/sync.ts and src/duck/stream.ts.
+ */
+/** What a masked value reads as. */
+export const MASKED = "****";
+/** libpq's `password=` keyword and its value: quoted (`'…'`, a `\` escaping the next character, to the closing quote
+ *  or the text's end, a `\` that ends the text included: issue 621, a text cut there was returned whole) or bare (to the
+ *  next space or quote); any case, spaces allowed around the `=` as libpq allows */
+const PASSWORD_KEYWORD = /\b(password\s*=\s*)(?:'(?:[^'\\]|\\[\s\S]?)*(?:'|$)|[^\s'"]+)/gi;
+/** `text` with every `password=` keyword's value masked, and nothing else changed: the leaked form alone, safe for any
+ *  stored free text (an error's words, the ledger read back, the scrub at open). */
+export function maskPasswordKeyword(text) {
+    return text.replace(PASSWORD_KEYWORD, (_m, key) => `${key}${MASKED}`);
+}
+/** The keyword with its value not begun at the text's end (`password`, `password =`): what follows on the next line may
+ *  be its value, as libpq allows a newline among the spaces around the `=` */
+const KEYWORD_OPEN = /\bpassword\s*(?:=\s*)?$/i;
+/** Whether a quoted value (its opening `'` first) has its closing quote, by the keyword's own escapes */
+function closed(value) {
+    let escaped = false;
+    for (let i = 1; i < value.length; i++) {
+        const c = value[i];
+        if (escaped)
+            escaped = false;
+        else if (c === "\\")
+            escaped = true;
+        else if (c === "'")
+            return true;
+    }
+    return false;
+}
+/**
+ * A TEXT READ A LINE AT A TIME, MASKED AS `maskPasswordKeyword` MASKS IT WHOLE (issue 621: a log file an older Mason
+ * wrote, read by `mason logs`, holds the leaked form in its lines): the same keyword, the same value, masked the same way,
+ * and nothing else changed — never a substring of the password (the reviews of PR 620: an identifier holding it is
+ * structure, and a mask cut into it showed where the password sat).
+ *
+ * A LINE IS ITS UNIT, AND AN ENTRY ITS BOUND. A log entry is a line at the margin and the indented lines under it
+ * (src/lib/log.ts `textEntry`), so a value can run on past its line only inside its entry: a quote open at a line's end
+ * masks the next indented lines to its closing quote (a password holding a newline), and a keyword at a line's end
+ * (`password`, `password =`) takes its value from the next indented line. A line at the margin, or a blank one, starts
+ * afresh: a quote an older Mason's line left open (a message cut off) masks its own entry, never the rest of the file.
+ * Each line's answer is decided by it and the lines before it, so a reader releases a line as soon as it has it whole,
+ * whatever its own chunks (src/lib/log-read.ts), and the answer is the same for every way the file is cut.
+ */
+export class PasswordLineMask {
+    /** what the previous line left open: a quoted value (to its closing quote), or the keyword with its value not begun */
+    open = null;
+    /** A line not ended yet, masked as it stands, the state left as it was: what a follow shows of a line still being
+     *  written (src/lib/log-read.ts `follow`), the whole line read by `line` once its newline comes. */
+    peek(raw) {
+        const open = this.open;
+        try {
+            return this.line(raw);
+        }
+        finally {
+            this.open = open;
+        }
+    }
+    /** One line (no newline), masked. */
+    line(raw) {
+        if (raw.trim() === "" || /^\S/.test(raw))
+            this.open = null; // a new entry: nothing carries into it
+        const open = this.open;
+        this.open = null;
+        if (open !== null && "quote" in open) {
+            // the value runs on from the line before: masked to its closing quote (the newline ended any escape), the rest read as any line
+            const indent = /^\s*/.exec(raw)[0];
+            let escaped = false;
+            for (let i = indent.length; i < raw.length; i++) {
+                const c = raw[i];
+                if (escaped)
+                    escaped = false;
+                else if (c === "\\")
+                    escaped = true;
+                else if (c === "'")
+                    return `${indent}${MASKED}${this.alone(raw.slice(i + 1))}`;
+            }
+            this.open = { quote: true };
+            return `${indent}${MASKED}`;
+        }
+        if (open !== null) {
+            // the keyword ended the line before: read with it, and its own text taken off again (the key is kept as written)
+            return this.alone(`${open.keyword}\n${raw}`).slice(open.keyword.length + 1);
+        }
+        return this.alone(raw);
+    }
+    /** `text` masked whole, and what it leaves open at its end noted for the next line */
+    alone(text) {
+        let atEnd = null; // the value of a match that runs to the text's end
+        const masked = text.replace(PASSWORD_KEYWORD, (match, key, index) => {
+            if (index + match.length === text.length)
+                atEnd = match.slice(key.length);
+            return `${key}${MASKED}`;
+        });
+        const value = atEnd;
+        if (value !== null) {
+            if (value.startsWith("'") && !closed(value))
+                this.open = { quote: true };
+        }
+        else {
+            const k = KEYWORD_OPEN.exec(text);
+            if (k !== null)
+                this.open = { keyword: text.slice(k.index) };
+        }
+        return masked;
+    }
+}
+/** An error's code: a Postgres SQLSTATE or a system error's (`ECONNREFUSED`), the kind the engine names its error by
+ *  (`IO Error`), else none — what is said of an error whose words are never repeated (the secret's statement). */
+export function errorCode(e) {
+    if (e !== null && typeof e === "object" && typeof e.code === "string" && e.code !== "")
+        return e.code;
+    const m = e instanceof Error ? /^([A-Z][A-Za-z]*(?: [A-Za-z]+)* Error):/.exec(e.message) : null;
+    return m?.[1] ?? null;
+}
+/** A CAUGHT ERROR'S WORDS, AS MASON REPEATS THEM (a log line, an event, a table's `error`, an answer): its message (or,
+ *  `stack`, its stack), every `password=` value masked. Never matched by a branch: that reads `messageOf`. */
+export function errorText(e, o = {}) {
+    return maskPasswordKeyword(e instanceof Error ? (o.stack === true ? e.stack ?? e.message : e.message) : String(e));
+}
+/** A CAUGHT ERROR'S RAW WORDS, FOR A DECISION ALONE (which failure it is: a wider numeric, a transaction already ended):
+ *  never shown — said, logged or stored, an error's words are `errorText`'s. */
+export function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/src/lib/table-sync.js

@@ -0,0 +1,282 @@
+/**
+ * HOW A TABLE IS KEPT CURRENT AFTER ITS FIRST COPY: the sources file's `sync:` (GitHub issue 33), at the top of the
+ * file as every table's default and on an entry for that table alone. ONE grammar, read by the one reader of the file
+ * (src/cli/sources.ts `parseSourceText`) and by `mason add --sync` (src/cli/commands.ts), so a value is taken or refused
+ * in the same words at both entrances:
+ *
+ *   off               nothing after the first copy until `mason sync <table>`, which polls it once, now (the default)
+ *   poll <interval>   the xmin poll every <interval>: <n>s, <n>m or <n>h, a whole number, at least 1s, at most 24h
+ *   replication       the database's change log, through the project's ONE slot and publication (src/duck/stream.ts):
+ *                     the publication carries the replicated tables only, and the polled ones are polled beside it
+ *
+ * The engine never decides how a table is kept current by its size: the row count matters only to `mason add`, which
+ * writes `sync: off` for a table over `BIG_TABLE_ROWS` when the file's default polls (src/cli/source-edit.ts).
+ */
+import { closest } from "./did-you-mean.js";
+/** the sync a table has when neither its entry nor the file says one: `off` (issue 33: Mason reads each table once,
+ *  then only what you tell it to) */
+export const DEFAULT_SYNC = { mode: "off" };
+/** the shortest interval a poll takes: below a second a full scan of the table on the source is the source's whole time */
+export const MIN_POLL_SECONDS = 1;
+/** the longest: a day. Longer is `off` with `mason sync <table>` from a scheduler (and an instant past a Date's range,
+ *  a review finding: `poll 9999999999999s` broke every status line) */
+export const MAX_POLL_SECONDS = 86_400;
+/**
+ * A TABLE THIS BIG IS NOT POLLED UNLESS ITS ENTRY SAYS SO (it was the run's POLL_ROW_LIMIT, which left such a table
+ * copied and never polled, a rule found only by its effect): a poll scans its table whole on the source (no index covers
+ * xmin) and counts it, and on a test server a 22 M-row table cost the production replica 12 s of scan and 2 s of count
+ * at every poll. So `mason add` of a table the catalog estimates over this many rows, under a file whose default polls,
+ * writes `sync: off` on its entry and says so with the alternatives. The stream applies a batch that changes a table
+ * this big by time as well (src/duck/stream.ts `applySize`): each write by key is a scan of its key column.
+ */
+export const BIG_TABLE_ROWS = 1_000_000;
+/** above this many rows a poll under `COSTLY_POLL_SECONDS` is warned of at `mason add`, with an estimate of its cost */
+export const COSTLY_POLL_ROWS = 10_000_000;
+export const COSTLY_POLL_SECONDS = 60;
+const MODES = ["off", "poll", "replication"];
+const UNIT_SECONDS = { s: 1, m: 60, h: 3600 };
+/** the units a person may write for one of ours, said back as the one to write */
+const UNIT_WORDS = {
+    s: "s", sec: "s", secs: "s", second: "s", seconds: "s", m: "m", min: "m", mins: "m", minute: "m", minutes: "m",
+    h: "h", hr: "h", hrs: "h", hour: "h", hours: "h",
+};
+const EXAMPLES = "poll 5s, poll 5m or poll 1h";
+/** what a sync is, said where one is wrong */
+export const SYNC_FORMS = `off, poll <interval> (${EXAMPLES}) or replication`;
+/** the value as the file writes it: `off`, `poll 30s` */
+export function syncText(s) {
+    return s.mode === "poll" ? `poll ${s.every}` : s.mode;
+}
+/** a span of seconds as an interval is written, in the largest unit it is a whole number of: 90 is `90s`, 120 `2m` */
+export function intervalOf(seconds) {
+    const s = Math.max(MIN_POLL_SECONDS, Math.round(seconds));
+    return s % 3600 === 0 ? `${s / 3600}h` : s % 60 === 0 ? `${s / 60}m` : `${s}s`;
+}
+/** an interval (`<n>s|m|h`) read, or why it is not one, with the interval to write when there is one. ONE grammar with three
+ *  entrances, each worded as it is written: a `sync:`'s `poll <interval>`, a generated table's `target_lag:`, and a
+ *  command's wait (`parseDuration`) */
+function parseInterval(v, write = "poll ") {
+    const m = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i.exec(v);
+    const examples = write === "" ? "5s, 5m or 1h" : EXAMPLES;
+    const how = `an interval is <n>s, <n>m or <n>h, a whole number, at least ${MIN_POLL_SECONDS}s (${examples})`;
+    if (m === null)
+        return { problem: `${JSON.stringify(v)} is not an interval: ${how}` };
+    const n = Number(m[1]), word = m[2].toLowerCase();
+    if (word === "ms")
+        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s${write === "" ? "" : " (a poll scans the table whole on your database)"}: write ${write}${MIN_POLL_SECONDS}s or longer` };
+    const unit = UNIT_WORDS[word];
+    if (unit === undefined) {
+        const days = /^(d|day|days)$/.test(word) ? `: write ${write}${intervalOf(n * 86_400)}` : "";
+        return { problem: `${v}: ${word} is not a unit of an interval — ${days ? `days are hours${days}` : how}` };
+    }
+    const seconds = n * UNIT_SECONDS[unit];
+    if (!Number.isInteger(n))
+        return { problem: `${v}: an interval is a whole number — write ${write}${intervalOf(seconds)}` };
+    if (seconds < MIN_POLL_SECONDS)
+        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s: write ${write}${MIN_POLL_SECONDS}s or longer` };
+    if (seconds > MAX_POLL_SECONDS)
+        return { problem: `${v} is over the longest interval, ${intervalOf(MAX_POLL_SECONDS)}: write ${write}${intervalOf(MAX_POLL_SECONDS)}${write === "" ? "" : ", or off with mason sync <table> run by a scheduler"}` };
+    // the number as a number is written (`05s` is `5s`): two spellings of one interval would read as a change of sync
+    const canonical = `${n}${unit}`;
+    if (canonical !== v)
+        return { problem: `${JSON.stringify(v)}: write ${write}${canonical}` };
+    return { every: canonical, seconds };
+}
+/** A generated table's `target_lag:` read (src/cli/generated-files.ts): an interval alone, in the grammar and the range a
+ *  poll's takes, or what is wrong with it in the words a person fixes it from. */
+export function parseLag(v) {
+    if (typeof v !== "string" || v.trim() === "")
+        return { problem: `is ${v === null || v === undefined ? "nothing" : typeof v === "number" ? `the number ${String(v)}` : "not an interval"}: write how far behind the table may be, like 30s, 5m or 1h` };
+    return parseInterval(v.trim(), "");
+}
+/** A command's own wait, as an interval (`mason deploy --timeout 10m`): the grammar and range a poll's and a `target_lag:`
+ *  take, so a span of time is written one way at every entrance. */
+export function parseDuration(v) {
+    return parseInterval(v.trim(), "");
+}
+/**
+ * A `sync:` VALUE READ, or what is wrong with it in the words a person fixes it from (the key is the caller's to say):
+ * the line to write, a `did you mean` for a misspelt mode, the floor for a short interval. Whether a table CAN be
+ * replicated (a primary key, a replica identity) is the catalog's, said at the entry (src/cli/sources.ts entryProblems).
+ */
+export function parseSync(v) {
+    if (typeof v !== "string" || v.trim() === "") {
+        const read = v === null || v === undefined ? "nothing" : typeof v === "boolean" ? `the boolean ${String(v)}` : typeof v === "number" ? `the number ${String(v)}` : "a list or a map";
+        return { problem: `is ${read}: write ${SYNC_FORMS}` };
+    }
+    const words = v.trim().split(/\s+/);
+    const mode = words[0], rest = words.slice(1).join(" ");
+    if (mode === "off")
+        return rest === "" ? { mode: "off" } : { problem: `off takes no interval: write off, or poll ${rest}` };
+    if (mode === "replication")
+        return rest === "" ? { mode: "replication" } : { problem: `replication takes no interval: write replication, or poll ${rest}` };
+    if (mode === "poll") {
+        if (rest === "")
+            return { problem: `poll needs its interval: write ${EXAMPLES} (at least ${MIN_POLL_SECONDS}s)` };
+        const i = parseInterval(rest);
+        return "problem" in i ? i : { mode: "poll", ...i };
+    }
+    // a misspelt mode: the line it may have meant, its interval kept when it reads as one
+    const near = closest(mode, MODES);
+    const meant = near === "poll" && rest !== "" && !("problem" in parseInterval(rest)) ? `poll ${rest}` : near;
+    // a question ends its sentence: "did you mean `poll 5s`? Write off, …"
+    return { problem: meant !== null ? `${mode} is not a sync — did you mean \`${meant}\`? Write ${SYNC_FORMS}` : `${mode} is not a sync: write ${SYNC_FORMS}` };
+}
+/** a sync for a person: `off`, `polled every 30s`, `replicated` */
+export function syncWords(s) {
+    return s.mode === "off" ? "off" : s.mode === "replication" ? "replicated" : `polled every ${s.every}`;
+}
+/** how long ago an instant was, as a status line reads: `4 s ago`, `12 min ago`, `5 h ago`, `3 days ago` */
+export function agoText(iso, now = Date.now()) {
+    const s = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
+    if (s < 90)
+        return `${s} s ago`;
+    if (s < 90 * 60)
+        return `${Math.round(s / 60)} min ago`;
+    if (s < 36 * 3600)
+        return `${Math.round(s / 3600)} h ago`;
+    const d = Math.round(s / 86_400);
+    return `${d} day${d === 1 ? "" : "s"} ago`;
+}
+/**
+ * THE EDIT THAT MAKES THE TOP'S `key:` SAY ONE OF `values`, in words a person (or an agent) applies as written: change
+ * the line the file has, keep one that already says it, or write it when the file has none. `anyPoll`: any
+ * `poll <interval>` already written is kept (for "poll it", whatever the interval).
+ */
+export function topEdit(top, key, values, anyPoll = false) {
+    const now = top[key] === null ? null : top[key].trim().replace(/\s+/g, " ");
+    const said = (v) => now !== null && (now === v || (anyPoll && v.startsWith("poll ") && now.startsWith("poll ")));
+    const kept = values.find(said);
+    if (kept !== undefined && now !== null)
+        return `keep ${key}: ${now} at the top of ${top.shown}`;
+    const to = values.map((v) => `${key}: ${v}`).join(" or ");
+    return now === null ? `write ${to} at the top of ${top.shown}` : `change ${key}: ${now} at the top of ${top.shown} to ${to}`;
+}
+/**
+ * `MASON_POLL_MS` SET IS REFUSED, never run on a default (CLAUDE.md: a renamed setting refuses the start, naming the
+ * line to write): how often a table is polled is the sources file's `sync:`, per table. Null when it is unset; else what
+ * is wrong, why and the way out — a Failure's fields for `mason start` (before it spawns, and the run itself), joined on
+ * one line of `mason serve`'s settings report (`pollMsRetiredText`). `top` is read only when it is set.
+ */
+export function pollMsRetired(env, top) {
+    const v = env.MASON_POLL_MS;
+    if (v === undefined || v === "")
+        return null;
+    const ms = Number(v);
+    const every = `poll ${Number.isFinite(ms) && ms >= MIN_POLL_SECONDS * 1000 ? intervalOf(Math.min(ms / 1000, MAX_POLL_SECONDS)) : "5s"}`;
+    return { message: `MASON_POLL_MS=${v} is no longer read`, why: "how often each table is polled is its sync: in the sources file",
+        fix: `${topEdit(top(), "sync", [every])} (every table; a table's entry may say its own), then unset MASON_POLL_MS` };
+}
+/** the same, as one line */
+export function pollMsRetiredText(env, top) {
+    const r = pollMsRetired(env, top);
+    return r === null ? null : `${r.message}: ${r.why} — ${r.fix}`;
+}
+/** what every retired way of choosing a whole project's changes is told: where it is said now, so what runs is what is
+ *  committed — how each table is kept current (`sync`), the publication replication reads (`publication`), or both */
+function saidInTheFile(what) {
+    const said = [...(what.sync ? ["how each table is kept current is its sync: in the sources file (at the top for every table, on an entry for that one)"] : []),
+        ...(what.publication ? [`the publication replication reads is ${what.sync ? "its" : "the sources file's"} publication:`] : [])];
+    return `${said.join(", and ")}, so what runs is what is committed`;
+}
+/**
+ * `mason start --replication`, `--poll` AND `--publication <name>` ARE GONE (issue 33, PR 3; no backwards compatibility
+ * before v1.0): each answers, without starting, with the edit to make at the top of the sources file (`top`, read only
+ * when a removed flag is given) — its `sync:` line to `replication` or `poll 5m`, its `publication:` to the name —
+ * every one given on ONE report, one coherent way out (a publication goes with replication). Null when none is given.
+ * Read from the raw command line, before the options are parsed, so a removed flag is answered as removed and never
+ * as an unknown option.
+ */
+export function removedStartFlags(argv, top) {
+    let replication = false, poll = false, publication;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--")
+            break;
+        if (a === "--replication" || a.startsWith("--replication="))
+            replication = true;
+        else if (a === "--poll" || a.startsWith("--poll="))
+            poll = true;
+        else if (a.startsWith("--publication="))
+            publication = a.slice("--publication=".length) || null;
+        else if (a === "--publication") {
+            const v = argv[i + 1];
+            publication = v !== undefined && !v.startsWith("-") ? v : null;
+        }
+    }
+    const given = [...(replication ? ["--replication"] : []), ...(poll ? ["--poll"] : []), ...(publication !== undefined ? ["--publication"] : [])];
+    if (given.length === 0)
+        return null;
+    const t = top();
+    const named = given.length === 1 ? `${given[0]} is gone` : `${given.slice(0, -1).join(", ")} and ${given.at(-1)} are gone`;
+    const pub = publication === undefined ? null : topEdit(t, "publication", [publication ?? "<name>"]);
+    let fix;
+    if (replication) {
+        // every table from the change log (or polled, when --poll said that too), and the publication beside it
+        const sync = topEdit(t, "sync", poll ? ["replication", "poll 5m"] : ["replication"]);
+        // two lines to write at the same top are one instruction: "write sync: replication and publication: app_pub at the top of …"
+        const at = ` at the top of ${t.shown}`;
+        const both = pub !== null && !poll && sync.startsWith("write ") && pub.startsWith("write ") && sync.endsWith(at) && pub.endsWith(at);
+        fix = both ? `${sync.slice(0, -at.length)} and ${pub.slice("write ".length)}`
+            : `${sync}${poll ? " (or each table's own on its entry)" : ""}${pub ? `, and ${pub}` : ""}`;
+    }
+    else if (pub !== null) {
+        // a publication is read only by replication: it names the tables that are replicated, the others are polled or off
+        fix = `${poll ? "a publication goes with replication: " : ""}${pub}, with sync: replication on the entries of the tables it carries` +
+            `${poll ? " and sync: poll 5m (any interval) on the others" : ""}`;
+    }
+    else {
+        const edit = topEdit(t, "sync", ["poll 5m"], true);
+        fix = `${edit} (${edit.startsWith("keep ") ? "every table is polled already; a table's entry may say its own"
+            : "any interval: poll 5s, poll 1h; or sync: off, the default, and mason sync <table> when you need it"})`;
+    }
+    return { message: `${named}: the sources file says it now`, why: saidInTheFile({ sync: replication || poll, publication: publication !== undefined }),
+        fix: `${fix}, then mason start` };
+}
+/**
+ * `MASON_CHANGES` SET IS REFUSED, never run on a default (CLAUDE.md: a removed setting refuses the start, naming the
+ * edit to make): how each table is kept current is the sources file's `sync:` (`top`, read only when it is set). Null
+ * when it is unset; else a Failure's fields, joined on one line of `mason serve`'s settings report
+ * (`changesRetiredText`).
+ */
+export function changesRetired(env, top) {
+    const v = env.MASON_CHANGES;
+    if (v === undefined || v === "")
+        return null;
+    const edit = v === "replication" ? topEdit(top(), "sync", ["replication"]) : v === "poll" ? topEdit(top(), "sync", ["poll 5m"], true)
+        : topEdit(top(), "sync", ["replication", "poll 5m"]);
+    return { message: `MASON_CHANGES=${v} is no longer read`, why: saidInTheFile({ sync: true, publication: false }),
+        fix: `${edit} (every table; a table's entry may say its own), then unset MASON_CHANGES` };
+}
+/** the same, as one line */
+export function changesRetiredText(env, top) {
+    const r = changesRetired(env, top);
+    return r === null ? null : `${r.message}: ${r.why} — ${r.fix}`;
+}
+/**
+ * A DURATION IN MILLISECONDS as a person reads it, the one formatter of a statement's, a sync's or a percentile's time
+ * (the web page's `msText`, src/web/shared.js, held equal by the tests): `512 ms` under a second, then `13.7 s`, then
+ * `2 min 5 s`, then `1 h 4 min` (a 13,703 ms statement read as thirteen thousand of something).
+ */
+export function msText(ms) {
+    const v = Math.max(0, ms);
+    if (Math.round(v) < 1000)
+        return `${Math.round(v)} ms`;
+    const tenths = Math.round(v / 100);
+    if (tenths < 600)
+        return `${(tenths / 10).toFixed(1)} s`;
+    const s = Math.round(v / 1000);
+    if (s < 3600)
+        return `${Math.floor(s / 60)} min${s % 60 ? ` ${s % 60} s` : ""}`;
+    const m = Math.round(s / 60);
+    return `${Math.floor(m / 60)} h${m % 60 ? ` ${m % 60} min` : ""}`;
+}
+/**
+ * WHAT A SYNC DID TO ONE TABLE, in the words `mason sync` prints on its line and the web page's Sync now says
+ * (src/cli/sync.ts `syncedReport`, src/web/pages/tables.js, held equal) — and a sync by hand records as its `synced`
+ * event (src/duck/sync.ts pollNow), so the event and the answer the person read are one sentence.
+ */
+export function syncedText(t) {
+    const n = (x) => x.toLocaleString("en-US");
+    return `${n(t.changed)} changed, ${n(t.deleted)} deleted, ${n(t.rows)} rows now · ${msText(t.ms)}`;
+}