@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/cli/user.js

@@ -0,0 +1,229 @@
+/**
+ * `mason user add | list | remove` — NAMED, REVOCABLE LOGINS FOR THE POSTGRES API, WITH NO EXPIRY
+ * (docs/DESIGN.md "On a server", item 1 of the agreed plan; src/duck/users.ts holds the rules). A BI
+ * tool's datasource stores ONE password: a user's lasts until it is removed.
+ *
+ * It runs as a second process beside the run (or beside `mason serve`: `docker compose exec mason mason user add
+ * metabase`, the data folder's `.mason/`), so it needs the project, never the run: it edits `.mason/users.json` under
+ * the file's lock, and the run's listener reads the change at its next connection or statement. The password is said
+ * ONCE, by `add`, with the URL to paste (one URL builder, pg-url.ts `connectionUrl`) when the run is up and recorded
+ * where it listens. The web page's users (`mason ui`) are the same functions (`addUser`, `listUsers`, `removeUser`),
+ * called by the run's command server.
+ */
+import * as path from "node:path";
+import { failed, jsonText, parseCommand, reportText, withEnd } from "./command.js";
+import { reach } from "./state.js";
+import { connectionUrl, listenerTips, postgresLink, psqlLine } from "./pg-url.js";
+import { changeUsers, keyFingerprint, newUserId, readUsers, underKey, userPassword, USER_NAME_RE, USER_NAME_RULE, USERS_FILE } from "../duck/users.js";
+import { didYouMean } from "../lib/did-you-mean.js";
+import { out as styleOut } from "./style.js";
+const out = (m) => { process.stdout.write(`${m}\n`); };
+export const USER = {
+    needs: "project",
+    name: "user",
+    summary: "the users the Postgres API takes: a name and a password that does not expire, for a BI tool or an app",
+    usage: `usage: mason user add <name> [--json]
+       mason user list [--json]
+       mason user remove <name> [--json]
+
+  A user of this project's Postgres API: a name and a password, as a BI tool's datasource form asks for them
+  (Metabase, Grafana, Superset, Power BI) or an app's DATABASE_URL carries them. Its password does not expire:
+  it connects until mason user remove, which refuses its next connection at once and
+  ends the sessions it holds at their next statement, without a restart. The password is printed once, by add.
+  The user name a tool sends must be the user's own.
+
+  The list is .mason/users.json (names and ids, no password), beside the running Mason, which reads it again by itself.
+  Rotating the API key (apiKey in .mason/config.json, MASON_API_KEY under mason serve) removes every user at once.
+
+    mason user add metabase                    a user for Metabase: its password and the URL to paste
+    mason user list
+    mason user remove metabase                 metabase connects no more
+    docker compose exec mason mason user add grafana   beside mason serve, in its data folder
+
+  <name>    ${USER_NAME_RULE}
+  --json    as data: add { user (the name), id, addedAt, password, database, and once Mason runs url, host, port,
+            sslmode }; list { users: [{ name, id, addedAt, live }] }; remove { removed: { name, id, addedAt } }; next
+`,
+    options: { json: { type: "boolean", default: false } },
+    json: ["user", "id", "addedAt", "password", "url", "host", "port", "database", "sslmode", "users", "removed", "next"],
+};
+/** The users of a project and why one is not live: added under an API key since rotated. */
+const liveOf = (u, apiKey) => underKey(u, apiKey);
+/** What to run after an add: with Mason up, the list and how to end it; with Mason stopped, mason start first. */
+export const addedNext = (name, up) => up
+    ? [["mason user list", "the users"], [`mason user remove ${name}`, "it connects no more"]]
+    : [["mason start", "start Mason: then mason status prints where the Postgres API listens"], ["mason user list", "the users"]];
+/** What to run after a remove. */
+export const REMOVED_NEXT = [["mason user list", "the users left"], ["mason user add <name>", "a new user, with a new password"]];
+/** Why `name` is not one `mason user <verb>` takes (a usage failure), or null. */
+export function userNameProblem(verb, name) {
+    if (name === undefined)
+        return `mason user ${verb} <name>: which user`;
+    if (!USER_NAME_RE.test(name))
+        return `${JSON.stringify(name)} is not a user name: ${USER_NAME_RULE}`;
+    return null;
+}
+const cantChange = (file, e) => ({ message: `the list of users could not be changed: ${e.message}`, code: "failed",
+    fix: `${file} is the list (mason user writes it): repair it, or move it aside, which removes every user` });
+/** The users `file` lists, each with whether it connects under `apiKey`; or why the file cannot be read. */
+export function listUsers(file, apiKey) {
+    const r = readUsers(file);
+    if ("problem" in r)
+        return { message: `the list of users cannot be read: ${r.problem}`, code: "bad_config", why: "no user connects while it cannot be read",
+            fix: `repair ${file}, or move it aside, which removes every user` };
+    return { users: r.users.map((u) => ({ name: u.name, id: u.id, addedAt: u.addedAt, live: liveOf(u, apiKey) })) };
+}
+/**
+ * ADD A USER to `file` under its lock: a new id, its password (said here, once, and kept nowhere), and — `link`, where
+ * the run's Postgres API listens, when it is up — the URL to paste. A name taken by a live user is refused.
+ */
+export function addUser(file, apiKey, name, o) {
+    const usage = userNameProblem("add", name);
+    if (usage !== null)
+        return { message: usage, code: "usage" };
+    const fingerprint = keyFingerprint(apiKey);
+    let added;
+    let replaced = false;
+    let r;
+    try {
+        r = changeUsers(file, (users) => {
+            const was = users.find((u) => u.name === name);
+            // a user added under a key since rotated connects no more: its name is free, said
+            if (was !== undefined && was.key === fingerprint)
+                return { refused: "taken" };
+            replaced = was !== undefined;
+            added = { name, id: newUserId(), addedAt: new Date().toISOString(), key: fingerprint };
+            return [...users.filter((u) => u !== was), added];
+        });
+    }
+    catch (e) {
+        return cantChange(file, e);
+    }
+    if (!Array.isArray(r)) {
+        return { message: `there is already a user ${JSON.stringify(name)}`, code: "refused",
+            why: "a name names one user, so removing it means one thing; its password is not kept, so it cannot be printed again",
+            fix: `mason user remove ${name}, then mason user add ${name} (a new password; the old one stops connecting), or add another name (${name}-2) and remove ${name} once the tool uses it`,
+            next: [["mason user list", "the users"], [`mason user remove ${name}`, "then add it again, with a new password"]] };
+    }
+    const u = added;
+    const password = userPassword(apiKey, u.name, u.id);
+    const { link } = o;
+    return { user: u.name, id: u.id, addedAt: u.addedAt, password, database: link?.database ?? o.database,
+        ...(link !== null ? { url: connectionUrl(link, u.name, password), host: link.host, port: link.port, sslmode: link.sslmode ?? "disable" } : {}), replaced };
+}
+/** REMOVE A USER from `file` under its lock: it connects no more. A name the file lacks is refused with the closest it has. */
+export function removeUser(file, name) {
+    const usage = userNameProblem("remove", name);
+    if (usage !== null)
+        return { message: usage, code: "usage" };
+    let removed;
+    let live = [];
+    let r;
+    try {
+        r = changeUsers(file, (users) => {
+            removed = users.find((u) => u.name === name);
+            live = users.map((u) => u.name);
+            return removed === undefined ? { refused: "unknown" } : users.filter((u) => u !== removed);
+        });
+    }
+    catch (e) {
+        return cantChange(file, e);
+    }
+    if (!Array.isArray(r)) {
+        return { message: `there is no user ${JSON.stringify(name)}${didYouMean(name, live)}`, code: "not_found",
+            why: live.length ? `the users: ${live.join(", ")}` : "this project has no users", next: [["mason user list", "the users"]] };
+    }
+    const gone = removed;
+    return { removed: { name: gone.name, id: gone.id, addedAt: gone.addedAt } };
+}
+// ------------------------------------------------------------------ the command
+export async function user(argv) {
+    const f = parseCommand(USER, argv);
+    if (typeof f === "number")
+        return f;
+    const json = f.values.json === true;
+    const usage = (message) => failed("user", { message, code: "usage", usage: USER.usage }, { json });
+    const [verb, name, ...rest] = f.positionals;
+    if (verb === undefined)
+        return usage("add, list or remove: mason user add <name> makes a user");
+    if (!["add", "list", "remove"].includes(verb))
+        return usage(`there is no mason user ${verb}: add, list or remove${didYouMean(verb, ["add", "list", "remove"])}`);
+    if (verb === "list" ? name !== undefined : rest.length)
+        return usage(`mason user ${verb} takes ${verb === "list" ? "no name" : "one name"}: ${[name, ...rest].filter(Boolean).join(" ")} is too many`);
+    if (verb !== "list") {
+        const problem = userNameProblem(verb, name);
+        if (problem !== null)
+            return usage(problem);
+    }
+    const w = await reach(USER, json);
+    if (w === null || w.project === null)
+        return 1;
+    const project = w.project;
+    const file = path.join(project.dir, USERS_FILE);
+    const apiKey = project.config.apiKey;
+    if (verb === "list") {
+        const r = listUsers(file, apiKey);
+        if ("message" in r)
+            return failed("user", r, { json });
+        const next = [["mason user add <name>", "a user for a tool: its password and URL, printed once"], ...(r.users.length ? [["mason user remove <name>", "that user connects no more"]] : [])];
+        if (json) {
+            out(jsonText(USER, { users: r.users }, next));
+            return 0;
+        }
+        const s = styleOut();
+        if (!r.users.length) {
+            out(withEnd(`${s.bold(`No users yet for ${project.config.name}.`)}`, { next }));
+            return 0;
+        }
+        const width = Math.max(...r.users.map((u) => u.name.length));
+        const lines = r.users.map((u) => `  ${s.cyan(u.name.padEnd(width))}   ${s.dim(`id ${u.id} · added ${u.addedAt.slice(0, 16).replace("T", " ")} UTC`)}` +
+            (u.live ? "" : `   ${s.yellow("does not connect: the API key was rotated since it was added")}`));
+        const rotated = r.users.filter((u) => !u.live);
+        out(withEnd(`${s.bold(`${r.users.length} user${r.users.length === 1 ? "" : "s"} of ${project.config.name}`)}\n${lines.join("\n")}`, { ...(rotated.length ? { tips: [`A user added under another API key does not connect: mason user remove ${rotated[0].name}, then mason user add ${rotated[0].name}.`] } : {}), next }));
+        return 0;
+    }
+    if (verb === "remove") {
+        const r = removeUser(file, name);
+        if ("message" in r)
+            return failed("user", r, { json });
+        const gone = r.removed;
+        const next = REMOVED_NEXT;
+        if (json) {
+            out(jsonText(USER, r, next));
+            return 0;
+        }
+        out(reportText({ headline: `The user ${gone.name} removed: it connects no more`,
+            details: [["user", gone.name], ["added", gone.addedAt], ["sessions", w.state === "up" ? "those it holds end at their next statement" : "none: Mason is not running"]],
+            tips: [`Adding ${gone.name} again makes a new password: the old one never connects again.`], next }));
+        return 0;
+    }
+    // add
+    const run = w.state === "up" ? w.run : null;
+    const link = run ? postgresLink(run.postgresUrl) : null;
+    const r = addUser(file, apiKey, name, { link, database: project.config.name });
+    if ("message" in r)
+        return failed("user", r, { json });
+    const { replaced, ...added } = r;
+    const next = addedNext(r.user, link !== null);
+    if (json) {
+        out(jsonText(USER, added, next));
+        return 0;
+    }
+    out(reportText({
+        headline: `The user ${r.user} added${replaced ? " (in place of one the API key's rotation had removed)" : ""}: its password is printed this once`,
+        details: [
+            ...(r.url !== undefined ? [["url", r.url], ["psql", psqlLine(r.url)]] : []),
+            ["user", r.user], ["password", r.password], ["database", r.database],
+            ...(link !== null ? [["host", link.host], ["port", String(link.port)], ...(link.sslmode ? [["ssl mode", link.sslmode]] : [])] : []),
+        ],
+        tips: [
+            "Paste it into the tool now: Mason keeps no copy of the password. Lost, remove the user and add it again.",
+            ...(link === null ? ["Mason is not running: mason start, then mason status says the host and port this user connects to."] : []),
+            ...listenerTips(run?.postgresListener ?? null),
+            "It never expires: mason user remove ends it, at once and for every session it holds.",
+            "Rotating the API key (apiKey in .mason/config.json, MASON_API_KEY under mason serve) removes every user at once.",
+        ],
+        next,
+    }));
+    return 0;
+}

