@mason-data/cli 0.6.2 → 0.7.0

package/dist/src/cli/demo.js

@@ -0,0 +1,149 @@
+/**
+ * THE DEMO PROJECT, THE CLI'S SIDE (`mason init demo`; the database itself is src/demo/source.ts): a project whose
+ * database is one Mason hosts itself — a Postgres in this process, persisted in `.mason/demo/`, served on a loopback
+ * port over the Postgres wire protocol and seeded with a small shop schema — so a person tries Mason with nothing to
+ * install. The project stays an ordinary one: its sources file names `url: ${DATABASE_URL}` and three of the four
+ * tables (the fourth, `DEMO_TABLE_TO_ADD`, is the person's to add), `.env` the demo's URL, and `mason start` reads it
+ * over the wire as it reads any Postgres, so the demo runs the read path production runs (docs/DESIGN.md "The demo
+ * database").
+ *
+ *   - THE PORT LIVES IN THE URL ALONE: `mason init demo` picks one free and writes it into `.env`; `mason start` reads
+ *     it back from the resolved URL (`demoPort`), never from a second record that could disagree with it.
+ *   - POLL ONLY: the demo database has no change log (no WAL sender), so `--replication` is refused before anything
+ *     starts (`demoChangesRefusal`).
+ *   - A WRITER: every MASON_DEMO_CHANGE_MS (`demoSettings`) the run makes one round of changes (`demoChanges`), so the
+ *     copy is seen keeping current.
+ *
+ * The demo's module is imported when it is used (`demoModule`): a command that never hosts it never loads its database;
+ * its URL and names are src/demo/seed.ts's, which loads none.
+ */
+import * as path from "node:path";
+import { parseSource, isLocalHost } from "./preflight.js";
+import { changesOf } from "./replication-mode.js";
+import { heldText, portHolder } from "./ports.js";
+import { DEMO_DIR, STATE_DIR } from "./project.js";
+import { DEMO_DATABASE, DEMO_USER, demoUrl } from "../demo/seed.js";
+/** What `mason init` takes in the URL's place to make a demo project. */
+export const DEMO_ARG = "demo";
+/** The port `mason init demo` prefers for the demo database (the next free one when it is held): beside Mason's 5433. */
+export const DEMO_PORT = 5434;
+/** The demo database's tables (the seed's own list), the ones `mason init demo` adds to the sources file and the one it
+ *  leaves for the person to add, and its URL (src/demo/seed.ts: no PGlite is loaded by it, so `mason init demo` and
+ *  `demoPort` never load the database). */
+export { DEMO_ADDED_TABLES, DEMO_TABLES, DEMO_TABLE_TO_ADD, demoUrl } from "../demo/seed.js";
+/** How often the run changes the demo database by default (MASON_DEMO_CHANGE_MS). */
+export const DEMO_CHANGE_MS = 5000;
+const DEMO_CHANGE_MIN_MS = 100;
+/** The demo database's module (`DemoSource`, and PGlite with it), loaded when the run hosts it, never to build or read
+ *  its URL (src/demo/seed.ts has those). */
+export const demoModule = () => import("../demo/source.js");
+/** What the run reads of the demo from its environment: how often it changes the database. Throws on a value that is no
+ *  number of milliseconds, said with the way out (as src/duck/sync.ts copyParallelOf). */
+export function demoSettings(env) {
+    const v = env.MASON_DEMO_CHANGE_MS;
+    if (v === undefined || v === "")
+        return { changeMs: DEMO_CHANGE_MS };
+    const n = Number(v);
+    if (!/^\d+$/.test(v.trim()) || n < DEMO_CHANGE_MIN_MS) {
+        throw new Error(`MASON_DEMO_CHANGE_MS=${JSON.stringify(v)} is not a number of milliseconds: how often the demo database changes (a new order, an older one's status moved on); ` +
+            `set it to ${DEMO_CHANGE_MIN_MS} or more, or unset it for ${DEMO_CHANGE_MS}`);
+    }
+    return { changeMs: n };
+}
+/**
+ * THE DEMO DATABASE'S PORT, READ FROM THE URL THE SOURCES FILE RESOLVED (`from` says where: `DATABASE_URL in .env`) — or
+ * why that URL is not the demo's, with the way out: a host off this machine (the demo database listens on 127.0.0.1
+ * alone), or any other change to `postgres://demo@127.0.0.1:<port>/demo`. The port is the one fact that may differ.
+ */
+export function demoPort(url, from) {
+    const wayOut = "mason destroy and mason init demo again in a new folder, or put the URL back";
+    const parsed = parseSource(url);
+    if ("problem" in parsed)
+        return { problem: `${from} was changed: ${parsed.problem}. The demo database is postgres://${DEMO_USER}@127.0.0.1:<port>/${DEMO_DATABASE}; ${wayOut}` };
+    const s = parsed.source;
+    // loopback alone: the demo database listens on nothing else (0.0.0.0 or a container's host name is not it)
+    if (!isLocalHost(s.host) || s.host === "0.0.0.0" || s.host === "host.docker.internal") {
+        return { problem: `${from} names ${s.host}, which is not this machine's loopback: the demo database is hosted by mason start on 127.0.0.1 alone (${demoUrl(s.port)}); ${wayOut}` };
+    }
+    if (s.url !== demoUrl(s.port))
+        return { problem: `${from} was changed: the demo database is ${demoUrl(s.port)}; ${wayOut}` };
+    return { port: s.port };
+}
+/** The refusal of logical replication for a demo project (the flag, or a mode the config was edited to): before
+ *  anything starts, with the way out; null for any other project, or a demo one polled. */
+export function demoChangesRefusal(cfg, flag) {
+    if (cfg.demo !== true || changesOf(flag, cfg.changes) !== "replication")
+        return null;
+    return { message: "the demo database is read by polling only: --replication does not apply to it", code: "refused",
+        why: "the demo database has no change log for logical replication to read; mason start polls it with SELECTs, every few seconds",
+        fix: flag === "replication" ? "mason start, without --replication" : `remove "changes": "replication" from ${STATE_DIR}/config.json, then mason start`,
+        next: [["mason start", "the demo database and Mason, polled"]] };
+}
+/** The step's done line: where the demo database listens, and whether it was seeded now or kept from the last run. */
+export function demoDoneLine(port, seeded) {
+    return `Demo database on 127.0.0.1:${port} (Postgres, hosted by this process in ${STATE_DIR}/${DEMO_DIR}; ${seeded ? "seeded with the shop schema" : "kept from the last run"})`;
+}
+/**
+ * THE DEMO DATABASE OPENED for the run in `home`/demo (`home` the project's `.mason/`), its events to `log`: the handle and
+ * the step's done line, or why it did not open — its own message (what failed), and when something holds the port, the
+ * way out ONCE, with its choices: mason stop for a run of this project's that may still hold it, stop what does, or move
+ * the demo database by changing the port in its URL, where `from` says the URL is (`DATABASE_URL in .env`: the port
+ * lives there alone). The port is free for every other reason, so the probe tells a held port apart without reading
+ * the message.
+ */
+export async function openDemo(o) {
+    const open = o.open ?? (async (a) => (await demoModule()).DemoSource.open(a));
+    try {
+        const demo = await open({ dir: path.join(o.home, DEMO_DIR), port: o.port, log: o.log });
+        return { demo, done: demoDoneLine(demo.port, demo.seeded) };
+    }
+    catch (e) {
+        const problem = `the demo database did not start: ${e.message}`;
+        const held = await portHolder(o.port);
+        if (held === null)
+            return { problem };
+        const move = `move the demo database: change the port in ${o.from} (postgres://${DEMO_USER}@127.0.0.1:<another>/${DEMO_DATABASE}) and mason start again`;
+        return { problem: held.code === "EACCES"
+                ? `${problem} (${heldText(o.port, held)}): ${move}`
+                : `${problem}: mason stop ends a run that may still hold it, else stop what does (lsof -nP -iTCP:${o.port} -sTCP:LISTEN names it), or ${move}` };
+    }
+}
+/**
+ * THE WRITER: one round of changes every `ms`, each said to `log` as the demo says it; a round that fails is said and
+ * the next one tried, and a round is never begun while the last one runs. Returns what stops it (idempotent).
+ */
+export function demoChanges(demo, ms, log) {
+    let busy = false;
+    const timer = setInterval(() => {
+        if (busy)
+            return;
+        busy = true;
+        demo.change().then((line) => log(line), (e) => log(`a change failed (the next one is tried in ${ms / 1000} s): ${e.message}`))
+            .finally(() => { busy = false; });
+    }, ms);
+    return () => clearInterval(timer);
+}
+/** The demo database closed once, however often it is asked: null when it closed, else what went wrong (said by the
+ *  caller, never swallowed). */
+export function closingOnce(demo) {
+    let closing = null;
+    return () => closing ??= demo.close().then(() => null, (e) => e.message);
+}
+/** What the crash path says of a demo database still closing when it stops waiting (`closedWithin`). */
+export const DEMO_STILL_CLOSING = (ms) => `closing the demo database: still closing after ${ms / 1000} s; its data may need seeding again at the next start`;
+/**
+ * A close waited for `ms` at most, and SAID when it is not done by then (`late`), never left silent: the crash path
+ * stops waiting so the supervisor can start the run again. The timer is cleared when the close wins, and is not
+ * unref'd, so a close that hangs is said before the process ends. A close that rejects rejects this.
+ */
+export async function closedWithin(closing, ms, late) {
+    let timer;
+    const timedOut = new Promise((resolve) => { timer = setTimeout(() => resolve(true), ms); });
+    try {
+        if (await Promise.race([closing.then(() => false), timedOut]))
+            late();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/cli/dev.js

@@ -2,6 +2,9 @@
  * `mason start` (one run per project): Mason for the project of this folder
  * (src/cli/project.ts), on the database its sources file names (src/cli/sources.ts), copying the tables it names.
  *
+ *   0. A DEMO PROJECT'S DATABASE (`mason init demo`, src/cli/demo.ts): hosted by this process, opened first on the port
+ *      the sources file's URL names, then connected to and read as any database is (by polling: it has no change log),
+ *      and changed every few seconds so the copy is seen keeping current.
  *   1. THE DATABASE (src/cli/preflight.ts checkSource): connect as the run will, say what to change when it cannot;
  *      a database on another machine only when the project was made with --remote. A database restored to another server
  *      is read again (its rows compared, the unchanged kept); another database is refused (mason destroy, then mason start).
@@ -30,7 +33,8 @@ import { createRunServer } from "./run-server.js";
 import { addedTables, rereadSources } from "./sources.js";
 import { newToken } from "./security.js";
 import { liveRun } from "./runs.js";
-import { DUCK_FILE, projectSource, theProject, writeConfig } from "./project.js";
+import { DEMO_DIR, DUCK_FILE, projectSource, theProject, writeConfig } from "./project.js";
+import { closedWithin, closingOnce, DEMO_STILL_CLOSING, demoChanges, demoChangesRefusal, demoPort, demoSettings, openDemo } from "./demo.js";
 import { postgresApiUrl, readPgTls } from "../api/postgres/listener.js";
 import { certificateFingerprint, elsewhereTip, ensureSelfSigned, listenerText, runListenerSettings, SELF_SIGNED_FILES } from "./pg-tls.js";
 import { startPostgresApi, timeoutMs } from "../api/postgres/server.js";
@@ -73,7 +77,34 @@ export function sourceMove(recorded, now) {
         return { action: "reread" };
     return { action: "same" };
 }
+/**
+ * The run, and whatever it hosts closed however it ends: a demo database that was opened is closed at the stop (after
+ * the sync, before the copy), and by this on every other way out — a failed step, a crash — its data flushed to its
+ * folder, a close that fails said.
+ */
 export async function dev(o) {
+    const hosted = { stopChanges: null, close: null };
+    try {
+        return await run(o, hosted);
+    }
+    finally {
+        hosted.stopChanges?.();
+        await closeDemo(hosted, null);
+    }
+}
+/** The demo database closed, if it is open: a failure said, never swallowed; `closed`, when given, said once it closed. */
+async function closeDemo(hosted, closed) {
+    const close = hosted.close;
+    if (close === null)
+        return;
+    hosted.close = null;
+    const failure = await close();
+    if (failure !== null)
+        say(`  closing the demo database: ${failure}`);
+    else if (closed !== null)
+        say(`  ${closed}`);
+}
+async function run(o, hosted) {
     const t = theProject(process.cwd());
     if ("problem" in t) {
         say(`mason start: ${t.problem}`);
@@ -89,13 +120,37 @@ export async function dev(o) {
         say(`mason start: Mason is already running for ${cfg.name} (pid ${other.pid}): mason status says what it is doing`);
         return 1;
     }
+    // A DEMO PROJECT IS POLLED (src/cli/demo.ts): its database has no change log, so replication is refused before anything starts
+    const demoRefused = demoChangesRefusal(cfg, o.changes);
+    if (demoRefused)
+        return failed("start", demoRefused, { json: false });
+    let demoChangeMs = null;
+    if (cfg.demo === true) {
+        try {
+            demoChangeMs = demoSettings(process.env).changeMs;
+        }
+        catch (e) {
+            say(`mason start: ${e.message}`);
+            return 1;
+        }
+    }
     const pinned = cliPinProblem(folder, o.version);
     if (pinned) {
         say(`mason start: ${pinned}`);
         return 1;
     }
+    // THE SOURCE (src/cli/sources.ts): the database and the tables to copy, from the project's sources file; a server's
+    // URL from its environment first (mason serve is configured by it alone). Read here, its failure said below where it
+    // always was (after the listener's checks): a demo project's port is needed first
+    const readSources = () => projectSource(project, process.env, { shellFirst: o.serve !== undefined });
+    const src = readSources();
+    // a demo project's database listens on the port its URL names (the one place it is kept), which no listener of the
+    // run's may take: read BEFORE the Postgres API's port is chosen and recorded, so the choice avoids it (a recorded or
+    // named port that is the demo's is refused by choosePgPort, nothing recorded), and the command server is kept off it
+    const demoAt = cfg.demo === true && !("message" in src) ? demoPort(src.resolved, src.from) : null;
+    const demoPorts = new Set(demoAt !== null && "port" in demoAt ? [demoAt.port] : []);
     // THE PORT IS THE PROJECT'S (src/cli/ports.ts): the first start's choice recorded, every later start on it or refused
-    const pg = await choosePgPort(process.env.MASON_PG_PORT, new Set(), cfg.pgPort ?? null);
+    const pg = await choosePgPort(process.env.MASON_PG_PORT, demoPorts, cfg.pgPort ?? null);
     if ("problem" in pg)
         return failed("start", pg, { json: false });
     if (cfg.pgPort !== pg.port) {
@@ -110,17 +165,41 @@ export async function dev(o) {
     const pgTls = listenerTls(listen, o.selfSignedTls, home, cfg);
     if ("problem" in pgTls)
         return failed("start", pgTls, { json: false });
-    const chosen = new Set([pg.port]);
+    const chosen = new Set([pg.port, ...demoPorts]);
     // a server's project folder is the team's, committed, and may be mounted read-only: mason serve writes nothing there
     const wrotePin = o.serve ? null : ensurePin(folder, o.version);
     if (wrotePin)
         say(`  wrote ${path.relative(project.root, wrotePin)}: version ${o.version}, the Mason this project is written for — commit it`);
-    // THE SOURCE (src/cli/sources.ts): the database and the tables to copy, from the project's sources file; a server's
-    // URL from its environment first (mason serve is configured by it alone)
-    const readSources = () => projectSource(project, process.env, { shellFirst: o.serve !== undefined });
-    const src = readSources();
     if ("message" in src)
         return failed("start", src, { json: false });
+    const logFile = path.join(home, "mason.log");
+    const log = fs.createWriteStream(logFile, { flags: "a" });
+    // one entry a line: a multi-line message's further lines indented under it (src/lib/log.ts `textEntry`);
+    // mason serve gets the same entry, for the container's stdout (src/cli/serve.ts)
+    const logLine = (l) => {
+        const entry = textEntry(`${new Date().toISOString()} `, l);
+        log.write(entry);
+        o.serve?.log(entry.trimEnd());
+    };
+    // THE DEMO DATABASE (src/cli/demo.ts), hosted here: opened before it is connected to, as any database is
+    let demo = null;
+    if (demoAt !== null) {
+        begin("Starting the demo database");
+        if ("problem" in demoAt) {
+            fail("Starting the demo database");
+            say(`  ${demoAt.problem}`);
+            return 1;
+        }
+        const opened = await openDemo({ home, port: demoAt.port, from: src.from, log: (l) => logLine(`[demo] ${l}`) });
+        if ("problem" in opened) {
+            fail("Starting the demo database");
+            say(`  ${opened.problem}`);
+            return 1;
+        }
+        demo = opened.demo;
+        hosted.close = closingOnce(opened.demo);
+        done(opened.done);
+    }
     const db = maskedUrl(src.resolved);
     begin(`Connecting to ${db}`);
     const checkSaid = [];
@@ -261,15 +340,6 @@ export async function dev(o) {
         say(`mason start: ${e.message}`);
         return 1;
     }
-    const logFile = path.join(home, "mason.log");
-    const log = fs.createWriteStream(logFile, { flags: "a" });
-    // one entry a line: a multi-line message's further lines indented under it (src/lib/log.ts `textEntry`);
-    // mason serve gets the same entry, for the container's stdout (src/cli/serve.ts)
-    const logLine = (l) => {
-        const entry = textEntry(`${new Date().toISOString()} `, l);
-        log.write(entry);
-        o.serve?.log(entry.trimEnd());
-    };
     begin("Opening the copy");
     const duckFile = path.join(home, DUCK_FILE);
     let store;
@@ -430,6 +500,7 @@ export async function dev(o) {
         slot: changes === "replication" ? repl.slot : "", changes, port: setupPort, token, folder: () => folder, root: project.root,
         // the web page (mason ui) is mason start's alone: mason serve's run serves none (src/cli/run-server.ts RunContext.page)
         page: o.serve === undefined,
+        demo: cfg.demo === true,
         users: { file: path.join(home, USERS_FILE), apiKey: cfg.apiKey, database: cfg.name, postgresUrl },
         ...(changes === "replication" ? { publication: { name: repl.publication, owned: repl.owned } } : {}),
         // the sources file is the list of what is added: a change to it is read by the sync at once
@@ -458,6 +529,9 @@ export async function dev(o) {
     writeConfig(home, cfg);
     done(`Mason is up: ${sync.state().length} table(s) added, kept current ${syncMode === "replication" ? `by logical replication (slot ${repl.slot}, publication ${repl.publication}${repl.owned ? "" : ", read as it is"})`
         : `every ${pollMs / 1000} s ${syncMode === "poll" ? "by polling with SELECTs (xmin)" : "by copying each table again whole (MASON_DUCK_SYNC=recopy)"}`}`);
+    // THE DEMO'S WRITER: a round of changes every MASON_DEMO_CHANGE_MS, begun once the run is up, said in the log
+    if (demo !== null && demoChangeMs !== null)
+        hosted.stopChanges = demoChanges(demo, demoChangeMs, (l) => logLine(`[demo] ${l}`));
     // the stop is in place BEFORE the ready line: a supervisor or a test signals on reading it, and a SIGTERM that found
     // no handler would end the run with the default action, never recording `running: null`
     let stopping = false;
@@ -470,11 +544,15 @@ export async function dev(o) {
             stopping = true;
             say(`FATAL ERROR: Mason: the copy's thread stopped (${reason})`);
             clearInterval(refreshFacts);
+            hosted.stopChanges?.();
             server.close();
             void (async () => {
                 // the sessions were told; the listener is closed so that none waits on a copy that cannot answer
                 const closed = api.close().catch((e) => say(`  closing the listener: ${e.message}`));
                 await Promise.race([closed, new Promise((r) => setTimeout(r, 2_000).unref())]);
+                // the demo database's data flushed to its folder before the log it writes to ends (dev() closes it otherwise)
+                // (a close still going after 2 s is said: the process ends without it, and the folder may not be whole)
+                await closedWithin(closeDemo(hosted, null), 2_000, () => say(`  ${DEMO_STILL_CLOSING(2_000)}`));
                 log.end();
                 resolve(1);
             })();
@@ -486,6 +564,7 @@ export async function dev(o) {
             o.serve?.stopping();
             say("\nmason start: stopping …");
             clearInterval(refreshFacts);
+            hosted.stopChanges?.();
             server.close();
             void (async () => {
                 try {
@@ -501,13 +580,25 @@ export async function dev(o) {
                 catch (e) {
                     say(`  closing the request log: ${e.message}`);
                 }
+                let syncStop = null;
                 try {
                     await sync.stop();
-                    await store.close();
-                    say(`  closed the copy (it stays in ${duckFile})`);
                 }
                 catch (e) {
-                    say(`  closing the copy: ${e.message}`);
+                    syncStop = e;
+                }
+                // the demo database after the sync (nothing reads it any more) and before the copy closes
+                await closeDemo(hosted, `closed the demo database (it stays in ${path.join(home, DEMO_DIR)}; mason destroy removes it)`);
+                if (syncStop !== null)
+                    say(`  closing the copy: ${syncStop.message}`);
+                else {
+                    try {
+                        await store.close();
+                        say(`  closed the copy (it stays in ${duckFile})`);
+                    }
+                    catch (e) {
+                        say(`  closing the copy: ${e.message}`);
+                    }
                 }
                 if (syncMode === "replication")
                     say(`  replication slot ${repl.slot} stays on ${source.database}, holding its WAL until the next mason start reads it (mason destroy drops it)` +
@@ -528,6 +619,8 @@ export async function dev(o) {
     // the web page by its command, never its URL: the URL carries the run's token, and this goes to dev.log
     if (o.serve === undefined)
         say("  Web UI  mason ui  (the status page and the users, in your browser)");
+    if (demoChangeMs !== null)
+        say(`  Demo  a new order lands every ${demoChangeMs / 1000} s: mason status shows the copy keeping up`);
     const elsewhere = elsewhereTip(pgTls.listener);
     if (elsewhere)
         say(`  ${elsewhere}`);
@@ -571,6 +664,6 @@ function listenerTls(listen, selfSigned, home, cfg) {
 /** The line a run writes once it answers commands: what `mason start` in the background waits for (src/cli/background.ts),
  *  and what tells its supervisor a death after it is a crash to restart (src/cli/supervise.ts, which defines it). */
 export const READY = READY_LINE;
-/** The one sentence of how the pieces fit, printed first by `mason start` and at the top of its help and the README. */
+/** The one sentence of how the pieces fit, printed first by `mason start` and at the top of its help. */
 export const PROJECT_LINE = "A Mason project is your app's folder: mason/sources/ names the database and the tables to copy, yours to commit; " +
     "this machine's copy of your data and Mason's state are in .mason/, rebuilt from that file.";

package/dist/src/cli/doctor.js

@@ -111,11 +111,11 @@ function portOf(url) {
     } // not a URL: no port to compare with
 }
 /** The database a URL names: reachable, its version, what this user can read. */
-export async function databaseCheck(url) {
+export async function databaseCheck(url, o = {}) {
     const parsed = parseSource(url);
     if ("problem" in parsed)
         return { name: "database", ok: false, detail: parsed.problem };
-    const connected = await connectSource(parsed.source);
+    const connected = await connectSource(parsed.source, o);
     if ("failure" in connected)
         return { name: "database", ok: false, detail: `${maskedUrl(parsed.source.url)}: ${connected.failure.message}${connected.failure.hints.map((h) => `\n    - ${h}`).join("")}` };
     let facts;
@@ -168,6 +168,9 @@ export function nextSteps(checks, run, project) {
         return [["mason doctor", `again, once Node ${NODE_MIN} or later is installed`]];
     if (bad("project") && run === null)
         return [["mason doctor", "again, once .mason/config.json is repaired or moved aside (the detail above says how)"]];
+    // the demo database is hosted by the run itself (src/cli/demo.ts): down until mason start makes it
+    if (bad("database") && project?.config.demo === true)
+        return [["mason start", "hosts the demo database, then copies its tables"]];
     if (bad("database"))
         return [["mason start", `once the connection works (the detail above says how; the URL is in ${project ? `${project.dir}/config.json` : ".mason/config.json"})`]];
     if (project === null)
@@ -224,7 +227,7 @@ export async function doctor(argv, deps = {}) {
             // the database the project's sources file names (src/cli/sources.ts): a file that cannot be read is the failing line
             const src = projectSource(project);
             checks.push("message" in src ? { name: "database", ok: false, detail: `${src.message}${src.why ? `: ${src.why.replace(/\n/g, "; ")}` : ""}. ${src.fix?.split("\n")[0] ?? ""}`.trim() }
-                : await databaseCheck(src.resolved));
+                : await databaseCheck(src.resolved, { demo: project.config.demo === true }));
         }
         // a project here whose config cannot be read: init would refuse, so "Ready: mason init" would send a person nowhere
         if ("code" in which && which.code === "bad_config")

package/dist/src/cli/guides.js

@@ -7,6 +7,7 @@
  *
  * A guide's name is never a command's (tests/cli-help.test.ts): one word never means two pages.
  */
+import { DEMO_ADDED_TABLES, DEMO_TABLES, DEMO_TABLE_TO_ADD } from "../demo/seed.js";
 /** The guides, by the name `mason help <guide>` takes. */
 export const GUIDES = {
     agent: "driving Mason from a coding agent: the commands in order, --json and its shapes, exit codes, failures",
@@ -29,16 +30,24 @@ async function agentGuide() {
     // imported here, not at the top: the registry imports this file for the HELP usage
     const { STEPS } = await import("./registry.js");
     const { FAILURE_CODES } = await import("./command.js");
-    const noJson = new Set(["help"]);
     const w = Math.max(...STEPS.flatMap(([, cs]) => cs.map((c) => c.name.length))) + "mason  --json".length;
-    const commands = STEPS.map(([step, cs]) => `  ${step}\n${cs.map((c) => `    ${`mason ${c.name}${noJson.has(c.name) ? "" : " --json"}`.padEnd(w)}  ${c.summary}`).join("\n")}`).join("\n");
+    const commands = STEPS.map(([step, cs]) => `  ${step}\n${cs.map((c) => `    ${`mason ${c.name}${Object.hasOwn(c.options, "json") ? " --json" : ""}`.padEnd(w)}  ${c.summary}`).join("\n")}`).join("\n");
     const codes = Object.entries(FAILURE_CODES).map(([code, what]) => `    ${code.padEnd(12)} ${what}`).join("\n");
     return `DRIVING MASON FROM A CODING AGENT — the same commands a person runs, answered as data
 
   Every command prints for a person, or with --json one JSON object for a program. One prints text alone: mason help
-  (this reference); mason logs --json is the log's lines, or with --requests the request log. Nothing a command prints
+  (this reference); mason mcp's stdout is the MCP protocol's, so it takes no --json and says a failure to start on
+  stderr; mason logs --json is the log's lines, or with --requests the request log. Nothing a command prints
   refers to a file this package does not ship.
 
+  AN AGENT WITH MCP (Claude Code, Claude Desktop, any MCP client) adds Mason as an MCP server first, then asks with
+  its tools rather than through a shell: tables (each copy's rows and how current it is), describe, query (rows with
+  their Postgres types, or the refusal with what to write instead) and explain. In the project's folder, Mason running:
+    mason user add claude --json              its url, printed once
+    claude mcp add mason --env MASON_URL="<url>" -- mason mcp
+  (the server's name before --env, which takes every value after it). mason help mcp says the rest: Claude Desktop's
+  config, a mason serve elsewhere.
+
   THE COMMANDS, in the order a project takes them (mason --help lists the same):
 ${commands}
 
@@ -74,21 +83,26 @@ ${codes}
         exclude: [raw_body]       every column but these
       sessions:
         key: [tenant_id, id]      only for a table with no primary key: the unique columns to copy it by (polling only)
-  mason add and mason remove edit one entry of it, keep the rest as it was, and take effect at once; an edit by hand is
-  read at the next mason start (or the next add or remove). Column types are read from the database at every start.
+  mason add and mason remove edit one entry of it and keep the rest as it was, Mason running or not: with it running
+  they take effect at once, else at mason start. An edit by hand is read at the next mason start (or the next add or
+  remove). Column types are read from the database at every start.
 
   A FIRST SESSION, as a shell runs it:
-    mason doctor --json && mason init --json && mason start --json
+    mason doctor --json && mason init --json
     mason tables --json                       choose the tables (rows, key, whether one can be added)
-    mason add orders customers --json && mason wait --json
+    mason add orders customers --json         added to the sources file, checked against the database
+    mason start --json && mason wait --json   Mason in the background; until every added table is copied
     mason user add my-tool --json             the URL and password a tool connects with
     mason status --json                       each table's copy, and the last day's slow and refused statements
+  With no database to hand, in a new folder: mason init demo --json && mason start --json — a demo database Mason
+  hosts itself (${DEMO_TABLES.join(", ")}), changed every few seconds, read by polling only. Init adds
+  ${DEMO_ADDED_TABLES.join(", ")}; ${DEMO_TABLE_TO_ADD} is left to add: mason add ${DEMO_TABLE_TO_ADD} --json && mason wait --json, after mason start.
 `;
 }
 const REPO = "https://github.com/embeddable-hq/mason-data/blob/main";
 /**
  * `mason help production` (the journey from running it locally to deploying it, on the mason-data image): the
- * README's "On a server", offline and short — what travels, what the server needs, how it runs, how it is upgraded.
+ * README's "Going to production", offline and short — what travels, what the server needs, how it runs, how it is upgraded.
  */
 export function productionGuide() {
     return `GOING TO PRODUCTION — the project folder (mason/sources/, mason/mason.yml) is all that travels: its sources file
@@ -113,6 +127,16 @@ names the tables the server copies, and its url: names the variable that holds t
    write its file, so run one replica, with no autoscaling, and stop the old container before the new one starts.
    GET /healthz on MASON_HEALTH_PORT (4140) answers 503 while it starts and 200 once it serves; the first start takes
    about 15 seconds before that, then copies the tables.
+   MEMORY: the copy may use half the container's memory limit by default (else half the machine's RAM); the other
+   half is the page cache, Node and the catalog (~820 MB). Give the container enough that the page cache holds the
+   columns your dashboards read: a query over a column it does not hold runs at the disk's speed. The benchmark's copy
+   was about a fifth of its tables in Postgres (10.1 GiB to 1.8 GiB, on a 15 GiB machine); mason status says yours.
+   To set it, MASON_DUCKDB_MEMORY=4GB with the container's limit about twice that. A statement past it fails alone
+   (53200) and the run goes on; a value near the container's limit is an OOM kill.
+   CPU: memory first, then cores. The benchmark's machine (4 vCPU Graviton3, 15 GiB) answered 32 clients at 10 M rows,
+   12 statements a second at a p95 of 3.5 s, as many a second as at 8 clients: more clients waited longer. A copy's
+   readers take about a core each while it runs (MASON_COPY_PARALLEL, default 3). The image is arm64 (the measured
+   one) and amd64. Which settings to decide: ${REPO}/deploy/mason-data/README.md#settings
 
 3. CONNECT THE TOOLS: beside the server (docker compose exec mason …), a user is a password a tool keeps:
      mason user add metabase                        its URL and password, printed once