@mason-data/cli 0.7.0 → 0.8.0

package/dist/src/cli/init.js

@@ -1,16 +1,19 @@
 /**
  * `mason init [<postgres url>]` (a project directory is initiated as other CLIs do it, by `mason init`):
- * makes the folder it is run in a Mason project. The database's URL comes from the argument, else the folder's
- * `.env.local` or `.env` (`DATABASE_URL`, the variable web frameworks use), else the shell's. The database is checked as
- * `mason start` checks it (checkSource) and nothing is written when it fails, unless --skip-check says the database is
- * not up yet.
+ * makes the folder it is run in a Mason project. The database's URL comes from the argument, else `MASON_DATABASE_URL`
+ * (Mason's own, for a database other than the app's), else `DATABASE_URL` (the variable web frameworks use), each from
+ * the folder's `.env.local`, then `.env`, then the shell (`appDatabaseUrl`) — or, when a sources file is here already (a
+ * clone), the variable its `url: ${…}` names, read the same way, so the database checked is the one the run copies from.
+ * The database is checked as `mason start` checks it (checkSource) and nothing is written when it fails, unless
+ * --skip-check says the database is not up yet.
  *
  * It writes `.mason/config.json` (0600: the project's name and Mason's key), the project's source file
- * (`mason/sources/<database>.yml`, src/cli/sources.ts: `kind: postgres`, `url: ${DATABASE_URL}`, `tables: {}`) — the
- * URL itself in `.env`, never in a committed file (the sources file is the developer's to commit, so the URL stays out
- * of it): nothing more when it came from there, the line added when it came from the argument or the shell — and adds
- * `.mason/` and that .env to the folder's .gitignore. It refuses a folder that is in a project already (here or above)
- * — but for a project with no source file (one an older Mason made), whose source file it writes, nothing else changed.
+ * (`mason/sources/<database>.yml`, src/cli/sources.ts: `kind: postgres`, `url: ${DATABASE_URL}` — or the variable the
+ * URL was read from, `tables: {}`, and `database: <name>` only under `--database`) — the URL itself in `.env`, never in a committed file (the sources file is the
+ * developer's to commit, so the URL stays out of it): nothing more when it came from there, the line added when it came
+ * from the argument or the shell — and adds `.mason/` and that .env to the folder's .gitignore. It refuses a folder that
+ * is in a project already (here or above) — but for a project with no source file (one an older Mason made), whose
+ * source file it writes, nothing else changed.
  *
  * `mason init demo` (src/cli/demo.ts) writes the same files for a database Mason hosts itself: the demo's URL, on a port
  * free now, in `.env` (the one place the port is kept), three of the demo's four tables already added (the fourth,
@@ -28,46 +31,57 @@ import { version } from "./version.js";
 import { parseVersion, PIN_FILE } from "../lib/project-version.js";
 import { appDatabaseUrl, appEnvValue, appendEnvLine, ENV_FILE } from "../lib/dotenv.js";
 import { DEMO_DIR, NAME_RE, STATE_DIR, brokenProblem, findProject, ignoresStateDir, nameFromFolder, newConfig, writeConfig } from "./project.js";
-import { DEMO_ADDED_TABLES, DEMO_ARG, DEMO_PORT, DEMO_TABLE_TO_ADD, demoUrl } from "./demo.js";
+import { DEMO_ADDED_TABLES, DEMO_ARG, DEMO_PORT, DEMO_SYNC, DEMO_TABLE_TO_ADD, demoUrl } from "./demo.js";
 import { freePort } from "./ports.js";
+import { databaseNameProblem, DEFAULT_DATABASE } from "../lib/database-name.js";
+import { DEFAULT_SYNC, syncText } from "../lib/table-sync.js";
+import { newRolesText, rolesFile } from "./roles.js";
 import { newSourceText, OLD_TABLES_DIR, parseSourceText, shownPath, sourceFileNames, sourceNameFor, sourcesDir } from "./sources.js";
-export const INIT_USAGE = `usage: mason init [<postgres url> | demo] [--name <name>] [--folder <dir>] [--remote] [--skip-check] [--json]
+export const INIT_USAGE = `usage: mason init [<postgres url> | demo] [--name <name>] [--database <name>] [--folder <dir>] [--remote] [--skip-check] [--json]
 
   Makes this folder a Mason project — run it in your app's folder. It checks it can read the database (and writes
   nothing when it cannot), then creates:
-    .mason/                   this machine's: Mason's key and, once Mason runs, its copy and state (gitignored)
-    mason/sources/<db>.yml    the database and the tables to copy (mason add adds them) — commit it
+    .mason/                   this machine's: Mason's key and, once Mason runs, its synced data and state (gitignored)
+    mason/sources/<db>.yml    the database and the tables to sync (mason add adds them) — commit it
+    mason/roles.yml           who may read what: one role, everything (tables: all), the default of a user added
+                              without --role, so every user reads every synced table until you narrow it — commit it
     mason/mason.yml           the Mason version the project is written for — commit it: production runs that version
-  The source file says url: \${DATABASE_URL}: the URL itself is in .env (written there when you give it here or it is
-  only in the shell), never in a committed file. .mason/ and that .env go into .gitignore. Every other mason command
-  then works anywhere in this folder. In a project with no source file (an older Mason's), it writes that file alone.
+  With no URL it reads MASON_DATABASE_URL, else your app's DATABASE_URL, each from .env.local, then .env, then the
+  shell. The source file names the variable read, url: \${DATABASE_URL} — \${MASON_DATABASE_URL} when that is the one
+  read, or when a URL given here is another database than your app's DATABASE_URL: the URL itself is in .env (written
+  there when you give it here or it is only in the shell), never in a committed file. .mason/ and that .env go into
+  .gitignore. Every other mason command then works anywhere in this folder. A source file already here (a clone of the
+  project) is kept, and a bare mason init reads the variable it names; a roles file already here is kept. In a project
+  with no source file (an older Mason's), it writes that file alone, and the roles file when there is none.
   mason init demo, in a new folder, makes a project on a demo database Mason hosts itself (a shop: customers, products,
   orders, order_items): mason start makes it in .mason/demo/ and changes it every few seconds. Three of its tables are
-  added; the fourth is yours to add after mason start (mason add ${DEMO_TABLE_TO_ADD}), to watch its copy begin.
+  added; the fourth is yours to add after mason start (mason add ${DEMO_TABLE_TO_ADD}), to watch its first sync begin.
 
-    mason init                                          DATABASE_URL from .env.local, .env or the shell
+    mason init                                          MASON_DATABASE_URL, else DATABASE_URL (.env or the shell)
     mason init postgres://me:secret@localhost:5432/shop
     mason init demo                                     a demo database Mason hosts itself: nothing to install
     mason init --folder db/mason --name shop-admin      the project's files elsewhere; another name
     mason init postgres://me:secret@db.example.com/shop --remote
 
-  --name <name>     the project's name: the database name a tool connects to on the Postgres API (default: this folder's)
+  --name <name>     the project's name, which its replication slot is named for (default: this folder's)
+  --database <name> the database name a tool connects with, written as database: in the source file (default: none
+                    written, so tools connect with ${DEFAULT_DATABASE}): your database's own, and a tool keeps the name it has
   --folder <dir>    where sources/ goes, relative to this folder (default mason; . for this folder itself)
   --remote          go ahead with a database on another machine (read the warnings mason init prints); not with demo
   --skip-check      write the project without connecting (the database is not up yet); mason start checks it; not with demo
   --json            as data: { name, root, folder, config, demo (true for the demo database's project, else false),
-                    source: { name (the source's: its file's), file, url (as the file writes it), env (the .env line
-                    written, its value masked, or null) }, database: { url (password masked), from, version, tables },
-                    warnings, next }
+                    source: { name (the source's: its file's), file, url (as the file writes it), database (the name
+                    a tool connects with, or null when the file has a mistake), env (the .env line written, its value masked, or null) }, roles: { file, written (false: one was here, and kept) },
+                    database: { url (password masked), from, version, tables }, warnings, next }
 `;
 export const INIT = {
     name: "init",
-    summary: "make this folder a Mason project on your Postgres: mason init (DATABASE_URL from .env), mason init postgres://… or demo",
+    summary: "make this folder a Mason project on your Postgres: mason init (its URL from .env), mason init postgres://… or demo",
     usage: INIT_USAGE,
-    options: { name: { type: "string" }, folder: { type: "string" }, remote: { type: "boolean" }, "skip-check": { type: "boolean" }, json: { type: "boolean" } },
-    json: ["name", "root", "folder", "config", "demo", "source", "database", "warnings", "next"],
+    options: { name: { type: "string" }, database: { type: "string" }, folder: { type: "string" }, remote: { type: "boolean" }, "skip-check": { type: "boolean" }, json: { type: "boolean" } },
+    json: ["name", "root", "folder", "config", "demo", "source", "roles", "database", "warnings", "next"],
 };
-/** Why `name` cannot be this project's, or null: not a name the Postgres API's database and the slot take. */
+/** Why `name` cannot be this project's, or null: not a name its replication slot takes. */
 export function nameProblem(name) {
     if (!NAME_RE.test(name))
         return `${JSON.stringify(name)} is not a project name: lower-case letters, digits, - and _, starting with a letter or digit (--name sets it)`;
@@ -85,7 +99,7 @@ export function withIgnored(gitignore, files = []) {
     let tail = "";
     if (!ignoresStateDir(text)) {
         added.push(`${STATE_DIR}/`);
-        tail += `# Mason: this machine's key, copy and state (mason init)\n${STATE_DIR}/\n`;
+        tail += `# Mason: this machine's key, synced data and state (mason init)\n${STATE_DIR}/\n`;
     }
     for (const f of files)
         if (!ignoresFile(text, f)) {
@@ -123,8 +137,13 @@ export function committedInGit(root, file) {
  * when the folder's .env.local or .env gives it already. DATABASE_URL when the folder's files give it no other value
  * (one only in the shell is written down: the next shell may not have it); else MASON_DATABASE_URL, so the app's own
  * DATABASE_URL is never changed under it. A problem when both name other databases.
+ * A URL READ FROM A VARIABLE (`found`, a bare mason init's `appDatabaseUrl`) is kept in that variable: the one read is
+ * the one named, and nothing is written when a folder's file gave it — so a MASON_DATABASE_URL is never written again as
+ * DATABASE_URL; one only in the shell is written down under its own name.
  */
-export function urlVariable(root, url) {
+export function urlVariable(root, url, found = null) {
+    if (found !== null)
+        return { variable: found.variable, line: found.file === null ? `${found.variable}=${url}` : null };
     for (const variable of ["DATABASE_URL", "MASON_DATABASE_URL"]) {
         const inFiles = appEnvValue(root, variable, {});
         if (inFiles === null)
@@ -132,10 +151,10 @@ export function urlVariable(root, url) {
         if (inFiles.value === url)
             return { variable, line: null };
     }
-    return { problem: "this folder's .env names DATABASE_URL and MASON_DATABASE_URL for other databases: set one of them to the database Mason copies from, then mason init again" };
+    return { problem: "this folder's .env names DATABASE_URL and MASON_DATABASE_URL for other databases: set one of them to the database Mason syncs from, then mason init again" };
 }
 /** `.env` with `line` added (made when there is none). */
-const addEnvLine = (root, line) => appendEnvLine(root, line, "the database Mason copies from (mason/sources/ names it; never commit this file)");
+const addEnvLine = (root, line) => appendEnvLine(root, line, "the database Mason syncs from (mason/sources/ names it; never commit this file)");
 /** A `.env` line as it is said: its value's password masked. */
 const maskedLine = (line) => { const eq = line.indexOf("="); return `${line.slice(0, eq)}=${maskedUrl(line.slice(eq + 1))}`; };
 export async function init(argv, cwd = process.cwd(), deps = {}) {
@@ -193,40 +212,65 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
     const named = nameProblem(name);
     if (named)
         return usage(named);
+    const connectName = f.values.database ?? null;
+    const badDatabase = connectName === null ? null : databaseNameProblem(connectName);
+    if (badDatabase !== null)
+        return usage(`--database: ${badDatabase}`);
+    // THE SOURCE FILE: one already here (a clone of the project) is kept; else written, its URL a variable of .env
+    const kept = sourceFileNames(folder)[0] ?? null;
+    if (demo && kept !== null) {
+        // a clone's sources file names the team's database: the demo never takes its place
+        return failed("init", { message: `${path.relative(root, path.join(sourcesDir(folder), kept))} is already here: mason init demo makes a project of its own`, code: "refused",
+            fix: "run it in a new folder (mkdir mason-demo && cd mason-demo && mason init demo), or mason init here for the database that file names" }, { json, io });
+    }
+    const keptPath = kept === null ? null : path.join(sourcesDir(folder), kept);
+    if (connectName !== null && keptPath !== null)
+        return usage(`--database writes a new source file, and ${path.relative(root, keptPath)} is here already`, `write database: ${connectName} in it`);
+    const keptFile = kept === null || keptPath === null ? null : parseSourceText(fs.readFileSync(keptPath, "utf8"), kept.replace(/\.ya?ml$/, ""), keptPath);
+    const keptVar = keptFile !== null && !("problems" in keptFile) && "env" in keptFile.url ? keptFile.url.env : null;
     // the demo's URL names a port free now, and is the one place the port is kept: mason start reads it from there
     let url = demo ? demoUrl(await freePort(DEMO_PORT)) : f.positionals[0] ?? null;
     let from = "";
     let envFile = null; // the folder's file the URL was read from (.env.local or .env): ignored with .mason/
+    let envVariable = null; // the variable envFile holds the URL in, set with it: the warning names it
+    // the variable a bare mason init read the URL from: the one the sources file names (urlVariable)
+    let found = null;
     if (url === null) {
-        const found = appDatabaseUrl(root);
+        // THE KEPT FILE DECIDES WHAT IS READ: the variable its url: names, as the run reads it (.env.local, .env, the shell),
+        // so the database init checks is the one mason start copies from; MASON_DATABASE_URL, then DATABASE_URL, only when
+        // no kept file names one (a clone naming DATABASE_URL was checked against a MASON_DATABASE_URL in the shell)
+        if (keptVar !== null && keptPath !== null) {
+            const v = appEnvValue(root, keptVar, deps.env ?? process.env);
+            const file = shownPath(root, keptPath);
+            if (v === null) {
+                return failed("init", { message: `which database? ${file} names url: \${${keptVar}}, and this folder has no ${keptVar}`, code: "usage",
+                    why: `mason start reads the URL from ${keptVar}, so mason init checks that one`,
+                    fix: `put it in this folder's .env as ${keptVar}=postgres://… (the variable ${file} names), or give its URL on the command line: mason init writes it there`,
+                    next: [["mason init postgres://user:password@localhost:5432/your_app", `its URL, given: written to .env as ${keptVar}`], ["mason init", `again, once .env has ${keptVar}`]] }, { json, io });
+            }
+            found = { url: v.value, variable: keptVar, from: `${keptVar} in ${v.from}`, file: v.file };
+        }
+        else
+            found = appDatabaseUrl(root, deps.env ?? process.env);
         if (!found) {
             // the fixes ARE the next commands, so a coding agent reads them as such too
-            return failed("init", { message: "which database? none is named, and this folder has no DATABASE_URL", code: "usage",
-                fix: "give its URL on the command line, or put it in this folder's .env as DATABASE_URL=postgres://… (your app's, usually)",
-                next: [["mason init postgres://user:password@localhost:5432/your_app", "its URL, given"], ["mason init", "again, once .env has DATABASE_URL"],
+            return failed("init", { message: "which database? none is named, and this folder has no MASON_DATABASE_URL or DATABASE_URL", code: "usage",
+                fix: "give its URL on the command line, or put it in this folder's .env as DATABASE_URL=postgres://… (your app's, usually) or as MASON_DATABASE_URL=postgres://… (read first: a database other than your app's)",
+                next: [["mason init postgres://user:password@localhost:5432/your_app", "its URL, given"], ["mason init", "again, once .env has MASON_DATABASE_URL or DATABASE_URL"],
                     ["mason init demo", "a demo database Mason makes itself: nothing to install"]] }, { json, io });
         }
         url = found.url;
-        from = ` (DATABASE_URL in ${found.from})`;
+        from = ` (${found.from})`;
         envFile = found.file;
+        envVariable = found.variable;
     }
     const parsed = parseSource(url);
     if ("problem" in parsed)
         return usage(parsed.problem);
     const remote = f.values.remote === true || sourceless?.config.remote === true;
-    // THE SOURCE FILE: one already here (a clone of the project) is kept; else written, its URL a variable of .env
-    const kept = sourceFileNames(folder)[0] ?? null;
-    if (demo && kept !== null) {
-        // a clone's sources file names the team's database: the demo never takes its place
-        return failed("init", { message: `${path.relative(root, path.join(sourcesDir(folder), kept))} is already here: mason init demo makes a project of its own`, code: "refused",
-            fix: "run it in a new folder (mkdir mason-demo && cd mason-demo && mason init demo), or mason init here for the database that file names" }, { json, io });
-    }
-    const keptText = kept === null ? null : fs.readFileSync(path.join(sourcesDir(folder), kept), "utf8");
-    const keptFile = kept === null ? null : parseSourceText(keptText, kept.replace(/\.ya?ml$/, ""), path.join(sourcesDir(folder), kept));
-    const keptVar = keptFile !== null && !("problems" in keptFile) && "env" in keptFile.url ? keptFile.url.env : null;
     // a kept file's variable gets this URL in .env when the folder's files give it none; one they give another value is said
     const keptValue = keptVar === null ? null : appEnvValue(root, keptVar, {});
-    const where = kept === null ? urlVariable(root, url)
+    const where = kept === null ? urlVariable(root, url, found)
         : { variable: keptVar ?? "", line: keptVar !== null && keptValue === null ? `${keptVar}=${url}` : null };
     if ("problem" in where)
         return failed("init", { message: where.problem, code: "refused" }, { json, io });
@@ -241,10 +285,12 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
     line(st.bold(`Making ${name} a Mason project in ${root}`));
     const notes = [];
     if (keptValue !== null && keptValue.value !== url)
-        notes.push(`${kept} reads ${keptVar} from ${keptValue.from}, which is ${maskedUrl(keptValue.value)}: mason start copies from that one, not ${db}`);
+        notes.push(`${kept} reads ${keptVar} from ${keptValue.from}, which is ${maskedUrl(keptValue.value)}: mason start syncs from that one, not ${db}`);
     let database = { url: db, from: from ? from.slice(2, -1) : null, version: null, tables: null };
     const rel = (p) => path.relative(root, p) || ".";
     const sourceFile = kept !== null ? path.join(sourcesDir(folder), kept) : path.join(sourcesDir(folder), `${sourceNameFor(parsed.source.database)}.yml`);
+    const rolesPath = rolesFile(folder);
+    const rolesKept = fs.existsSync(rolesPath);
     // the folder an older Mason listed the tables in: read by nothing (no backwards compatibility before v1.0), said
     const oldTables = path.join(folder, OLD_TABLES_DIR);
     if (fs.existsSync(oldTables))
@@ -252,7 +298,7 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
     // A DATABASE ON ANOTHER MACHINE, NOT CONFIRMED: not a failed step (the check passed, or was skipped) but a stop before
     // anything is written, said as one failure (remoteConfirmation) — the same words whether the check ran or not
     const confirmRemote = () => failed("init", remoteConfirmation(parsed.source.host, { cmd: "mason init",
-        wayOut: "run the same mason init again with --remote: that says yes, copy from that machine",
+        wayOut: "run the same mason init again with --remote: that says yes, sync from that machine",
         next: [["mason init --remote <url>", "the same command, confirmed"]] }), { json, io });
     try {
         if (demo) {
@@ -288,27 +334,40 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
             database = { ...database, version: checked.facts.versionText, tables: checked.facts.tables.length };
         }
         if (sourceless)
-            await steps.step(`Keeping ${STATE_DIR}/config.json`, () => undefined, () => `Kept ${STATE_DIR}/config.json: the project ${name}, its key and its copy`);
+            await steps.step(`Keeping ${STATE_DIR}/config.json`, () => undefined, () => `Kept ${STATE_DIR}/config.json: the project ${name}, its key and its synced data`);
         else {
             await steps.step(`Writing ${STATE_DIR}/config.json`, () => {
                 writeConfig(path.join(root, STATE_DIR), newConfig(name, path.relative(root, folder) || ".", remote, { demo }));
             }, () => `Wrote ${STATE_DIR}/config.json: Mason's key (this machine's)`);
         }
         if (kept !== null) {
-            await steps.step(`Keeping ${rel(sourceFile)}`, () => undefined, () => `Kept ${rel(sourceFile)}: the database and the tables this project copies`);
+            await steps.step(`Keeping ${rel(sourceFile)}`, () => undefined, () => `Kept ${rel(sourceFile)}: the database and the tables this project syncs`);
             if (keptFile !== null && "problems" in keptFile)
                 notes.push(`${rel(sourceFile)} has ${keptFile.problems.length === 1 ? "a mistake" : "mistakes"}, which mason start refuses: ${keptFile.problems.join("; ")}`);
         }
         else {
             await steps.step(`Writing ${rel(sourceFile)}`, () => {
                 fs.mkdirSync(path.dirname(sourceFile), { recursive: true });
-                fs.writeFileSync(sourceFile, newSourceText(`\${${where.variable}}`, demo ? DEMO_ADDED_TABLES : []));
-            }, () => `Wrote ${rel(sourceFile)}: the database (url: \${${where.variable}}) and the tables to copy, ${demo ? `the demo's ${DEMO_ADDED_TABLES.length} added — mason add ${DEMO_TABLE_TO_ADD} adds the fourth` : "none yet (mason add)"} — commit it`);
+                fs.writeFileSync(sourceFile, newSourceText(`\${${where.variable}}`, demo ? DEMO_ADDED_TABLES : [], demo ? DEMO_SYNC : DEFAULT_SYNC, connectName));
+            }, () => `Wrote ${rel(sourceFile)}: the database (url: \${${where.variable}}), ${connectName === null ? "" : `database: ${connectName}, `}sync: ${syncText(demo ? DEMO_SYNC : DEFAULT_SYNC)} ` +
+                `(${demo ? "every table polled every 5 s" : "each table read once, then again only by mason sync <table>"}) and the tables to sync, ` +
+                `${demo ? `the demo's ${DEMO_ADDED_TABLES.length} added — mason add ${DEMO_TABLE_TO_ADD} adds the fourth` : "none yet (mason add)"} — commit it`);
+        }
+        // THE ROLES FILE (src/cli/roles.ts newRolesText): today's access said in a committed file — every user reads every
+        // copied table, as the default role everything — kept when one is here (a clone of the project)
+        if (rolesKept)
+            await steps.step(`Keeping ${rel(rolesPath)}`, () => undefined, () => `Kept ${rel(rolesPath)}: the roles and the default for a user added without --role`);
+        else {
+            await steps.step(`Writing ${rel(rolesPath)}`, () => {
+                fs.mkdirSync(path.dirname(rolesPath), { recursive: true });
+                fs.writeFileSync(rolesPath, newRolesText());
+            }, () => `Wrote ${rel(rolesPath)}: every user reads every synced table (default: everything, tables: all) — narrow it with a second role — commit it`);
         }
         if (where.line !== null) {
             const envLine = where.line;
             await steps.step(`Writing ${where.variable} to .env`, () => addEnvLine(root, envLine), () => `Wrote ${maskedLine(envLine)} to .env: the URL the source file names, kept out of git`);
             envFile = ENV_FILE;
+            envVariable = where.variable;
         }
         // THE VERSION PIN (src/cli/pin.ts): what production's image is held to. A checkout's mason (`dev`) has none to write
         const cli = deps.version ?? version();
@@ -329,7 +388,7 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
             return after === null ? "already" : before === null ? "made" : after.added.join(" and ");
         }, (r) => r === "already" ? `.gitignore already ignores ${ignored}` : r === "made" ? `Made .gitignore, ignoring ${ignored}` : `Added ${r} to .gitignore`);
         if (envFile && committedInGit(root, envFile)) {
-            notes.push(`${envFile} holds the database URL (DATABASE_URL) and is committed in git: git rm --cached ${envFile} takes it out of the next commit (the file stays); then change the password`);
+            notes.push(`${envFile} holds the database URL (${envVariable}) and is committed in git: git rm --cached ${envFile} takes it out of the next commit (the file stays); then change the password`);
         }
     }
     catch (e) {
@@ -342,25 +401,27 @@ export async function init(argv, cwd = process.cwd(), deps = {}) {
             why: parsed.source.remote ? undefined : `the database's URL is ${db}${from}` }, { json, io });
     }
     const next = demo ? [
-        ["mason start", "the demo database and Mason, in the background: its tables copied, then kept current"],
-        [`mason add ${DEMO_TABLE_TO_ADD}`, "the demo's fourth table, once Mason is up: watch its copy begin"],
-        ["mason status", "the copy keeping up with the demo's changes"],
+        ["mason start", "the demo database and Mason, in the background: its tables synced, then kept current"],
+        [`mason add ${DEMO_TABLE_TO_ADD}`, "the demo's fourth table, once Mason is up: watch its first sync begin"],
+        ["mason status", "the synced data keeping up with the demo's changes"],
         ["mason user add <name>", "a user for psql or a BI tool: its password and URL, printed once"],
     ] : [
         ["mason start", "Mason in the background, for this folder"],
         ["mason tables", "the database's tables and their columns"],
-        ["mason add <table>", "copy a table into Mason"],
+        ["mason add <table>", "sync a table into Mason"],
     ];
     if (json) {
         say(jsonText(INIT, { name, root, folder: path.relative(root, folder) || ".", config: path.join(root, STATE_DIR, "config.json"), demo,
             source: { name: path.basename(sourceFile).replace(/\.ya?ml$/, ""), file: sourceFile, url: keptFile !== null && !("problems" in keptFile) ? ("env" in keptFile.url ? `\${${keptFile.url.env}}` : maskedUrl(keptFile.url.literal)) : `\${${where.variable}}`,
+                database: keptFile === null ? connectName ?? DEFAULT_DATABASE : "problems" in keptFile ? null : keptFile.database ?? DEFAULT_DATABASE,
                 env: where.line === null ? null : maskedLine(where.line) },
+            roles: { file: rolesPath, written: !rolesKept },
             database, warnings: notes }, next));
         return 0;
     }
     for (const n of notes)
         say(`  ! ${n}`);
-    say(endText({ tips: [demo ? `The demo database runs inside mason start, read by polling: a new order every few seconds; ${DEMO_TABLE_TO_ADD} is left for you to add; mason destroy removes it with the copy`
+    say(endText({ tips: [demo ? `The demo database runs inside mason start, read by polling: a new order every few seconds; ${DEMO_TABLE_TO_ADD} is left for you to add; mason destroy removes it with the synced data`
                 : "Mason only reads your database: no setting, slot or publication is needed or made"], next }, st));
     return 0;
 }

package/dist/src/cli/machine.js

@@ -18,16 +18,16 @@ import { dropOwnReplication, dropStatements, madeReplication } from "./replicati
 import { sourceFileNames } from "./sources.js";
 export const DESTROY_USAGE = `usage: mason destroy [--json]
 
-  Removes this folder's project's copy of your data from this machine — its file — and Mason's state in its
+  Removes this folder's project's synced data from this machine — its file — and Mason's state in its
   .mason/ (the logs, the request log). Mason is stopped first if it runs. Your files (mason/sources/), .mason/config.json and
-  the users (mason user) stay: the next mason start copies the tables again, and every tool connects as before.
+  the users (mason user) stay: the next mason start syncs the tables again, and every tool connects as before.
 
     mason destroy                this folder's project
 
-  mason stop keeps the copy and the state, and the next mason start resumes in seconds; mason destroy frees the disk, and
+  mason stop keeps the synced data and the state, and the next mason start resumes in seconds; mason destroy frees the disk, and
   the next mason start begins again. In replication mode the slot (and Mason's own publication) are dropped from the
   database too: they hold its WAL for as long as they exist. A demo project's database (mason init demo, in .mason/demo/)
-  goes with the copy: the next mason start makes and seeds it again.
+  goes with the synced data: the next mason start makes and seeds it again.
 
   --json   as data: { removed: [{ name, removed: [what], error }], next }
 
@@ -36,7 +36,7 @@ export const DESTROY_USAGE = `usage: mason destroy [--json]
 export const DESTROY = {
     needs: "project",
     name: "destroy",
-    summary: "remove this project's copy of the data and Mason's state from this machine (your files and users stay)",
+    summary: "remove this project's synced data and Mason's state from this machine (your files and users stay)",
     usage: DESTROY_USAGE,
     options: { json: { type: "boolean" } },
     json: ["removed", "next"],
@@ -71,11 +71,12 @@ export async function removeProject(p, o = {}) {
         if (sup !== null)
             removed.push(`stopped its supervisor (pid ${sup}), which was about to start it again`);
     }
-    // REPLICATION MODE made a publication and a slot on the database (src/cli/replication-mode.ts): the slot holds its WAL
-    // for as long as it exists, so it goes with the copy — and when it cannot, the rest goes and the failure says how
+    // REPLICATION made a publication and a slot on the database (src/cli/replication-mode.ts), recorded by the start or
+    // the run that made them (an older start recorded its mode, `changes`): the slot holds its WAL for as long as it
+    // exists, so it goes with the copy — and when it cannot, the rest goes and the failure says how
     let replication = null;
     let objects = "publication and replication slot";
-    if (p.config.changes === "replication") {
+    if ((p.config.replication ?? null) !== null || p.config.changes === "replication") {
         // the slot, and the publication only when it is Mason's own: one the operator named is its owner's, left as it is
         const src = projectSource(p);
         // what the start that made them recorded (madeReplication); a project with no record names them by its one sources file
@@ -90,7 +91,7 @@ export async function removeProject(p, o = {}) {
             // and the real slot goes on holding its WAL (the review of the sources file)
             const from = p.config.sourceServer ?? null;
             if (from !== null && from.database !== parsed.source.database) {
-                throw new Error(`the sources file names ${parsed.source.database} now, and the copy came from ${from.database}, where the slot is: ` +
+                throw new Error(`the sources file names ${parsed.source.database} now, and the synced data came from ${from.database}, where the slot is: ` +
                     `put that database's URL back in the sources file and run mason destroy again, or drop them on ${from.database} by hand`);
             }
             for (const d of await (o.dropReplication ?? dropOwnReplication)(parsed.source, own, from))
@@ -145,7 +146,7 @@ export async function destroy(argv, deps = {}) {
     catch (e) {
         result = { name, removed: [], error: e.message };
     }
-    const next = result.error ? [] : [["mason start", "copies the tables again"]];
+    const next = result.error ? [] : [["mason start", "syncs the tables again"]];
     if (json) {
         out(jsonText(DESTROY, { removed: [result] }, next));
         return result.error ? 1 : 0;
@@ -156,7 +157,7 @@ export async function destroy(argv, deps = {}) {
         headline: result.removed.length ? `Removed ${name}` : `Nothing was left of ${name} to remove`,
         details: [...(result.removed.length ? [["removed", result.removed.join(", ")]] : []), ["kept", `your files in ${t.project.folder}, .mason/config.json and the users` +
                     // the demo database is state like the copy (src/cli/demo.ts): it goes, and config.demo stays to make it again
-                    (t.project.config.demo === true ? ` — not the demo database, which went with the copy: the next mason start seeds it again` : "")]],
+                    (t.project.config.demo === true ? ` — not the demo database, which went with the synced data: the next mason start seeds it again` : "")]],
     }), { next }));
     return 0;
 }

package/dist/src/cli/main.js

@@ -38,11 +38,11 @@ async function main(argv) {
         dev: { message: "mason dev is now mason start", next: [["mason init <postgres url>", "once, in your app's folder"], ["mason start", "Mason in the background"]] },
         docs: { message: "mason docs is now mason help", next: [["mason help agent", "driving Mason from a coding agent"], ["mason help production", "running Mason on a server"]] },
         // named for what it does to the copy, never for the mechanism
-        poll: { message: "mason poll is now mason sync", next: [["mason sync <table>", "make the copy of a table current now"], ["mason status", "each table's copy, and which the sync leaves out"]] },
-        purge: { message: "mason purge is now mason destroy", next: [["mason destroy", "this folder's project: its copy and state, never its files"]] },
+        poll: { message: "mason poll is now mason sync", next: [["mason sync <table>", "bring a synced table up to date now"], ["mason status", "each synced table, and which the sync leaves out"]] },
+        purge: { message: "mason purge is now mason destroy", next: [["mason destroy", "this folder's project: its synced data and state, never its files"]] },
         // mason rm read as the opposite of mason add: it removed a project's copy and state, never a table;
         // the opposite of mason add is mason remove, so both are offered
-        rm: { message: "mason rm is gone: mason remove takes a table out of the project, mason destroy removes the project's copy", next: [["mason remove <table>", "a table, and its copy"], ["mason destroy", "this folder's project: its copy and state, never its files"]] },
+        rm: { message: "mason rm is gone: mason remove takes a table out of the project, mason destroy removes the project's synced data", next: [["mason remove <table>", "a table, and its synced data"], ["mason destroy", "this folder's project: its synced data and state, never its files"]] },
         // a user's password does not expire, so mason user is enough and mason connect was dropped
         connect: { message: "mason connect is gone: mason user add <name> makes a user whose password does not expire, and prints the URL to paste", next: [["mason user add <name>", "a user for a BI tool or your app"], ["mason status", "where the Postgres API listens"]] },
         // a project is its folder (mason list was dropped): nothing on the machine lists them

package/dist/src/cli/mcp.js

@@ -9,7 +9,7 @@
  * `--url`, else `MASON_URL`), so it works the same beside `mason start` and against a `mason serve` elsewhere, and every
  * statement is a row of the request log under `application_name` `mason-mcp/<client>`. Everything it reads comes over
  * that wire: the tables and columns from the catalog (a real Postgres), the rows and how current each copy is from
- * EXPLAIN (FORMAT JSON)'s `Mason.Copies` — the sync's own words, the same line `mason status` prints.
+ * EXPLAIN (FORMAT JSON)'s `Mason.Tables` — the sync's own words, the same line `mason status` prints.
  *
  * STDOUT IS THE PROTOCOL'S: newline-delimited JSON-RPC 2.0 frames and nothing else (`CommandSpec.stdout`: no --json,
  * every failure on stderr); what it says goes to stderr. A tool's failure is Mason's refusal (SQLSTATE, message,
@@ -29,15 +29,15 @@ import { PgConnection, PgError, pgIdent, pgLiteral, socketErrorText } from "../c
 import { qualifiedName } from "../duck/explain.js";
 import { didYouMean } from "../lib/did-you-mean.js";
 /** The URL a client is shown in the help: a user's, as mason user add prints it. */
-const EXAMPLE_URL = "postgres://claude:<password>@127.0.0.1:5433/shop";
+const EXAMPLE_URL = "postgres://claude:<password>@127.0.0.1:5433/mason";
 export const MCP = {
     name: "mcp",
-    summary: "an MCP server on stdio, for Claude Code, Claude Desktop and other agents: the copy's tables, queries, refusals",
+    summary: "an MCP server on stdio, for Claude Code, Claude Desktop and other agents: the synced tables, queries, refusals",
     usage: `usage: mason mcp [--url <postgres://user:password@host:port/database>]
 
   An MCP (Model Context Protocol) server on stdin and stdout, for Claude Code, Claude Desktop and any MCP client.
   Its tools say what an agent would otherwise guess: the tables Mason serves, each one's columns, rows and how
-  current its copy is, and each statement's answer with its Postgres types — or Mason's refusal, with what to write
+  current each is, and each statement's answer with its Postgres types — or Mason's refusal, with what to write
   instead. It connects to the Postgres API as a mason user, by the URL mason user add printed (MASON_URL, else
   --url), so it works beside mason start or against a mason serve elsewhere, and every statement it runs is in
   the request log under application_name mason-mcp/<the client's name>. It serves until the client closes stdin.
@@ -121,7 +121,7 @@ function connect(s, applicationName) {
         applicationName, connectTimeoutMs: 10_000, textForms: [] });
 }
 /** Why a connection failed, in the failure shape: nothing listening, a password refused, a database it does not serve. */
-function connectFailure(e, s) {
+export function connectFailure(e, s) {
     const where = `${s.host}:${s.port}`;
     if (e instanceof PgError) {
         const hint = e.fields.H;
@@ -131,7 +131,9 @@ function connectFailure(e, s) {
                 next: [["mason user list", "the users, beside the run"], ADD_STEP] };
         }
         return { message: `${where} refused the connection: ${e.fields.M ?? e.message}${e.code ? ` (${e.code})` : ""}`, code: "refused", why: hint ?? e.detail,
-            fix: "the URL mason user add printed: its database is the project's", next: [HELP_STEP] };
+            // a URL from before the name moved is the likely one: the hint is the listener's, and says the right name
+            fix: e.code === "3D000" ? "the last part of the URL is the database: change it to the one the hint names, or use the URL mason user add printed"
+                : "the URL mason user add printed", next: [HELP_STEP] };
     }
     const reason = e instanceof Error ? socketErrorText(e) : String(e);
     const said = /ECONNREFUSED/.test(reason) ? `nothing is listening on ${where}` : reason.replace(/^connecting to \S+: /, "");
@@ -224,8 +226,9 @@ export const TOOLS = [
     {
         name: "tables",
         title: "The tables Mason serves",
-        description: "The tables Mason serves, each a copy of a table of the application's Postgres database: about how many rows each holds, " +
-            "and how its copy is kept current (polled, streamed by logical replication, or not current, with when it last was). " +
+        description: "The tables Mason serves, each synced from a table of the application's Postgres database: about how many rows each holds, " +
+            "and how it is kept current and when it was last synced (sync: off — read again only when someone runs mason sync — or polled " +
+            "every so often, or streamed by logical replication). A table last synced days ago answers as of then: say so with the answer. " +
             "Start here: a statement can read only these, named as listed.",
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
         annotations: { readOnlyHint: true, openWorldHint: false },
@@ -233,7 +236,8 @@ export const TOOLS = [
     {
         name: "describe",
         title: "One table's columns",
-        description: "One table's columns with their Postgres types, its primary key and foreign keys, about how many rows it holds and how its copy is kept current.",
+        description: "One table's columns with their Postgres types, its primary key and foreign keys, about how many rows it holds, how it is kept current " +
+            "and when it was last synced.",
         inputSchema: { type: "object", properties: { table: { type: "string", description: "the table as tables lists it (public.orders), or a bare name in public (orders)" } },
             required: ["table"], additionalProperties: false },
         annotations: { readOnlyHint: true, openWorldHint: false },
@@ -254,8 +258,9 @@ export const TOOLS = [
     {
         name: "explain",
         title: "How Mason answers a statement",
-        description: "How Mason answers one statement, as its EXPLAIN prints it: each copy the statement reads with its rows and how current it is, " +
-            "the SQL Mason runs for it, and the plan. analyze: true runs the statement too and adds each step's rows and time.",
+        description: "How Mason answers one statement, as its EXPLAIN prints it: each synced table the statement reads with its rows and how current it is, " +
+            "the SQL Mason runs for it, and the plan. analyze: true runs the statement too and adds each step's rows and time. " +
+            "For a statement that reads a table your role filters: no plan and no row counts, and analyze is refused.",
         inputSchema: { type: "object", properties: {
                 sql: { type: "string", description: "one statement, in Postgres's SQL (without EXPLAIN)" },
                 analyze: { type: "boolean", default: false, description: "run it, and say each step's rows and time" },
@@ -269,13 +274,14 @@ export const RESOURCES = [
     { uri: "mason://help/agent", name: "agent", title: "Driving Mason from an agent", description: "mason help agent: the commands in order, their --json shapes, exit codes and failures", mimeType: "text/plain" },
     { uri: "mason://help/mcp", name: "mcp", title: "mason mcp", description: "mason help mcp: this server's tools, and how to add it to a client", mimeType: "text/plain" },
 ];
-const INSTRUCTIONS = "Mason serves read-only copies of tables of an application's Postgres database, for analytical SQL (scans and aggregates). " +
-    "Call tables first, describe a table before querying it, and write Postgres's SQL. Each table says how current its copy is. " +
+const INSTRUCTIONS = "Mason serves read-only tables synced from an application's Postgres database, for analytical SQL (scans and aggregates). " +
+    "Call tables first, describe a table before querying it, and write Postgres's SQL. Each table says how current it is. " +
     "When a statement is refused, its hint says what to write instead.";
 /** The relations Mason serves, as the catalog lists them (a catalog read: no row of the request log). */
 async function relations(pg) {
     const r = await pg.query(`SELECT n.nspname, c.relname, c.relkind FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
-    WHERE c.relkind IN ('r', 'p', 'v', 'm') AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg\\_%' ORDER BY 1, 2`);
+    WHERE c.relkind IN ('r', 'p', 'v', 'm') AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg\\_%'
+      AND (pg_catalog.has_table_privilege(c.oid, 'SELECT') OR pg_catalog.has_any_column_privilege(c.oid, 'SELECT')) ORDER BY 1, 2`);
     return r.rows.map(([schema, name, kind]) => ({ schema: schema, name: name, kind: kind === "v" || kind === "m" ? "view" : "table" }));
 }
 class McpServer {
@@ -494,7 +500,7 @@ class McpServer {
         return { tables: all.map((t) => t.kind === "view" ? { table: qualifiedName(t), kind: "view" } : { table: qualifiedName(t), kind: "table", ...copyFacts(copies.get(qualifiedName(t))) }) };
     }
     /**
-     * HOW EACH COPY IS KEPT CURRENT, and its rows: EXPLAIN (FORMAT JSON)'s `Mason.Copies`, the sync's own words (what
+     * HOW EACH COPY IS KEPT CURRENT, and its rows: EXPLAIN (FORMAT JSON)'s `Mason.Tables`, the sync's own words (what
      * `mason status` prints), read over the wire so a remote mason serve answers as a local run does. One EXPLAIN a table
      * (a union of them all failed whole for one table it could not plan, and left a refusal in the request log the agent
      * never sent), several at once on connections of this call's. In a run the catalog lists only the tables copied
@@ -523,7 +529,7 @@ class McpServer {
             catch (e) {
                 throw new BadAnswer(`EXPLAIN (FORMAT JSON) of ${key} is not JSON (${e.message}): ${text.slice(0, 200)}`);
             }
-            const copy = doc[0]?.Mason?.Copies?.find((c) => c.Table === key);
+            const copy = doc[0]?.Mason?.Tables?.find((c) => c.Table === key);
             if (copy !== undefined)
                 out.set(key, copy);
         };
@@ -556,7 +562,8 @@ class McpServer {
         const rel = `${pgLiteral(qualifiedName(found))}::regclass`;
         // pg_catalog.format_type, written out: these are the catalog's own OIDs (mason_wire_type names the wire's)
         const columns = await pg.query(`SELECT a.attname, pg_catalog.format_type(a.atttypid, a.atttypmod), a.attnotnull, pg_catalog.col_description(a.attrelid, a.attnum)
-      FROM pg_catalog.pg_attribute a WHERE a.attrelid = ${rel} AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`);
+      FROM pg_catalog.pg_attribute a WHERE a.attrelid = ${rel} AND a.attnum > 0 AND NOT a.attisdropped
+        AND pg_catalog.has_column_privilege(a.attrelid, a.attnum, 'SELECT') ORDER BY a.attnum`);
         const key = await pg.query(`SELECT a.attname FROM pg_catalog.pg_index i JOIN pg_catalog.pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY (i.indkey)
       WHERE i.indrelid = ${rel} AND i.indisprimary ORDER BY array_position(i.indkey::int2[], a.attnum)`);
         const foreign = await pg.query(`SELECT pg_catalog.pg_get_constraintdef(oid) FROM pg_catalog.pg_constraint WHERE conrelid = ${rel} AND contype = 'f' ORDER BY conname`);
@@ -666,13 +673,15 @@ class ToolAnswerError extends ToolError {
 }
 /** A JSON-RPC error answer. */
 function rpcError(id, code, message) { return { jsonrpc: "2.0", id, error: { code, message } }; }
-/** A copy's facts as the tools say them: about how many rows, how it is kept current, and what keeps it current now. */
+/** A copy's facts as the tools say them: about how many rows, how it is kept current, what keeps it current now, and —
+ *  polled or off — its sync and when it was last synced (a copy's age is never hidden: issue 33). */
 function copyFacts(c) {
     if (c === undefined)
-        return { rows_about: null, kept: "how it is kept current is unknown: Mason has no copy of it" };
+        return { rows_about: null, kept: "how it is kept current is unknown: Mason has not synced it" };
     if ("error" in c)
         return { rows_about: null, kept: `how it is kept current could not be read: ${c.error}` };
-    return { rows_about: c["Estimated Rows"], kept: c["Kept Current"], kept_current_by: c["Kept Current By"] };
+    return { rows_about: c["Estimated Rows"] ?? null, kept: c["Kept Current"], kept_current_by: c["Kept Current By"],
+        ...(c.Sync !== undefined ? { sync: c.Sync, last_synced: c["Last Synced"] ?? null } : {}) };
 }
 /** A refusal as the model reads it: Postgres's fields, as psql prints them, and the same as structured content.
  *  `shift`: the characters this server put before the statement (EXPLAIN's), taken off its position. */