@mason-data/cli 0.6.2 → 0.8.0

package/dist/src/cli/version.js

@@ -1,12 +1,13 @@
 /**
- * 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).
+ * What this Mason is, and where that was read (what a person running it can act on follows from it: `mason serve`'s pin
+ * says the image to run, or the npm line): 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".
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-export function version() {
+export function runningVersion() {
     // 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")]) {
@@ -14,10 +15,11 @@ export function version() {
             continue;
         const pkg = JSON.parse(fs.readFileSync(p, "utf8"));
         if (pkg.name === "@mason-data/cli" && pkg.version)
-            return pkg.version;
+            return { text: pkg.version, from: "package" };
     }
     const image = process.env.MASON_VERSION?.trim();
     if (image)
-        return /^v\d+\.\d+\.\d+$/.test(image) ? image.slice(1) : image;
-    return "dev";
+        return { text: /^v\d+\.\d+\.\d+$/.test(image) ? image.slice(1) : image, from: "image" };
+    return { text: "dev", from: "checkout" };
 }
+export const version = () => runningVersion().text;

package/dist/src/demo/seed.js

@@ -0,0 +1,240 @@
+/**
+ * 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);
+/** how the demo's tables are kept current (the sources file's top `sync:`, src/lib/table-sync.ts): polled every 5 s,
+ *  so the demo shows a copy keeping up with its writer — where a project `mason init` makes is `off` */
+export const DEMO_SYNC = { mode: "poll", every: "5s", seconds: 5 };
+/** 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}`,
+    };
+}