@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/page-share.js

@@ -0,0 +1,96 @@
+import { newSharePassword, shareSecret } from "./share-run.js";
+import { probeShare, startTunnel, tunnelPlan } from "./tunnel.js";
+/** How often the page beats, and how long a share waits for a beat before it ends (the header says why each). */
+export const BEAT_MS = 15_000;
+export const BOUND_MS = 120_000;
+/** How long the tunnel has to give its address: `mason share`'s default. */
+const TIMEOUT_MS = 30_000;
+/** A tunnel's failure in the page's words: what to do there, never a flag of the command's. */
+function pageFailure(f, plan) {
+    if (f.code === "not_found") {
+        return { message: `${plan.bin} is not on this machine, and Connect from anywhere needs it`, code: "not_found", why: "the temporary address is a tunnel opened over ssh",
+            fix: `install ${plan.install}, then Connect from anywhere again`, next: [["mason doctor", "checks this machine"]] };
+    }
+    return { message: f.message, code: f.code, ...(f.why !== undefined ? { why: f.why } : {}),
+        fix: f.message.startsWith("the tunnel gave no address") ? "the tunnel's service answered in a way this Mason cannot read: nothing was left open; mason share, in a terminal, offers another tunnel"
+            : `${f.fix ?? "is this machine online? Port 443 outbound is all it needs"}; nothing was left open`,
+        next: [["mason logs", "the run's log"]] };
+}
+export class PageShares {
+    deps;
+    /** the page's share open now: its user, the tunnel once up, and the timer its beats reset */
+    current = null;
+    constructor(deps) { this.deps = deps; }
+    get bound() { return this.deps.boundMs ?? BOUND_MS; }
+    /** The roles the page offers before it asks (`RunShares.choices`). */
+    choices() { return this.deps.shares.choices(); }
+    /** Opens the page's share: the login, the tunnel, the probe; refused, the failure, and nothing left open. */
+    async open(o) {
+        const { shares } = this.deps;
+        const password = newSharePassword();
+        const opened = await shares.open({ secret: shareSecret(password), role: o.role, from: "page" });
+        if ("failure" in opened)
+            return opened;
+        const user = opened.user;
+        const mine = { user, tunnel: null, timer: this.lapse(user) };
+        this.current = mine;
+        // however it ends (Stop sharing, no beat, its tunnel, the run stopping), the tunnel's client goes with it
+        shares.onEnd(user, () => { clearTimeout(mine.timer); mine.tunnel?.stop(); if (this.current === mine)
+            this.current = null; });
+        const plan = tunnelPlan("pinggy", { port: opened.port, home: this.deps.home, token: null });
+        const t = await (this.deps.start ?? startTunnel)(plan, { timeoutMs: this.deps.timeoutMs ?? TIMEOUT_MS, onPid: (pid) => { shares.update(user, { pid, via: plan.via, state: "opening" }); } });
+        if ("message" in t) {
+            await shares.close(user, "its tunnel did not open");
+            return { failure: pageFailure(t, plan) };
+        }
+        if (this.current !== mine) {
+            t.stop();
+            return { failure: this.endedWhileOpening(user) };
+        }
+        mine.tunnel = t;
+        const probe = await (this.deps.probe ?? probeShare)(t, opened.fingerprint);
+        if (this.current !== mine) {
+            t.stop();
+            return { failure: this.endedWhileOpening(user) };
+        }
+        if (probe === "other") {
+            await shares.close(user, "its address answered with another certificate");
+            return { failure: { message: `${t.host}:${t.port} is not this share: something else answers there`, code: "failed", why: "the tunnel gave that address, and the certificate there is not this share's",
+                    fix: "nothing was left open. Do not connect a tool to that address", next: [["mason logs", "the run's log"]] } };
+        }
+        shares.update(user, { host: t.host, port: t.port, endsAt: t.endsAt, state: "up", pid: t.pid, via: plan.via });
+        void t.ended.then((why) => shares.close(user, `its tunnel closed (${why})`)).catch((e) => this.deps.log(`share: closing ${user} after its tunnel: ${e.message}`));
+        this.deps.log(`share: ${user} opened from the web page, at ${t.host}:${t.port}`);
+        return { user, host: t.host, port: t.port, database: opened.database, password, sslmode: "require", fingerprint: opened.fingerprint, role: opened.role, reads: opened.reads,
+            openedAt: new Date().toISOString(), endsAt: t.endsAt, verified: probe === "same", beatMs: BEAT_MS, boundMs: this.bound };
+    }
+    endedWhileOpening(user) {
+        const why = this.deps.shares.ended?.user === user ? this.deps.shares.ended.why : "it was stopped";
+        return { message: `the share ended while its tunnel opened: ${why}`, code: "failed", fix: "nothing was left open: Connect from anywhere again" };
+    }
+    /** The timer a beat resets: past the bound with no beat, the share ends. */
+    lapse(user) {
+        const t = setTimeout(() => {
+            void this.deps.shares.close(user, `the web page stopped checking in for ${Math.round(this.bound / 1000)} s (closed, asleep or gone)`)
+                .catch((e) => this.deps.log(`share: closing ${user}: ${e.message}`));
+        }, this.bound);
+        t.unref();
+        return t;
+    }
+    /** A beat from the page: true when `user` is the page's share and still open. */
+    beat(user) {
+        const c = this.current;
+        if (c === null || c.user !== user || this.deps.shares.fromOf(user) !== "page")
+            return false;
+        clearTimeout(c.timer);
+        c.timer = this.lapse(user);
+        return true;
+    }
+    /** Stop sharing: the page's share ended now. false: no such share of the page's is open. */
+    async stop(user) {
+        if (this.deps.shares.fromOf(user) !== "page")
+            return false;
+        await this.deps.shares.close(user, "Stop sharing, on the web page");
+        return true;
+    }
+}