package/dist/src/cli/version.js

@@ -0,0 +1,23 @@
+/**
+ * The package's version when installed; else the image's (`MASON_VERSION`, stamped at build by images-publish.yml:
+ * `v0.6.1` for a release, said `0.6.1` as the package says it, or `main-<sha>`); a checkout runs as "dev" (and
+ * ClickHouse's `main` image).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+export function version() {
+    // src/cli/ in a checkout (the repo's package.json, which is not this one), dist/src/cli/ in the package
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    for (const p of [path.join(here, "..", "..", "package.json"), path.join(here, "..", "..", "..", "package.json")]) {
+        if (!fs.existsSync(p))
+            continue;
+        const pkg = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (pkg.name === "@mason-data/cli" && pkg.version)
+            return pkg.version;
+    }
+    const image = process.env.MASON_VERSION?.trim();
+    if (image)
+        return /^v\d+\.\d+\.\d+$/.test(image) ? image.slice(1) : image;
+    return "dev";
+}

package/dist/src/demo/seed.js

@@ -0,0 +1,237 @@
+/**
+ * THE DEMO DATABASE'S SCHEMA AND ROWS (`mason init demo`, src/demo/source.ts): a small web shop a BI user recognises at
+ * once — `customers`, `products`, `orders`, `order_items` — with primary and foreign keys declared, about 200 / 50 /
+ * 5,000 / 15,000 rows, and the orders' dates spread over the twelve months before the seed, so a time-window chart has
+ * data in every week.
+ *
+ * SYNTHETIC ONLY (CLAUDE.md "A real database's data and structures are confidential"): every name below is made up
+ * here, from short word lists, and every email is at example.com.
+ *
+ * DETERMINISTIC: one seeded PRNG (`mulberry32`) draws every value, so every demo holds the same rows; only the dates are
+ * anchored to the moment of the seed (`now`), so "the last 30 days" has orders whenever the demo was made. The rounds of
+ * changes (`changeSql`) draw from a PRNG seeded by the newest order's id, so they are the same sequence too, across
+ * restarts.
+ *
+ * WRITTEN AS A FEW MULTI-ROW INSERTs (`ROWS_PER_INSERT` a statement), never one per row: PGlite is slow per statement.
+ * Prices and totals are counted in integer cents and printed as decimals, so a total is exactly its items' sum.
+ */
+/** A small, fast, seeded PRNG (mulberry32): the same seed, the same sequence, on every machine. */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** The demo database's name and its user: what its URL says, and what `current_database()` and `current_user` are. */
+export const DEMO_DATABASE = "demo";
+export const DEMO_USER = "demo";
+/** `postgres://demo@127.0.0.1:<port>/demo`: the demo database's URL, its port the one fact that differs. */
+export function demoUrl(port) {
+    return `postgres://${DEMO_USER}@127.0.0.1:${port}/${DEMO_DATABASE}`;
+}
+export const SEED_COUNTS = { customers: 200, products: 50, orders: 5_000 };
+/** the database's four tables, in the order they are made (a foreign key's target first) */
+export const DEMO_TABLES = ["customers", "products", "orders", "order_items"];
+/**
+ * THE TABLE `mason init demo` LEAVES OUT of the sources file, for the person to add themselves: the first thing they do
+ * after `mason start` is a real `mason add` (or the web page's Add), and they see a copy begin. `order_items`, because
+ * its foreign keys' targets (`orders`, `products`) are among the ones added, so it joins cleanly when it arrives. The
+ * database holds it regardless, and the writer (`changeSql`) keeps inserting into it.
+ */
+export const DEMO_TABLE_TO_ADD = "order_items";
+/** the tables `mason init demo` writes to the sources file: the database's, but the one left to add */
+export const DEMO_ADDED_TABLES = DEMO_TABLES.filter((t) => t !== DEMO_TABLE_TO_ADD);
+/** an order's status moves along this path (`changeSql`); `cancelled` is a side exit */
+export const ORDER_STATUSES = ["pending", "paid", "shipped", "delivered"];
+const ROWS_PER_INSERT = 1_000;
+const DAY_MS = 86_400_000;
+const FIRST = ["Ada", "Ben", "Cleo", "Dev", "Eli", "Fay", "Gus", "Hana", "Ivo", "Jun", "Kai", "Lea", "Milo", "Nia", "Otto",
+    "Pia", "Quin", "Rae", "Sol", "Tess", "Uma", "Vic", "Wren", "Xavi", "Yara", "Zed"];
+const LAST = ["Abbott", "Brook", "Castell", "Dorn", "Ember", "Fallow", "Grove", "Hollis", "Ingram", "Juniper", "Keel",
+    "Lark", "Marsh", "Nettle", "Orchard", "Penn", "Quarry", "Rook", "Sorrel", "Thorne", "Vale", "Wilde"];
+/** weighted: the first countries hold most customers, as a shop's do */
+const COUNTRIES = ["United States", "United States", "United States", "United Kingdom", "United Kingdom", "Germany",
+    "Germany", "France", "Canada", "Australia", "Netherlands", "Spain", "Japan", "Brazil", "India"];
+const CATEGORIES = {
+    Books: { nouns: ["Novel", "Cookbook", "Atlas", "Field Guide", "Notebook"], cents: [800, 4_500] },
+    Electronics: { nouns: ["Headphones", "Speaker", "Charger", "Keyboard", "Webcam"], cents: [1_500, 25_000] },
+    Home: { nouns: ["Lamp", "Rug", "Mug", "Throw", "Vase"], cents: [1_200, 12_000] },
+    Garden: { nouns: ["Trowel", "Planter", "Hose", "Seed Kit", "Bird Feeder"], cents: [900, 8_000] },
+    Sports: { nouns: ["Yoga Mat", "Water Bottle", "Jump Rope", "Backpack", "Cap"], cents: [1_000, 9_000] },
+};
+const ADJECTIVES = ["Oak", "Slate", "Cedar", "Coral", "Indigo", "Amber", "Birch", "Moss", "Pebble", "Saffron"];
+/** a SQL string literal (the seed's own words only, but quoted properly all the same) */
+const lit = (s) => `'${s.replace(/'/g, "''")}'`;
+const money = (cents) => `${Math.floor(cents / 100)}.${String(cents % 100).padStart(2, "0")}`;
+const stamp = (ms) => lit(new Date(ms).toISOString());
+/** `INSERT INTO t (cols) VALUES …` in statements of ROWS_PER_INSERT rows */
+function inserts(table, columns, rows) {
+    const out = [];
+    for (let i = 0; i < rows.length; i += ROWS_PER_INSERT) {
+        out.push(`INSERT INTO ${table} (${columns}) VALUES\n${rows.slice(i, i + ROWS_PER_INSERT).join(",\n")}`);
+    }
+    return out;
+}
+const DDL = `CREATE TABLE customers (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  name text NOT NULL,
+  email text NOT NULL UNIQUE,
+  country text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE products (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  name text NOT NULL,
+  category text NOT NULL,
+  price numeric(10,2) NOT NULL
+);
+CREATE TABLE orders (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  customer_id bigint NOT NULL REFERENCES customers (id),
+  status text NOT NULL,
+  total numeric(12,2) NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE order_items (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  order_id bigint NOT NULL REFERENCES orders (id),
+  product_id bigint NOT NULL REFERENCES products (id),
+  quantity integer NOT NULL,
+  unit_price numeric(10,2) NOT NULL
+);
+CREATE INDEX order_items_order_id ON order_items (order_id);
+CREATE INDEX orders_customer_id ON orders (customer_id);
+COMMENT ON TABLE orders IS 'One row per checkout; total is the sum of its order_items';`;
+/** The product catalogue: its prices in cents, by id (1-based), which the orders' items read. */
+function products(rand) {
+    const names = Object.keys(CATEGORIES);
+    const out = [];
+    for (let i = 0; i < SEED_COUNTS.products; i++) {
+        const category = names[i % names.length];
+        const c = CATEGORIES[category];
+        const noun = c.nouns[Math.floor(i / names.length) % c.nouns.length];
+        const adjective = ADJECTIVES[Math.floor(i / (names.length * c.nouns.length)) % ADJECTIVES.length];
+        // a price ending in 99 or 49, as a shop's do
+        const cents = Math.floor((c.cents[0] + rand() * (c.cents[1] - c.cents[0])) / 100) * 100 + (rand() < 0.7 ? 99 : 49);
+        out.push({ name: `${adjective} ${noun}`, category, cents });
+    }
+    return out;
+}
+/** The status of an order placed `ageDays` ago: the old ones delivered (some cancelled), the newest still moving. */
+function statusOf(ageDays, rand) {
+    if (rand() < 0.04)
+        return "cancelled";
+    if (ageDays > 10)
+        return "delivered";
+    if (ageDays > 5)
+        return rand() < 0.6 ? "delivered" : "shipped";
+    if (ageDays > 2)
+        return rand() < 0.5 ? "shipped" : "paid";
+    return rand() < 0.5 ? "paid" : "pending";
+}
+/**
+ * The whole seed, as statements to run in order in ONE transaction: the tables, their rows, the identity sequences moved
+ * past the ids written, and ANALYZE (run by the caller, outside the transaction) so the catalog's row estimates are the
+ * counts. `now` anchors the dates: the orders span the 365 days before it.
+ */
+export function seedStatements(now) {
+    const rand = mulberry32(20_261_027);
+    const end = now.getTime();
+    const start = end - 365 * DAY_MS;
+    const customerRows = [];
+    const customerSince = [];
+    for (let id = 1; id <= SEED_COUNTS.customers; id++) {
+        const first = FIRST[Math.floor(rand() * FIRST.length)];
+        const last = LAST[Math.floor(rand() * LAST.length)];
+        const country = COUNTRIES[Math.floor(rand() * COUNTRIES.length)];
+        // customers sign up over the year before the first orders and the year itself
+        const since = start - 180 * DAY_MS + Math.floor(rand() * 500 * DAY_MS);
+        customerSince.push(Math.min(since, end - DAY_MS));
+        customerRows.push(`(${id}, ${lit(`${first} ${last}`)}, ${lit(`${first}.${last}.${id}@example.com`.toLowerCase())}, ${lit(country)}, ${stamp(customerSince[id - 1])})`);
+    }
+    const catalogue = products(rand);
+    const productRows = catalogue.map((p, i) => `(${i + 1}, ${lit(p.name)}, ${lit(p.category)}, ${money(p.cents)})`);
+    // the orders' times: more of them as the year goes on (a growing shop), sorted so ids follow time, as an app's do
+    const times = [];
+    for (let i = 0; i < SEED_COUNTS.orders; i++)
+        times.push(start + Math.floor(Math.sqrt(rand()) * (end - start - 60_000)));
+    times.sort((a, b) => a - b);
+    const orderRows = [];
+    const itemRows = [];
+    let itemId = 0;
+    for (let i = 0; i < times.length; i++) {
+        const id = i + 1;
+        const at = times[i];
+        // a customer who had signed up by then; a few customers order far more often (the square skews to low ids)
+        let customer = 1 + Math.floor(rand() * rand() * SEED_COUNTS.customers);
+        if (customerSince[customer - 1] > at)
+            customer = 1 + Math.floor(rand() * SEED_COUNTS.customers);
+        const lines = 1 + Math.floor(rand() * 5); // 1–5 items, about 3 on average
+        let total = 0;
+        for (let l = 0; l < lines; l++) {
+            const product = 1 + Math.floor(rand() * catalogue.length);
+            const quantity = rand() < 0.75 ? 1 : 2 + Math.floor(rand() * 3);
+            const cents = catalogue[product - 1].cents;
+            total += quantity * cents;
+            itemRows.push(`(${++itemId}, ${id}, ${product}, ${quantity}, ${money(cents)})`);
+        }
+        orderRows.push(`(${id}, ${customer}, ${lit(statusOf((end - at) / DAY_MS, rand))}, ${money(total)}, ${stamp(at)})`);
+    }
+    return {
+        ddl: DDL,
+        rows: [
+            ...inserts("customers", "id, name, email, country, created_at", customerRows),
+            ...inserts("products", "id, name, category, price", productRows),
+            ...inserts("orders", "id, customer_id, status, total, created_at", orderRows),
+            ...inserts("order_items", "id, order_id, product_id, quantity, unit_price", itemRows),
+        ],
+        // the identity columns continue past the ids written, so a later insert (`changeSql`) takes the next one
+        after: DEMO_TABLES.map((t) => `SELECT setval(pg_get_serial_sequence('${t}', 'id'), (SELECT max(id) FROM ${t}))`),
+    };
+}
+/** What one round of changes reads first: the newest order's id, the products' prices, and the oldest order still moving. */
+export const CHANGE_STATE_SQL = `SELECT (SELECT coalesce(max(id), 0) FROM orders)::text AS newest,
+  (SELECT count(*) FROM customers)::text AS customers,
+  (SELECT coalesce(json_agg(json_build_array(id, (price * 100)::bigint) ORDER BY id), '[]'::json)::text FROM products) AS prices,
+  (SELECT json_build_array(id, status)::text FROM orders WHERE status IN ('pending', 'paid', 'shipped') ORDER BY created_at, id LIMIT 1) AS moving`;
+/**
+ * ONE ROUND OF CHANGES, as one transaction's statements: a new order (now, `pending`) with 1–4 items and its total, and
+ * the oldest order still moving moved one step on its path (pending → paid → shipped → delivered). Its values are drawn
+ * from a PRNG seeded by the newest order's id, so the rounds are the same sequence on every demo. Answers the statements
+ * (the new order's id read back last, as `id`) and what they did, in one line, given that id.
+ */
+export function changeSql(s) {
+    const rand = mulberry32(s.newest * 7_919 + 17);
+    const customer = 1 + Math.floor(rand() * Math.max(1, s.customers));
+    const lines = 1 + Math.floor(rand() * 4);
+    const items = [];
+    for (let l = 0; l < lines && s.prices.length > 0; l++) {
+        const [product, cents] = s.prices[Math.floor(rand() * s.prices.length)];
+        items.push({ product, quantity: rand() < 0.75 ? 1 : 2, cents });
+    }
+    const total = items.reduce((sum, i) => sum + i.quantity * i.cents, 0);
+    const statements = [
+        // the order's id is its identity's next, read back by the items through currval
+        `INSERT INTO orders (customer_id, status, total, created_at) VALUES (${customer}, 'pending', ${money(total)}, now())`,
+        ...(items.length === 0 ? [] : [`INSERT INTO order_items (order_id, product_id, quantity, unit_price) VALUES ` +
+                items.map((i) => `(currval(pg_get_serial_sequence('orders', 'id')), ${i.product}, ${i.quantity}, ${money(i.cents)})`).join(", ")]),
+    ];
+    let moved = "";
+    if (s.moving !== null) {
+        const [id, status] = s.moving;
+        const next = ORDER_STATUSES[ORDER_STATUSES.indexOf(status) + 1];
+        if (next !== undefined) {
+            statements.push(`UPDATE orders SET status = ${lit(next)} WHERE id = ${id}`);
+            moved = `; order ${id} ${status} → ${next}`;
+        }
+    }
+    statements.push(`SELECT currval(pg_get_serial_sequence('orders', 'id'))::text AS id`);
+    return {
+        statements,
+        said: (orderId) => `order ${orderId} placed by customer ${customer} (${items.length} item${items.length === 1 ? "" : "s"}, ${money(total)})${moved}`,
+    };
+}