package/dist/src/cli/pg-tls.js

@@ -31,7 +31,7 @@ export function runListenerSettings(shell, o) {
             fix: "drop --self-signed-tls to serve your certificate, or unset MASON_PG_TLS_CERT and MASON_PG_TLS_KEY to serve a self-signed one" };
     }
     const s = pgListenerSettings({
-        MASON_PG_HOST: shell.MASON_PG_HOST, MASON_PG_PORT: String(o.port), MASON_PG_PLAIN: shell.MASON_PG_PLAIN,
+        MASON_PG_HOST: shell.MASON_PG_HOST, MASON_PG_PORT: String(o.port), MASON_PG_PLAIN: shell.MASON_PG_PLAIN, MASON_PG_PROXY_FROM: shell.MASON_PG_PROXY_FROM,
         MASON_PG_TLS_CERT: o.selfSigned ? path.join(o.home, SELF_SIGNED_FILES.cert) : shell.MASON_PG_TLS_CERT,
         MASON_PG_TLS_KEY: o.selfSigned ? path.join(o.home, SELF_SIGNED_FILES.key) : shell.MASON_PG_TLS_KEY,
     }, "127.0.0.1");

package/dist/src/cli/pin.js

@@ -7,6 +7,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { parseVersion, pinFileText, projectPinProblem, PIN_FILE } from "../lib/project-version.js";
+import { projectWriteRefusal } from "./project.js";
 /** Why this mason command may not run the project in `folder`, or null (a checkout's `dev` checks nothing). */
 export function commandPinProblem(folder, cliVersion) {
     return projectPinProblem(folder, cliVersion, { what: "this mason command",
@@ -23,11 +24,14 @@ export function cliPinProblem(folder, cliVersion) {
 }
 /**
  * Write `folder`'s mason.yml with this command's version when it has none; the file written, or null when there was one
- * already (or this is a checkout's `dev`, which has no version to write).
+ * already (or this is a checkout's `dev`, which has no version to write), or when the project's files are read-only here
+ * (src/cli/project.ts `projectWriteRefusal`, asked of `root`, the project's: a deployed project's pin is the one committed).
  */
-export function ensurePin(folder, cliVersion) {
+export function ensurePin(folder, cliVersion, root, env = process.env) {
     if (parseVersion(cliVersion) === null)
         return null;
+    if (projectWriteRefusal(root, env) !== null)
+        return null;
     const file = path.join(folder, PIN_FILE);
     if (fs.existsSync(file))
         return null;

package/dist/src/cli/pool-size.cjs

@@ -0,0 +1,85 @@
+/**
+ * THE SIZE OF LIBUV'S POOL (issue 88). A statement in flight holds one of its threads for as long as DuckDB computes
+ * (docs/FLOWS.md "What waits, and where"), and at Node's four a fifth statement waits behind four heavy ones: 10 s to 50 s
+ * for a `SELECT 1`. libuv reads UV_THREADPOOL_SIZE once, when the first task reaches the pool, so this must run before
+ * anything uses it: CommonJS, loaded synchronously, by src/cli/mason.cjs and as main.ts's FIRST import. Nothing here may
+ * use the pool: every read is synchronous.
+ *
+ * WHY 32, MEASURED AND NOT DERIVED (docs/DESIGN.md "The pool"): Mason admits no fixed number of running statements. A
+ * session runs one at a time and CANCEL_SLOTS allows 4,096 sessions, past the 1,024 threads libuv allows, so no pool
+ * sits above that limit. The 1,024 itself is refused: libuv starts every thread at once and ABORTS the process with no
+ * message when one cannot be made (exit 133 under `--pids-limit=300`). 16 fixed five statements and 32 fixed eight; past
+ * eight there is no data, and the old queue was the only limit on how much memory statements take at once.
+ *
+ * A LIMIT ON THREADS IS READ FIRST, because that abort under a platform's restart is a silent loop. Below what Mason
+ * needs the size is lowered to fit and said; an operator's own size that does not fit refuses the start, as an invalid
+ * one does (`abc` would run 1 thread, `-1` 1,024). A size of 4 or less is never refused: it is Node's own, and what a
+ * run inherits from the `mason start` that lowered it.
+ *
+ * ON WINDOWS `process.env` never reaches libuv's getenv, so what this sets does nothing and the pool stays at 4:
+ * UV_THREADPOOL_SIZE must be set in the shell before `mason`.
+ */
+"use strict";
+const fs = require("node:fs");
+const os = require("node:os");
+
+const POOL_THREADS = 32;
+const LIBUV_MAX = 1024;
+/** Node's own size: never lowered past it */
+const FLOOR = 4;
+const CGROUP_LIMITS = ["/sys/fs/cgroup/pids.max", "/sys/fs/cgroup/pids/pids.max"];
+const PROCESS_LIMITS = "/proc/self/limits";
+
+/** A file's text; null when this machine has no such file, or it cannot be read: then it says no limit. */
+function read(file) {
+  try { return fs.readFileSync(file, "utf8"); }
+  catch { return null; }
+}
+
+/** The lowest numeric limit on threads the files say; null when none does (`max`, `unlimited`, not Linux). */
+function threadLimit(cgroupFiles, processLimits) {
+  const said = cgroupFiles.map((f) => /^\s*(\d+)\s*$/.exec(read(f) ?? "")?.[1]);
+  said.push(/^Max processes\s+(\d+)/m.exec(read(processLimits) ?? "")?.[1]);
+  const numbers = said.filter((n) => n !== undefined).map(Number);
+  return numbers.length === 0 ? null : Math.min(...numbers);
+}
+
+/**
+ * Sets UV_THREADPOOL_SIZE in `o.env` and returns the size, or refuses by `o.refuse`. Everything it reads is a parameter,
+ * for tests/cli-pool-size.test.ts. `o.announce`: say a lowered size (the commands that start a run; any other would
+ * repeat it on every call).
+ */
+function sizePool(o = {}) {
+  const env = o.env ?? process.env;
+  const platform = o.platform ?? process.platform;
+  const cpus = o.cpus ?? os.availableParallelism();
+  const say = o.say ?? ((line) => process.stderr.write(`${line}\n`));
+  const refuse = o.refuse ?? ((line) => { say(line); process.exit(1); });
+  const limit = platform !== "linux" ? null : threadLimit(o.cgroupFiles ?? CGROUP_LIMITS, o.processLimits ?? PROCESS_LIMITS);
+  /** the threads of a run with a pool of `size`: its other threads are about 20 plus five a CPU (read off real runs) */
+  const needs = (size) => size + 20 + 5 * cpus;
+  const fitting = limit === null ? POOL_THREADS : Math.min(POOL_THREADS, Math.max(FLOOR, limit - needs(0)));
+
+  const own = env.UV_THREADPOOL_SIZE;
+  if (own) {
+    if (!/^[1-9]\d*$/.test(own) || Number(own) > LIBUV_MAX) {
+      refuse(`UV_THREADPOOL_SIZE=${JSON.stringify(own)} is not a number of threads from 1 to ${LIBUV_MAX}: set one, or unset it for Mason's ${POOL_THREADS}`);
+      return null;
+    }
+    const size = Number(own);
+    if (limit !== null && size > FLOOR && limit < needs(size)) {
+      refuse(`UV_THREADPOOL_SIZE=${own} does not fit: this machine allows ${limit} threads, Mason would need about ${needs(size)}, and Node exits with no message past the limit: set UV_THREADPOOL_SIZE=${fitting}`);
+      return null;
+    }
+    return size;
+  }
+  if (fitting < POOL_THREADS && o.announce === true) {
+    say(`this machine allows ${limit} threads and Mason wants about ${needs(POOL_THREADS)}, so it uses a pool of ${fitting}: set UV_THREADPOOL_SIZE=${fitting} to choose it, or another that fits`);
+  }
+  env.UV_THREADPOOL_SIZE = String(fitting);
+  return fitting;
+}
+
+sizePool({ announce: ["start", "serve"].includes(process.argv[2] ?? "") });
+
+module.exports = { sizePool, POOL_THREADS };

package/dist/src/cli/ports.js

@@ -11,6 +11,8 @@
  */
 import * as net from "node:net";
 import { DEFAULT_PG_PORT, pgListenerAddress } from "../api/postgres/listener.js";
+/** The port the commands and the web page reach a run on, unless a flag or a setting says another. */
+export const DEFAULT_UI_PORT = 4039;
 export const PROBE_ADDRESSES = ["127.0.0.1", "0.0.0.0", "::", "::1"];
 /** The address that holds `port`, or null when every address binds. */
 export async function portHolder(port) {

package/dist/src/cli/preflight.js

@@ -10,49 +10,103 @@
  */
 import * as os from "node:os";
 import { PgConnection, PgError } from "../cdc/pg-wire.js";
-import { parseDatabaseUrl } from "../lib/database-url.js";
+import { parseDatabaseUrl, queryProblem } from "../lib/database-url.js";
 /** A host on this machine: polling it costs nothing that leaves the machine. */
 export function isLocalHost(host) {
     const h = host.toLowerCase();
     return h === "localhost" || h === "::1" || h === "0.0.0.0" || /^127\./.test(h) || h === "host.docker.internal" || h.endsWith(".localhost");
 }
-/** The URL with its password masked: what is printed and shown, never the secret. */
-export function maskedUrl(url) {
+/**
+ * THE ONE WAY A VALUE OF THE SOURCE'S URL SETTING IS SHOWN (issue 541), wherever Mason prints, logs or answers it: the URL
+ * with its password replaced by `****`, or null — never shown. It fails closed, so a secret masked by recognising its
+ * shape cannot leak in another shape: shown only when the value parses WHOLE as a postgres:// URL with a host, nothing
+ * dropped or rewritten by the parse (no space or control character inside it, which a parse strips or encodes; one at
+ * either end, a secret file's last newline, is trimmed as the parse trims it), no `#` at all and no `@` after the host
+ * (a password holding `/`, `?` or `#` unencoded splits the authority there, and its tail would be shown as a path, a
+ * parameter or a fragment), and a query the URL is read by whole (src/lib/database-url.ts queryProblem: only the
+ * parameters read, each once, each value one the reading accepts — libpq takes any connection keyword there,
+ * `?password=…` included, and a value can hold one, `sslmode=prefer%26password=…`), so no part shown is one not read;
+ * the query shown is the one read, written out again. A keyword/value string, a bare password, any other URL: null.
+ */
+export function shownUrl(value) {
+    const v = value.trim();
+    if (/[\s\x00-\x1f\x7f#]/.test(v))
+        return null;
+    let u;
     try {
-        const u = new URL(url);
-        if (u.password)
-            u.password = "****";
-        return u.toString();
+        u = new URL(v);
     }
     catch {
-        // not a URL: everything from the user's colon to the LAST @ is the password, whatever it holds (a / or an @ that
-        // was not encoded) — a host never holds an @
-        return url.replace(/:\/\/([^:@/]*):.*@/, "://$1:****@");
+        return null;
     }
+    if (u.protocol !== "postgres:" && u.protocol !== "postgresql:")
+        return null;
+    if (!u.hostname || /@/.test(u.pathname + u.search))
+        return null;
+    if (queryProblem(u.searchParams) !== null)
+        return null;
+    u.search = u.searchParams.toString();
+    if (u.password)
+        u.password = "****";
+    return u.toString();
 }
-/**
- * Parse the URL `mason start` was given. The user defaults to the OS user (libpq's default, and Homebrew's and
- * Postgres.app's superuser); the database never defaults — guessing it would read the wrong one.
- */
-export function parseSource(url) {
+/** A value of the source's URL setting in a sentence: `shownUrl`'s, or words that say it is not shown, never the value. */
+export function maskedUrl(value) {
+    return shownUrl(value) ?? "a value that is not a postgres:// URL (not shown)";
+}
+const URL_FORM = "postgres://user:password@host:5432/your_app";
+/** The schemes a wrong URL is named by: Mason's own list, so a scheme said is never a part of the value Mason did not know. */
+const KNOWN_SCHEMES = new Set(["mysql", "mariadb", "mssql", "sqlserver", "oracle", "mongodb", "mongodb+srv", "redis", "rediss", "sqlite", "clickhouse",
+    "http", "https", "file", "pg", "pgsql", "psql", "postgis", "postgre", "postgress", "postgresq"]);
+const ENCODE = "a password holding @ : / # ? % or a space is URL-encoded (encodeURIComponent; @ is %40, / is %2F, # is %23)";
+/** What is wrong with the query of a postgres:// URL that reads whole but for it (queryProblem's words), else null. */
+function queryOf(t) {
+    if (!/^postgres(ql)?:\/\//i.test(t) || /[\s\x00-\x1f\x7f#]/.test(t))
+        return null;
     let u;
     try {
-        u = new URL(url);
+        u = new URL(t);
     }
     catch {
-        // its password masked: the problem is printed (and, under mason mcp, kept in the MCP client's log)
-        return { problem: `${JSON.stringify(maskedUrl(url))} is not a URL. The form is postgres://user:password@localhost:5432/your_app — a password ` +
-                `containing @ : / # ? or % must be URL-encoded (encodeURIComponent; @ is %40).` };
+        return null;
     }
-    if (u.protocol !== "postgres:" && u.protocol !== "postgresql:")
-        return { problem: `the URL's scheme is ${u.protocol.replace(/:$/, "")}; it must be postgres:// or postgresql://` };
+    // an @ after the host is a password split there (said as such), not a parameter
+    return u.hostname === "" || /@/.test(u.pathname + u.search) ? null : queryProblem(u.searchParams);
+}
+/**
+ * Why a value `shownUrl` will not show is not a URL Mason reads, told from its SHAPE alone (`name` says where it is):
+ * what it looks like and how to write it, never a part of it, so a coding agent fixes it from the message alone.
+ */
+function notShownProblem(value, name) {
+    const t = value.trim();
+    const why = t === "" ? "it is empty"
+        : /^[A-Za-z_][A-Za-z0-9_]*\s*=/.test(t) ? "it looks like a keyword/value connection string (host=… user=… password=…)"
+            : /^jdbc:/i.test(t) ? "it looks like a JDBC URL: drop jdbc:, and give the user and password before the host"
+                : !/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(t) ? "it is not a URL"
+                    : queryOf(t) !== null ? queryOf(t)
+                        : !/^postgres(ql)?:\/\//i.test(t) ? `its scheme is ${KNOWN_SCHEMES.has(t.slice(0, t.indexOf(":")).toLowerCase()) ? `${t.slice(0, t.indexOf(":")).toLowerCase()}, not` : "not"} postgres:// or postgresql://`
+                            : "it does not read as one URL (a character that is not URL-encoded splits it: an @ : / ? # % or a space in the password, an @ or # in the database " +
+                                "or a parameter; or the port is not a number up to 65535)";
+    return `${name} is not a postgres:// URL: ${why}. Write it as ${URL_FORM}, where ${ENCODE}`;
+}
+/**
+ * Parse the URL `mason start` was given (`name` says where it is, `DATABASE_URL in .env`: a problem names it, never the
+ * value). The user defaults to the OS user (libpq's default, and Homebrew's and Postgres.app's superuser); the database
+ * never defaults — guessing it would read the wrong one. Only a value `shownUrl` shows is read, so every URL a run
+ * connects with is one its messages can show.
+ */
+export function parseSource(url, name = "the URL") {
+    if (shownUrl(url) === null)
+        return { problem: notShownProblem(url, name) };
+    const u = new URL(url.trim());
     if (!u.username)
         u.username = encodeURIComponent(os.userInfo().username);
-    if (!u.pathname.replace(/^\//, "")) {
-        return { problem: `the URL names no database. Add it after the port: postgres://${decodeURIComponent(u.username)}@${u.host || "localhost:5432"}/your_app ` +
-                `(the one your app uses — its DATABASE_URL usually says).` };
-    }
     try {
+        // inside the try: a user name with a malformed %-escape is refused (decodeURIComponent throws), never a crash
+        if (!u.pathname.replace(/^\//, "")) {
+            return { problem: `${name} names no database. Add it after the port: postgres://${decodeURIComponent(u.username)}@${u.host || "localhost:5432"}/your_app ` +
+                    `(the one your app uses — its DATABASE_URL usually says).` };
+        }
         const parts = parseDatabaseUrl(u.toString());
         const remote = !isLocalHost(parts.host);
         // a database elsewhere is read over the network: never in the clear unless the URL says so outright
@@ -61,7 +115,9 @@ export function parseSource(url) {
         return { source: { ...parts, url: u.toString(), remote } };
     }
     catch (e) {
-        return { problem: e.message.replace(/^DATABASE_URL/, "the URL") };
+        if (e instanceof URIError)
+            return { problem: `${name} holds a % that starts no %-escape: a % in the user or the password is written %25. Write it as ${URL_FORM}, where ${ENCODE}` };
+        return { problem: e.message.replace(/^DATABASE_URL/, name) };
     }
 }
 /** What a failed connection means, and what to change. */
@@ -80,8 +136,9 @@ export function explainConnectError(e, s, o = {}) {
                 ],
             };
         }
+        // the database is not repeated (issue 541: a refusal echoes no part of the value); the hint lists the ones there are
         if (e.code === "3D000")
-            return { message: `${where} has no database ${JSON.stringify(s.database)}`, hints: [] };
+            return { message: `${where} has no database by the name the URL gives (the part after the port)`, hints: [] };
         return { message: `${where}: ${msg}`, hints: [] };
     }
     if (/ECONNREFUSED/.test(msg)) {
@@ -138,6 +195,18 @@ export async function connectSource(s, o = {}) {
         return { failure };
     }
 }
+/** pg_collation_actual_version (a libc collation's glibc now) exists from this server_version_num */
+const COLLATION_ACTUAL_NUM = 130000;
+/** The database's collations of its encoding, each as src/duck/collation.ts reads it. The locale's column differs by
+ *  version (colllocale from 17, colliculocale 15–16, none before: collcollate holds ICU's), so the row is read whole. */
+export async function readCollations(pg, versionNum) {
+    const version = versionNum >= COLLATION_ACTUAL_NUM ? "CASE WHEN c.collprovider = 'c' THEN pg_collation_actual_version(c.oid) END" : "NULL::text";
+    const rows = JSON.parse((await pg.query(`SELECT coalesce(json_agg(to_jsonb(c) || jsonb_build_object('schema', n.nspname, 'actual', ${version}) ORDER BY c.oid), '[]')::text ` +
+        "FROM pg_collation c JOIN pg_namespace n ON n.oid = c.collnamespace WHERE c.collencoding IN (-1, pg_char_to_encoding(getdatabaseencoding()))")).rows[0]?.[0] ?? "[]");
+    return rows.map((r) => ({ schema: String(r.schema), name: String(r.collname), provider: String(r.collprovider ?? "c"), collate: (r.collcollate ?? null), ctype: (r.collctype ?? null),
+        locale: (r.colllocale ?? r.colliculocale ?? (r.collprovider === "i" ? r.collcollate : null) ?? null), deterministic: r.collisdeterministic !== false,
+        version: (r.actual ?? r.collversion ?? null) }));
+}
 /** The source's plain views (never a materialized one: that is a table of its own), each definition printed under a
  *  search_path of pg_catalog alone, which qualifies every table, type and function a view reads (`public.orders`):
  *  `SET LOCAL` holds for the rest of this one Query and ends with it, whatever happens */
@@ -177,13 +246,21 @@ export const TABLES_SQL = `SELECT json_agg(t ORDER BY t.schema, t.table)::text F
       -- nothing: never declared to the catalog, never a key: Mason accepts
       WHERE i.indrelid = c.oid AND i.indisunique AND i.indisvalid AND NOT i.indisprimary AND i.indpred IS NULL AND i.indexprs IS NULL
         AND i.indnkeyatts = i.indnatts) AS unique_keys,
-    (SELECT coalesce(json_agg(json_build_object('name', a.attname, 'type', format_type(a.atttypid, a.atttypmod),
-        'not_null', a.attnotnull, 'comment', col_description(c.oid, a.attnum), 'type_oid', a.atttypid,
-        'type_array_oid', (SELECT typarray FROM pg_type WHERE oid = a.atttypid),
+    (SELECT coalesce(json_agg(json_build_object('name', a.attname, 'type', format_type(b.oid, b.mod), 'domain', b.oid <> a.atttypid,
+        'not_null', a.attnotnull, 'comment', col_description(c.oid, a.attnum), 'type_oid', b.oid,
+        'type_array_oid', (SELECT typarray FROM pg_type WHERE oid = b.oid),
+        'type_kind', (SELECT coalesce(e.typtype, t.typtype) FROM pg_type t LEFT JOIN pg_type e ON e.typarray = t.oid WHERE t.oid = b.oid),
         'default', pg_get_expr(d.adbin, d.adrelid), 'identity', a.attidentity, 'generated', a.attgenerated,
+        -- the column's own collation, where it is not its (base) type's: the catalog declares it (src/duck/collation.ts)
+        'collation', (SELECT json_build_object('schema', cn.nspname, 'name', co.collname) FROM pg_collation co JOIN pg_namespace cn ON cn.oid = co.collnamespace
+          WHERE co.oid = a.attcollation AND a.attcollation <> 0 AND a.attcollation <> (SELECT typcollation FROM pg_type WHERE oid = b.oid)),
         -- the sequence a serial or identity column owns: asked only of a column with a default or an identity
         'sequence', CASE WHEN d.adbin IS NOT NULL OR a.attidentity <> '' THEN pg_get_serial_sequence(format('%I.%I', n.nspname, c.relname), a.attname) END) ORDER BY a.attnum), '[]'::json)
       FROM pg_attribute a LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+      -- a domain's column is read and declared as its base type (a domain of a domain too)
+      CROSS JOIN LATERAL (WITH RECURSIVE base(oid, mod) AS (SELECT a.atttypid, a.atttypmod UNION ALL
+          SELECT t.typbasetype, t.typtypmod FROM base JOIN pg_type t ON t.oid = base.oid WHERE t.typtype = 'd')
+        SELECT base.oid, base.mod FROM base JOIN pg_type t ON t.oid = base.oid WHERE t.typtype <> 'd') b
       WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped) AS columns,
     (SELECT coalesce(json_agg(json_build_object('column', a.attname, 'target', tn.nspname || '.' || tc.relname, 'target_column', ta.attname)), '[]'::json)
       FROM pg_constraint f
@@ -199,8 +276,18 @@ export const TABLES_SQL = `SELECT json_agg(t ORDER BY t.schema, t.table)::text F
 /** What a never-analysed table counted to, by oid: `mason start` reads the catalog every 10 s, and a table is counted
  *  once per run, never per read (review of #404: a remote one over the network each time). */
 const COUNTED = new Map();
+/** the server_version_num from which `pg_database_collation_actual_version` exists */
+const COLLATION_ACTUAL_VERSION_NUM = 150000;
+const COLLATION_ACTUAL_VERSION_SQL = "SELECT pg_database_collation_actual_version(oid) FROM pg_database WHERE datname = current_database()";
+/** The collation library's version now, else what the database recorded (`recorded`, datcollversion; before Postgres 15, none). */
+export async function collationVersion(pg, versionNum, recorded) {
+    if (versionNum < COLLATION_ACTUAL_VERSION_NUM)
+        return recorded;
+    return (await pg.query(COLLATION_ACTUAL_VERSION_SQL)).rows[0]?.[0] ?? recorded;
+}
 /** The database's facts: its version, whether it is a standby, and every table this user can read. */
-export async function readSourceFacts(pg, counted = COUNTED) {
+/** `collations: false` (the run's 10-second refresh) leaves the database's collations unread: they were read at the start */
+export async function readSourceFacts(pg, counted = COUNTED, o = {}) {
     const r = (await pg.query("SELECT current_setting('server_version_num'), current_setting('server_version'), pg_is_in_recovery()::text")).rows[0];
     const rows = JSON.parse((await pg.query(TABLES_SQL)).rows[0]?.[0] ?? "null");
     const tables = [];
@@ -213,24 +300,28 @@ export async function readSourceFacts(pg, counted = COUNTED) {
         }
         tables.push({
             source: `${t.schema}.${t.table}`, schema: t.schema, table: t.table, key: t.key, rows: count, bytes: Number(t.bytes), comment: t.comment,
-            columns: t.columns.map((c) => ({ name: c.name, type: c.type, notNull: c.not_null, comment: c.comment,
-                ...(c.type_oid >= 16384 ? { typeOid: c.type_oid, ...(c.type_array_oid > 0 ? { typeArrayOid: c.type_array_oid } : {}) } : {}),
+            columns: t.columns.map((c) => ({ name: c.name, type: c.type, typeKind: c.type_kind, ...(c.domain ? { domain: true } : {}), notNull: c.not_null, comment: c.comment,
+                // an oid is a STRING in Postgres's JSON (only the int, float and numeric types are numbers): one spelling, here
+                ...(Number(c.type_oid) >= 16384 ? { typeOid: Number(c.type_oid), ...(Number(c.type_array_oid) > 0 ? { typeArrayOid: Number(c.type_array_oid) } : {}) } : {}),
                 // a generated column's pg_attrdef row is its expression, never a default
                 ...(c.default !== null && c.generated === "" ? { default: c.default } : {}), ...(c.identity === "a" || c.identity === "d" ? { identity: c.identity } : {}),
-                ...(c.generated === "s" ? { generated: true } : {}), ...(c.sequence !== null ? { sequence: c.sequence } : {}) })),
+                ...(c.generated === "s" ? { generated: true } : {}), ...(c.sequence !== null ? { sequence: c.sequence } : {}),
+                ...(c.collation !== null && c.collation !== undefined ? { collation: c.collation } : {}) })),
             foreignKeys: t.foreign_keys.map((f) => ({ column: f.column, target: f.target, targetColumn: f.target_column })),
             uniqueKeys: t.unique_keys.map((u) => ({ name: u.name, columns: u.columns, constraint: u.constraint, nullsNotDistinct: u.nulls_not_distinct })),
-            ...(t.row_type_oid > 0 ? { rowTypeOid: t.row_type_oid } : {}),
+            ...(Number(t.row_type_oid) > 0 ? { rowTypeOid: Number(t.row_type_oid) } : {}),
             ...(t.replica_identity === "d" || t.replica_identity === "n" || t.replica_identity === "f" || t.replica_identity === "i" ? { replicaIdentity: t.replica_identity } : {}),
         });
     }
     // the columns differ by version (datlocprovider from 15, daticulocale 15–16, datlocale from 17): read the row whole
     const db = JSON.parse((await pg.query("SELECT to_jsonb(d)::text FROM pg_database d WHERE datname = current_database()")).rows[0]?.[0] ?? "{}");
-    // datcollversion (Postgres 15+): the library's version of it (glibc's for libc), which moves when the OS's does
-    const collation = { provider: db.datlocprovider ?? "c", collate: db.datcollate ?? "C", locale: db.datlocale ?? db.daticulocale ?? null, version: db.datcollversion ?? null };
+    // the library's version of it NOW (Postgres 15+; glibc's for libc): datcollversion is what the database was created or
+    // last refreshed under, so it stays where it was through an OS upgrade, which is what must read the order again
+    const collation = { provider: db.datlocprovider ?? "c", collate: db.datcollate ?? "C", ctype: db.datctype ?? db.datcollate ?? "C", locale: db.datlocale ?? db.daticulocale ?? null, version: await collationVersion(pg, Number(r[0]), db.datcollversion ?? null) };
     const views = JSON.parse((await pg.query(VIEWS_SQL)).rows[0]?.[0] ?? "[]")
         .map((v) => ({ schema: v.schema, name: v.name, definition: v.definition, comment: v.comment }));
-    return { version: Number(r[0]), versionText: r[1] ?? "", standby: r[2] === "true", tables, systemIdentifier: await systemIdentifier(pg), collation, views };
+    const collations = o.collations === false ? undefined : await readCollations(pg, Number(r[0]));
+    return { version: Number(r[0]), versionText: r[1] ?? "", standby: r[2] === "true", tables, systemIdentifier: await systemIdentifier(pg), collation, ...(collations !== undefined ? { collations } : {}), views };
 }
 /** The server's system identifier, or null when this user may not read it (only that refusal: any other error is real). */
 export async function systemIdentifier(pg) {
@@ -310,7 +401,7 @@ export function versionProblem(f) {
  * after the check's facts.
  */
 export async function checkSource(url, o) {
-    const parsed = parseSource(url);
+    const parsed = parseSource(url, o.name);
     if ("problem" in parsed) {
         o.say(`${o.cmd}: ${parsed.problem}`);
         return { exit: 2 };

package/dist/src/cli/project.js

@@ -76,6 +76,53 @@ export function readProject(root) {
     }
     return { root, dir, folder: path.resolve(root, config.folder), config };
 }
+/** Why a path could not be resolved, in a person's words (the system's code beside them). */
+export function unresolvedWhy(e) {
+    const code = e.code;
+    const words = {
+        ELOOP: "a symbolic link on the way leads back to itself (a loop)",
+        ENOTDIR: "a part of the path is a file, not a folder",
+        EACCES: "a folder on the way may not be read by this user",
+        EPERM: "a folder on the way may not be read by this user",
+        ENAMETOOLONG: "the path is longer than this system takes",
+    };
+    return code !== undefined && words[code] !== undefined ? `${words[code]} (${code})` : `the system could not resolve it (${code ?? e.message})`;
+}
+/**
+ * WHERE A PROJECT'S FILES ARE, against its root (the folder `.mason/` is in): strictly `inside` it (a folder of their own,
+ * `mason/`), the `root` itself (`mason init --folder .`), or `outside` it (`..`, `../app`, an absolute path elsewhere, a
+ * link that leaves it). Read from the real paths — a folder not made yet by its nearest folder that is — so every
+ * spelling of one place is one answer. A path that cannot be resolved (a loop, a file as a folder, a folder this user
+ * may not read, a path too long) is a fourth answer, `unknown` with why, never an exception: fail closed, each caller
+ * refuses it with the way out. The one authority: `mason init` refuses outside and unknown, `mason deploy` sends only
+ * from inside (src/cli/deploy.ts: a root's or an outside folder's YAML is the application's, or anyone's).
+ */
+export function folderPlace(root, folder) {
+    const real = (p) => {
+        const rest = [];
+        for (let d = path.resolve(p);; d = path.dirname(d)) {
+            try {
+                return path.join(fs.realpathSync(d), ...rest.reverse());
+            }
+            catch (e) {
+                // a part not made yet: the nearest one that is decides (a folder mason init will make); anything else is unknown
+                if (e.code !== "ENOENT" || path.dirname(d) === d)
+                    throw e;
+                rest.push(path.basename(d));
+            }
+        }
+    };
+    let rel;
+    try {
+        rel = path.relative(real(root), real(folder));
+    }
+    catch (e) {
+        return { place: "unknown", why: unresolvedWhy(e) };
+    }
+    if (rel === "")
+        return { place: "root" };
+    return { place: rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel) ? "outside" : "inside" };
+}
 /** Whether a lookup found a project it could read. */
 export const isProject = (p) => p !== null && !("broken" in p);
 /** What a broken project's commands say: the file, what is wrong with it, and the two ways out. */
@@ -115,7 +162,7 @@ export function theProject(cwd) {
     if (p)
         return { project: p };
     return { problem: "no Mason project here or above", code: "no_project", fix: "cd into a project's folder, or make this folder one (mason init demo: a demo database, nothing to install)",
-        next: [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"]] };
+        next: [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or its URL on stdin: mason init -)"]] };
 }
 /** Whether `root`'s .gitignore already ignores `.mason/`. */
 export function ignoresStateDir(gitignore) {
@@ -150,12 +197,64 @@ export function databaseMoved(p, answersAs) {
     const says = connectDatabase(written, {}, {});
     return says === answersAs ? null : says;
 }
+/** The setting that says the project's files are deployed, and read-only where Mason runs (`projectWriteRefusal`). */
+export const READONLY_SETTING = "MASON_PROJECT_READONLY";
+/** MASON_PROJECT_READONLY as the environment says it: 1 true, 0 or unset false, anything else what is wrong with it. */
+export function projectReadOnlySetting(env) {
+    const v = env[READONLY_SETTING];
+    if (v === undefined || v === "" || v === "0")
+        return false;
+    if (v === "1")
+        return true;
+    return { problem: `${READONLY_SETTING}=${JSON.stringify(v)}: 1 (the project's files are deployed, and read-only here) or 0 (the default)` };
+}
+/** what a refused edit of a deployed project says to run next */
+const READONLY_NEXT = [["mason status", "what Mason syncs here, as the deployed files say"]];
+/**
+ * WHETHER THE PROJECT'S FILES MAY BE WRITTEN HERE — THE ONE AUTHORITY (issue 473): null when they may, else the refusal.
+ * A deployment that ships its committed project folder (CI, GitOps, a platform that deploys the folder) runs the files
+ * as committed: an edit on the server would run what nobody committed, and the next deploy would undo it without a word.
+ * MASON_PROJECT_READONLY=1 says so, and EVERY WRITER OF A PROJECT FILE ASKS THIS FIRST and writes nothing on a refusal:
+ * the sources file (`mason add` and `mason remove` at both entrances, the page's Add and Remove: src/cli/source-edit.ts
+ * `sourceToEdit`; `mason serve`'s first file, `serveSource`), `mason.yml` (src/cli/pin.ts `ensurePin`) and what `mason
+ * init` writes (the sources, roles and generated tables' files, `.env`, `.gitignore`). The users (`.mason/users.json`),
+ * the sync and every read are not the project's files, and are unchanged.
+ *
+ * Read from two places, either refusing: this process's environment, and THE RECORD the run makes in the project's
+ * config at its start (`projectReadOnly`, src/cli/dev.ts) — so a command beside the run (`docker compose exec mason
+ * mason add …`), with the run up or down, is refused whatever its own environment says (`MASON_PROJECT_READONLY=0
+ * mason add` does not un-say the run's). `root` is the project's (where `.mason/` is), or null where no record is to be
+ * read (`mason serve` before it writes the config: its own environment decides). Fail closed: a value that is not 0 or
+ * 1, or a config that cannot be read, cannot tell, and refuses.
+ */
+export function projectWriteRefusal(root, env) {
+    const set = projectReadOnlySetting(env);
+    if (typeof set !== "boolean") {
+        return { message: `${set.problem}, so whether the project's files may be written here cannot be told`, code: "refused",
+            why: "Mason writes none of them until it can tell", fix: `set ${READONLY_SETTING}=1 or ${READONLY_SETTING}=0, or unset it`, next: READONLY_NEXT };
+    }
+    const p = root === null ? null : readProject(root);
+    if (p !== null && "broken" in p) {
+        return { message: `whether the project's files may be written here cannot be told: ${p.file}: ${p.broken}`, code: "refused",
+            why: "the config records whether Mason runs the project read-only, and Mason writes none of its files until it can tell", fix: brokenProblem(p).fix, next: READONLY_NEXT };
+    }
+    const recorded = p?.config.projectReadOnly === true;
+    if (!set && !recorded)
+        return null;
+    return { message: `the project's files are read-only here (${READONLY_SETTING}=1${set ? "" : " when Mason last started"})`, code: "refused",
+        why: "Mason runs them as they were deployed: an edit here would run what nobody committed, and the next deploy would undo it",
+        fix: "edit the files and deploy them: mason add or mason remove where the project is committed, then commit and deploy",
+        next: READONLY_NEXT };
+}
 /**
  * A SETTING A START REFUSES, for the start that is typed and the run it spawns alike: read by the parent where the person
  * (or --json) reads the answer, and by the run, which `mason start --attach` and `mason serve` reach without the parent.
  * One list, because a check in the run alone reaches a background start as "the run stopped", its way out in a log.
  */
 export function startSettingRefusal(p, env, o) {
+    const readOnly = projectReadOnlySetting(env);
+    if (typeof readOnly !== "boolean")
+        return { message: readOnly.problem, code: "refused", fix: `set ${READONLY_SETTING}=1 or ${READONLY_SETTING}=0, or unset it` };
     const top = () => sourcesTop(p.root, p.folder);
     const pollMs = pollMsRetired(env, top);
     if (pollMs !== null)