cortad 0.3.1-rc.9 → 0.3.2

package/lib/mint.mjs

@@ -100,57 +100,169 @@ async function firebaseIdToken(account, apiKey) {
   return res.ok && out?.idToken ? { idToken: out.idToken } : { error: String(out?.error?.message ?? `status ${res.status}`).slice(0, 120) };
 }
 
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+// A server key goes only over TLS, or to a service on this machine (a local Supabase).
+function serviceOrigin(value) {
+  try { const u = new URL(value); return u.protocol === "https:" || (u.protocol === "http:" && LOOPBACK.has(u.hostname)) ? u.origin : null; } catch { return null; }
+}
+async function send(url, { method = "POST", headers = {}, body } = {}) {
+  const res = await fetch(url, { method, headers: { "content-type": "application/json", ...headers }, ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(20_000) });
+  return { ok: res.ok, status: res.status, json: await res.json().catch(() => null) };
+}
+const saidBy = (r) => String(r.json?.errors?.[0]?.long_message ?? r.json?.msg ?? r.json?.error_description ?? r.json?.message ?? `status ${r.status}`).slice(0, 120);
+const refusedBy = (who, r) => ({ status: "refused", note: `${who} refused the test account: ${saidBy(r)}` });
+// An account the service already held may have been given a role since this machine made it.
+const ELEVATED_ACCOUNT = { status: "refused", note: "the test account carries an admin role; only an ordinary account is signed in" };
+const elevated = (...claims) => claims.some((c) => c && ELEVATED.test(JSON.stringify(c)));
+
+// Clerk's Backend API, in their development instance only: the account, a session for it, and the
+// session's token, which lives a minute and is minted again from the same session before it lapses.
+export async function clerkToken(env, account, session) {
+  const key = env.CLERK_SECRET_KEY;
+  if (!key) return { status: "absent", note: "no CLERK_SECRET_KEY in your environment" };
+  if (!key.startsWith("sk_test_")) return { status: "refused", note: "your CLERK_SECRET_KEY is a production key; test accounts are made only in a development instance" };
+  const origin = serviceOrigin(env.CLERK_API_URL || "https://api.clerk.com");
+  if (!origin) return { status: "refused", note: "CLERK_API_URL is not an https address" };
+  const api = `${origin}/v1`;
+  const auth = { authorization: `Bearer ${key}` };
+  const tokenOf = async (id) => (await send(`${api}/sessions/${encodeURIComponent(id)}/tokens`, { headers: auth })).json?.jwt;
+  const again = session && await tokenOf(session);
+  if (again) return { token: again, session };
+  // Clerk sends nothing to a +clerk_test address; it exists for exactly this.
+  const email = `${account.username}+clerk_test@example.com`;
+  const found = await send(`${api}/users?email_address=${encodeURIComponent(email)}`, { method: "GET", headers: auth });
+  let user = Array.isArray(found.json) ? found.json[0] : null;
+  if (!user) {
+    // No password: a session is made through this API, and an instance that signs in only by email
+    // code or OAuth refuses a user created with one.
+    const made = await send(`${api}/users`, { headers: auth, body: { email_address: [email], skip_password_requirement: true } });
+    if (!made.ok || !made.json?.id) return refusedBy("your Clerk instance", made);
+    user = made.json;
+  }
+  if (elevated(user.public_metadata, user.private_metadata)) return ELEVATED_ACCOUNT;
+  const opened = await send(`${api}/sessions`, { headers: auth, body: { user_id: user.id } });
+  if (!opened.ok || !opened.json?.id) return refusedBy("your Clerk instance", opened);
+  const token = await tokenOf(opened.json.id);
+  return token ? { token, session: opened.json.id } : { status: "refused", note: "your Clerk instance issued no session token" };
+}
+
+const SUPABASE_URL = /^(?:NEXT_PUBLIC_|VITE_|EXPO_PUBLIC_|PUBLIC_)?SUPABASE_URL$/;
+const SUPABASE_SERVICE = /^SUPABASE_(?:SERVICE_ROLE|SERVICE|SECRET)_KEY$/;
+const SUPABASE_PUBLIC = /^(?:NEXT_PUBLIC_|VITE_|EXPO_PUBLIC_|PUBLIC_)?SUPABASE_(?:ANON|PUBLISHABLE)(?:_DEFAULT)?_KEY$/;
+const named = (env, pattern) => Object.entries(env).find(([name, value]) => pattern.test(name) && value)?.[1] ?? null;
+
+// Supabase Auth's admin API makes the account already confirmed, with the service key their server
+// holds; a password sign-in then issues the session their own client would hold.
+export async function supabaseSession(env, account) {
+  const url = named(env, SUPABASE_URL);
+  const service = named(env, SUPABASE_SERVICE);
+  if (!url || !service) return { status: "absent", note: `no ${url ? "SUPABASE_SERVICE_ROLE_KEY" : "SUPABASE_URL"} in your environment` };
+  const origin = serviceOrigin(url);
+  if (!origin) return { status: "refused", note: "SUPABASE_URL is not an https address" };
+  const made = await send(`${origin}/auth/v1/admin/users`, { headers: { apikey: service, authorization: `Bearer ${service}` }, body: { email: account.email, password: account.password, email_confirm: true } });
+  if (!made.ok && !/already|exists|registered/i.test(saidBy(made))) return refusedBy("your Supabase project", made);
+  const got = await send(`${origin}/auth/v1/token?grant_type=password`, { headers: { apikey: named(env, SUPABASE_PUBLIC) ?? service }, body: { email: account.email, password: account.password } });
+  if (!got.ok || typeof got.json?.access_token !== "string") return refusedBy("your Supabase project", got);
+  if (elevated(got.json.user?.app_metadata, got.json.user?.role)) return ELEVATED_ACCOUNT;
+  return { session: got.json, origin };
+}
+
+// @supabase/ssr's own cookie: the session as base64url JSON under sb-<ref>-auth-token, cut into
+// numbered chunks past 3180 characters the way the library cuts it.
+export function supabaseCookie(origin, session) {
+  const name = `sb-${new URL(origin).hostname.split(".")[0]}-auth-token`;
+  const value = `base64-${Buffer.from(JSON.stringify(session)).toString("base64url")}`;
+  if (value.length <= 3180) return `${name}=${value}`;
+  return value.match(/.{1,3180}/g).map((part, i) => `${name}.${i}=${part}`).join("; ");
+}
+
+// Each hosted service's sign-in, as the value the role's header carries and how long it holds.
+const SIGN_IN = new Map([
+  ["firebase", async ({ env, all }) => {
+    const account = serviceAccountOf(env);
+    const apiKey = webApiKeyOf(all);
+    if (!account || !apiKey) return { status: "absent", note: !account ? "no Firebase admin credential in your environment" : "no Firebase web API key in your environment" };
+    const got = await firebaseIdToken(account, apiKey);
+    if (!got.idToken) return { status: "refused", note: `your Firebase project refused the sign-in: ${got.error}` };
+    return { value: `Bearer ${got.idToken}`, ttl: 3600, door: "your Firebase project", said: `signed in to your app as a test user it can tell apart (${TEST_UID}, in your own Firebase project)` };
+  }],
+  ["clerk", async ({ env, account, session }) => {
+    const got = await clerkToken(env, account, session);
+    return got.token ? { value: `Bearer ${got.token}`, ttl: 60, session: got.session, door: "your Clerk development instance", said: "made a test account in your Clerk development instance for the run to sign in with" } : got;
+  }],
+  ["supabase-admin", async ({ env, account, header }) => {
+    const got = await supabaseSession(env, account);
+    if (!got.session) return got;
+    const s = got.session;
+    return {
+      value: header === "cookie" ? supabaseCookie(got.origin, s) : `Bearer ${s.access_token}`, secrets: [s.access_token, s.refresh_token],
+      ttl: Number(s.expires_in) || 3600, door: "your Supabase project", said: "made a test account in your Supabase project for the run to sign in with",
+    };
+  }],
+]);
+// Renewed this long after a sign-in: Clerk's token lives 60 s, Supabase's and Firebase's an hour.
+const RENEW_MS = { firebase: 50 * 60_000, clerk: 50_000, "supabase-admin": 55 * 60_000 };
+const PER_PERSON = new Set(["clerk", "supabase-admin"]);
+// A simulated person's own caller: the run sends `clerk:p1a2b3c4` for the person behind a trial.
+const PERSONA = /^([a-z][a-z0-9_-]{0,30}):p[0-9a-f]{8}$/;
+
 export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], say, keepSecret, appDir = () => root }) {
   const dir = join(work, "identities");
   const headerFile = (role) => join(dir, `bl-identity-${slug(role)}.header`);
-  const firebaseRoles = new Map();
+  const hosted = new Map();
+  // The roles signed in on this machine so far, in the order they were: the connect command's own
+  // test requests ask as the first when an endpoint refuses a visitor.
+  const minted = new Set();
   const envs = () => {
     // The app's own folder first: in a monorepo the root's env file is not the backend's.
     const homes = [appDir(), root];
     const own = homes.flatMap((h) => [envFiles.find((f) => dirname(f) === h && basename(f) === ".env"), envFiles.find((f) => dirname(f) === h)]).find(Boolean) ?? envFiles[0];
     return { path: own ?? join(root, ".env"), all: [process.env, ...envFiles.map(readEnv)] };
   };
-  const keep = (role, header, value) => { writeFileSync(headerFile(role), `${header}: ${value}\n`, { mode: 0o600 }); keepSecret(value.replace(/^Bearer\s+/i, "")); };
+  const merged = () => Object.assign({}, ...[...envs().all].reverse());
+  const keep = (role, header, value, secrets = []) => {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(headerFile(role), `${header}: ${value}\n`, { mode: 0o600 });
+    for (const secret of [value.replace(/^Bearer\s+/i, ""), ...secrets]) keepSecret(secret);
+  };
 
-  async function firebase(row) {
+  // A hosted service's sign-in, kept on this machine and renewed through headerFor. Only the
+  // bearer or the cookie is ever filled, whatever header a recipe names.
+  async function signIn(row) {
+    const header = row.header === "cookie" ? "cookie" : "authorization";
     const { all } = envs();
-    const merged = Object.assign({}, ...[...all].reverse());
-    if (merged.FIREBASE_AUTH_EMULATOR_HOST) return row;
-    const account = serviceAccountOf(merged);
-    const apiKey = webApiKeyOf(all);
-    if (!account || !apiKey) return { ...row, status: "absent", note: !account ? "no Firebase admin credential in your environment" : "no Firebase web API key in your environment" };
-    const got = await firebaseIdToken(account, apiKey).catch((e) => ({ error: String(e?.message ?? e).slice(0, 120) }));
-    if (!got.idToken) return { ...row, status: "refused", note: `your Firebase project refused the sign-in: ${got.error}` };
-    keep(row.role, row.header, `Bearer ${got.idToken}`);
-    if (!firebaseRoles.has(row.role)) say(`signed in to your app as a test user it can tell apart (${TEST_UID}, in your own Firebase project)`);
-    firebaseRoles.set(row.role, { header: row.header, at: Date.now() });
-    return { ...row, status: "minted", door: "your Firebase project", expires: Math.floor(Date.now() / 1000) + 3600 };
+    const got = await SIGN_IN.get(row.kind)({ env: merged(), all, header, account: accountsFor(root, [row.role])[row.role], session: hosted.get(row.role)?.session })
+      .catch((e) => ({ status: "unreachable", note: String(e?.message ?? e).slice(0, 120) }));
+    if (!got.value) return { ...row, status: got.status, note: got.note };
+    keep(row.role, header, got.value, got.secrets);
+    if (!hosted.has(row.role) && !PERSONA.test(row.role)) say(got.said);
+    hosted.set(row.role, { row: { ...row, header }, at: Date.now(), session: got.session });
+    return { ...row, header, status: "minted", door: got.door, expires: Math.floor(Date.now() / 1000) + got.ttl };
   }
 
   async function mint(body, port) {
     let recipes = Array.isArray(body?.recipes) ? body.recipes.slice(0, 12) : [];
     // On a refused first pass the raise asks again with this flag: sign in with the credential the
     // app's own environment names, filling its sign-in form or a Basic header from that pair.
-    if (body?.envCreds) {
-      const names = Object.keys(Object.assign({}, ...[...envs().all].reverse()));
-      recipes = envCredentialRecipes(recipes, names, body.loginRoutes).slice(0, 12);
-    }
+    if (body?.envCreds) recipes = envCredentialRecipes(recipes, Object.keys(merged()), body.loginRoutes).slice(0, 12);
     if (!recipes.length || !port) return { identities: [] };
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     const out = join(dir, "bl-identities.json");
     rmSync(out, { force: true });
     // ponytail: the program is Python, as it is in the sandbox. A machine without python3 mints
     // nothing and says so; port the program to this file if that turns out to be common.
-    // A Firebase caller with no emulator on this machine is signed in at their real project, below.
-    // Handed to the program it waited its whole deadline on an emulator that was never there, and
-    // one app's sign-in arrived after the world had given up waiting for it.
-    const merged = Object.assign({}, ...[...envs().all].reverse());
-    const emulated = Boolean(merged.FIREBASE_AUTH_EMULATOR_HOST);
+    // A caller a hosted service verifies is signed in at that service, below; a Firebase caller goes
+    // to the program only when an emulator stands in for their project. Handed to the program it
+    // waited its whole deadline on an emulator that was never there, and one app's sign-in arrived
+    // after the world had given up waiting for it.
+    const env = merged();
+    const emulated = Boolean(env.FIREBASE_AUTH_EMULATOR_HOST);
+    const signsHere = (r) => SIGN_IN.has(r?.kind) && !(r.kind === "firebase" && emulated);
     const refused = new Map();
     // A pair the environment names for the app's own account is the one credential the raise is
     // allowed to reuse: the elevation and existing-account guards do not apply to it.
-    for (const r of recipes) { const why = r?.envCred ? null : refusal(r, merged, (value) => inSource(root, sourceFiles(), value)); if (why && typeof r?.role === "string") refused.set(r.role, why); }
-    const forProgram = recipes.filter((r) => !refused.has(r?.role) && (r?.kind !== "firebase" || emulated));
+    for (const r of recipes) { const why = r?.envCred ? null : refusal(r, env, (value) => inSource(root, sourceFiles(), value)); if (why && typeof r?.role === "string") refused.set(r.role, why); }
+    const forProgram = recipes.filter((r) => !refused.has(r?.role) && !signsHere(r));
     // The program signs in once per role value ("staff" as sales, support, marketing), each named
     // role:value; an account made for "staff" alone was never the one it asked for.
     const accounts = accountsFor(root, forProgram.flatMap((r) => (Array.isArray(r.roles) && r.roles.length ? r.roles.map((v) => `${r.role}:${v}`) : [r.role])));
@@ -166,22 +278,42 @@ export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], s
       if (typeof recipe?.role !== "string" || !ROLE.test(recipe.role)) continue;
       const blank = { role: recipe.role, kind: recipe.kind, header: recipe.header, opens: [], door: recipe.header, where: recipe.where };
       if (refused.has(recipe.role)) { rows.push({ ...blank, status: "refused", note: refused.get(recipe.role) }); continue; }
-      const row = known.get(recipe.role) ?? (recipe.kind === "firebase" && !emulated ? { ...blank, status: "upstream" } : { ...blank, status: ran ? "unreachable" : "absent", ...(ran ? {} : { note: "python3 is not installed on this machine" }) });
-      rows.push(recipe.kind === "firebase" && row.status !== "minted" ? await firebase(row) : row);
+      if (signsHere(recipe)) { rows.push(await signIn({ ...blank, status: "upstream" })); continue; }
+      rows.push(known.get(recipe.role) ?? { ...blank, status: ran ? "unreachable" : "absent", ...(ran ? {} : { note: "python3 is not installed on this machine" }) });
+    }
+    for (const row of rows.filter((r) => r.status === "minted")) {
+      minted.add(row.role);
+      if (existsSync(headerFile(row.role))) keepSecret(readFileSync(headerFile(row.role), "utf8").split(": ").slice(1).join(": ").trim().replace(/^Bearer\s+/i, ""));
     }
-    for (const row of rows) if (row.status === "minted" && existsSync(headerFile(row.role))) keepSecret(readFileSync(headerFile(row.role), "utf8").split(": ").slice(1).join(": ").trim().replace(/^Bearer\s+/i, ""));
     return { identities: rows };
   }
 
-  // The header a role speaks with, or nothing. A Firebase token lives an hour; it is renewed here
-  // when a run outlasts it.
-  async function headerFor(role) {
-    if (!ROLE.test(role)) return null;
-    const fb = firebaseRoles.get(role);
-    if (fb && Date.now() - fb.at > 50 * 60_000) await firebase({ role, header: fb.header, kind: "firebase" }).catch(() => null);
-    // A token the app's door issued, or a credential that is itself one of their secrets (an admin
-    // key). In the sandbox the second never leaves the box; here it never leaves this machine, which
-    // is the same promise, because this is where the request is sent from.
+  // A hosted token renewed before it lapses, and a simulated person's own account signed in the
+  // first time that person speaks. One sign-in per role at a time: lanes asking together share it.
+  const renewing = new Map();
+  const tried = new Set();
+  const shared = new Set();
+  async function due(role) {
+    const held = hosted.get(role);
+    if (held) { if (Date.now() - held.at > RENEW_MS[held.row.kind]) await signIn(held.row); return; }
+    const owner = hosted.get(PERSONA.exec(role)?.[1]);
+    if (!owner || !PER_PERSON.has(owner.row.kind) || tried.has(role)) return;
+    tried.add(role);
+    const got = await signIn({ ...owner.row, role });
+    if (got.status !== "minted" && !shared.has(owner.row.role)) {
+      shared.add(owner.row.role);
+      say(`a simulated person's own test account could not be made (${got.note ?? got.status}), so that person signs in as the shared test account`);
+    }
+  }
+  const renewed = (role) => {
+    if (!renewing.has(role)) renewing.set(role, due(role).catch(() => null).finally(() => renewing.delete(role)));
+    return renewing.get(role);
+  };
+
+  // A token the app's door issued, or a credential that is itself one of their secrets (an admin
+  // key). In the sandbox the second never leaves the box; here it never leaves this machine, which
+  // is the same promise, because this is where the request is sent from.
+  function held(role) {
     const file = [headerFile(role), headerFile(role).replace(/\.header$/, ".sealed")].find((f) => { try { return statSync(f).isFile(); } catch { return false; } });
     if (!file) return null;
     const line = readFileSync(file, "utf8").split("\n")[0] ?? "";
@@ -189,5 +321,14 @@ export function makeIdentities({ root, work, envFiles, sourceFiles = () => [], s
     return at > 0 ? { name: line.slice(0, at).trim().toLowerCase(), value: line.slice(at + 2).trim() } : null;
   }
 
-  return { mint, headerFor };
+  // The header a role speaks with, or nothing. A person whose own account could not be made speaks
+  // as the role that person belongs to, the one account every trial used before.
+  async function headerFor(role) {
+    if (!ROLE.test(role)) return null;
+    await renewed(role);
+    const base = PERSONA.exec(role)?.[1];
+    return held(role) ?? (base ? held(base) : null);
+  }
+
+  return { mint, headerFor, roles: () => [...minted] };
 }

package/lib/mongo.mjs

@@ -0,0 +1,74 @@
+// A MongoDB database copied for a session on the server it lives on, with MongoDB's own tools: a
+// dump of it restored under a name of ours, and dropped after. The address carries the password, so
+// it reaches mongodump and mongorestore through a config file only this user can read, and mongosh
+// through its environment: never a command line another process on this machine can read.
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// A database bigger than this is not copied: said instead, so the person decides.
+export const MONGO_CAP = 1024 ** 3;
+
+// The address with another database in it. A user kept in the app's own database signs in there,
+// which the address says by naming that database, so the copy's address names it as the place to
+// sign in. Rewritten as text: a replica set's host list (a:27017,b:27018) is no URL a parser takes.
+export function withDb(uri, db, source) {
+  const [, head, hosts, path = "", query = "", tail = ""] = /^([^:]+:\/\/)([^/?#]*)(?:\/([^?#]*))?(\?[^#]*)?(#.*)?$/.exec(uri);
+  const cut = hosts.lastIndexOf("@");
+  const signsIn = cut > 0 && !hosts.startsWith(":") && !/[?&]authSource=/i.test(query);
+  const own = (() => { try { return decodeURIComponent(path); } catch { return path; } })();
+  const from = signsIn ? `${query ? `${query}&` : "?"}authSource=${encodeURIComponent(own || source || "admin")}` : query;
+  return `${head}${hosts}/${encodeURIComponent(db)}${from}${tail}`;
+}
+
+function run(bin, args, { env = {}, stdin = null } = {}) {
+  return new Promise((done) => {
+    const child = spawn(bin, args, { env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", ...env }, stdio: [stdin ? "pipe" : "ignore", "pipe", "pipe"] });
+    let out = "", err = "";
+    child.stdout.on("data", (d) => { out += d; });
+    child.stderr.on("data", (d) => { err = (err + d).slice(-4000); });
+    if (stdin) stdin.pipe(child.stdin);
+    child.on("error", (e) => done({ code: e.code === "ENOENT" ? "missing" : 1, out, err: String(e.message) }));
+    child.on("close", (code) => done({ code, out, err }));
+  });
+}
+// One statement against the server, the address in the environment.
+const shell = (uri, script) => run("mongosh", ["--nodb", "--quiet", "--eval", `const c = new Mongo(process.env.CORTAD_MONGO); ${script}`], { env: { CORTAD_MONGO: uri } });
+
+// Why a tool refused, as a class the sentence is written from, never in the server's own words.
+export function refusal(r) {
+  if (r.code === "missing") return "missing";
+  if (/Authentication failed|AuthenticationFailed|auth error/i.test(r.err)) return "auth";
+  if (/not authorized|Unauthorized|requires authentication/i.test(r.err)) return "rights";
+  if (/ECONNREFUSED|connection refused|server selection|No servers available|timed out/i.test(r.err)) return "down";
+  return "other";
+}
+
+export async function cloneMongo(conn, source, clone) {
+  const size = await shell(withDb(conn.uri, source, source), `print(c.getDB(${JSON.stringify(source)}).stats().dataSize)`);
+  if (size.code !== 0) return { why: refusal(size) };
+  if (Number(size.out.trim()) > MONGO_CAP) return { why: "big" };
+  const dir = mkdtempSync(join(tmpdir(), "cortad-mongo-"));
+  try {
+    writeFileSync(join(dir, "from.yaml"), `uri: ${JSON.stringify(withDb(conn.uri, source, source))}\n`, { mode: 0o600 });
+    writeFileSync(join(dir, "to.yaml"), `uri: ${JSON.stringify(withDb(conn.uri, "", source))}\n`, { mode: 0o600 });
+    const dump = spawn("mongodump", [`--config=${join(dir, "from.yaml")}`, `--db=${source}`, "--archive"], { env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "" }, stdio: ["ignore", "pipe", "pipe"] });
+    let dumpErr = "";
+    dump.stderr.on("data", (d) => { dumpErr = (dumpErr + d).slice(-4000); });
+    const dumped = new Promise((done) => { dump.on("error", (e) => done(e.code === "ENOENT" ? "missing" : 1)); dump.on("close", done); });
+    const restored = await run("mongorestore", [`--config=${join(dir, "to.yaml")}`, "--archive", `--nsInclude=${source}.*`, `--nsFrom=${source}.*`, `--nsTo=${clone}.*`], { stdin: dump.stdout });
+    const dumpCode = await dumped;
+    if (dumpCode === 0 && restored.code === 0) return { how: "dump" };
+    await dropMongo(conn, clone, source);
+    // Either side ending stops the other, which then fails for that reason alone: the telling one wins.
+    const whys = [dumpCode === 0 ? null : refusal({ code: dumpCode, err: dumpErr }), restored.code === 0 ? null : refusal(restored)].filter(Boolean);
+    return { why: whys.find((w) => w !== "other") ?? "other" };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export async function dropMongo(conn, clone, source) {
+  return (await shell(withDb(conn.uri, clone, source), `c.getDB(${JSON.stringify(clone)}).dropDatabase()`)).code === 0;
+}

package/lib/numbers-text.mjs

@@ -0,0 +1,68 @@
+import { clip, closeToCall, has, num, pack, pageOf, plural } from "./words.mjs";
+
+// Every number the run measured, whole, one call away (`findings numbers`): each group with its count
+// by class, of how many, the interval on the share that matters, and one exchange from the worst
+// group of each.
+
+const pct = (x) => `${Math.round(x * 100)}%`;
+const interval = (b) => `${pct(b.lo)} to ${pct(b.hi)}`;
+const isScale = (t) => t.classes.every((c) => /^\d+$/.test(c));
+
+const units = (n, unit) => (unit === "replies" ? plural(n, "reply", "replies") : plural(n, "conversation"));
+
+const SPLIT_WORDS = { journey: "By journey", segment: "By user segment", situation: "By place in your app", reply: "By reply" };
+const SPLIT_WORD = { journey: "journey", segment: "user segment", situation: "place", reply: "reply" };
+// The server counts in "trials"; the person reads conversations.
+const unitSaid = (unit) => (unit === "replies" ? "replies" : "conversations");
+
+// One group as a row under its header: the counts in the header's order, of how many, the average
+// on a scale, then the share named with its interval.
+function row(t, d, said) {
+  const of = units(d.of, t.unit);
+  const unsure = d.unsure ? `; ${closeToCall(d.unsure, said)}` : "";
+  const share = d.bad && d.of ? `, ${interval(d.bad)}` : "";
+  if (t.kind === "question") return `${num(d.counts?.broke ?? 0)} of ${of}${share}${unsure}`;
+  const counts = t.classes.map((c) => num(d.counts?.[c] ?? 0)).join(", ");
+  const mean = has(d.mean) ? `, average ${d.mean.toFixed(2)}` : "";
+  return `${counts} of ${of}${mean}${d.bad && t.badSaid ? `; ${num(d.bad.k)}${share}` : ""}${unsure}`;
+}
+
+// How the rows are read: a question's conversations broken, or a measurement's classes and its share.
+const headerOf = (t) => (t.kind === "question"
+  ? `  Counted as: the ${unitSaid(t.unit)} it broke in, of the ${unitSaid(t.unit)} that asked it, with the 95% interval.`
+  : `  Counted as: ${isScale(t) ? `levels ${t.classes.join(", ")}` : t.classes.join(", ")} of ${unitSaid(t.unit)}${t.badSaid ? `; then how many ${t.badSaid}, with the 95% interval` : ""}.`);
+
+function tableBlock(t) {
+  const said = {};
+  const lines = [`${t.kind === "question" ? `${t.id}  ` : ""}${clip(t.title, 400)}${t.from ? ` (${t.from})` : ""}`];
+  if (t.legend) lines.push(`  ${clip(t.legend, 500)}`);
+  lines.push(headerOf(t), `  All: ${row(t, t.all, said)}`);
+  for (const split of ["journey", "segment", "situation", "reply"]) {
+    const groups = t.by?.[split] ?? [];
+    if (!groups.length || (split !== "reply" && groups.length === 1 && groups[0].of === t.all.of)) continue;
+    lines.push(`  ${SPLIT_WORDS[split]}:`, ...groups.map((d) => `    ${clip(d.value, 90)}${d.kept ? " (saved to test fixes)" : ""}: ${row(t, d, said)}`));
+  }
+  const w = t.worst;
+  if (w) {
+    const e = w.exchange;
+    lines.push(`  Worst: ${SPLIT_WORD[w.split] ?? w.split} ${clip(w.value, 90)}.${e ? ` Conversation ${String(e.trialId).slice(0, 8)}, reply ${e.reply}.` : " Its conversations are saved to test fixes."}`);
+    if (e?.sent) lines.push(`    Sent: "${clip(e.sent, 300)}"`);
+    if (e?.answer) lines.push(`    Reply ${e.reply}: "${clip(e.answer, 300)}"`);
+    if (e?.after) lines.push(`    Then the customer: "${clip(e.after, 300)}"`);
+    if (e?.quote && e.quote !== e.answer) lines.push(`    It broke on: "${clip(e.quote, 240)}"`);
+  }
+  return lines.join("\n");
+}
+
+// Every number, whole, in pages under what every client shows at once.
+export function numbersText(d, page = 1) {
+  const n = d?.numbers;
+  if (!n) return d?.why ?? "No run has finished on this repository yet.";
+  const head = [
+    `Run ${n.runId}: every number it measured, ${plural(n.measures.length, "measurement")} and ${plural(n.questions.length, "question")} over ${plural(n.trials, "conversation")}, ${plural(n.replies, "reply", "replies")} and ${plural(n.readings, "reading")}.`,
+    "A conversation counts once in each group it played in; a reply split counts each conversation at that reply.",
+  ].join("\n");
+  const blocks = [...n.measures, ...n.questions].map(tableBlock);
+  const pages = pack(head, blocks.map((b) => `\n${b}`), `Run ${n.runId}, numbers continued.`);
+  return pageOf(pages, page, (k) => `findings numbers with page ${k}`);
+}

package/lib/pg.mjs

@@ -0,0 +1,118 @@
+// A Postgres database copied for a session on the server it lives on, with the credentials the
+// app's own settings carry, and dropped after. Postgres's own tools do the work (psql, and pg_dump
+// when the database is in use); the password reaches them through their environment, never a
+// command line another process on this machine can read.
+import { spawn } from "node:child_process";
+
+// A database bigger than this is not copied: said instead, so the person decides.
+export const PG_CAP = 1024 ** 3;
+const quote = (name) => `"${String(name).replace(/"/g, '""')}"`;
+const literal = (text) => `'${String(text).replace(/'/g, "''")}'`;
+
+const envOf = (conn, db) => ({
+  PATH: process.env.PATH ?? "",
+  HOME: process.env.HOME ?? "",
+  PGDATABASE: db,
+  PGCONNECT_TIMEOUT: "10",
+  PGAPPNAME: "cortad",
+  ...(conn.host ? { PGHOST: conn.host } : {}),
+  ...(conn.port ? { PGPORT: String(conn.port) } : {}),
+  ...(conn.user ? { PGUSER: conn.user } : {}),
+  ...(conn.password ? { PGPASSWORD: conn.password } : {}),
+  ...(conn.sslmode ? { PGSSLMODE: conn.sslmode } : {}),
+});
+
+function run(bin, args, env, input = null) {
+  return new Promise((done) => {
+    const child = spawn(bin, args, { env, stdio: [input ? "pipe" : "ignore", "pipe", "pipe"] });
+    let out = "", err = "";
+    child.stdout.on("data", (d) => { out += d; });
+    child.stderr.on("data", (d) => { err = (err + d).slice(-4000); });
+    if (input) input.pipe(child.stdin);
+    child.on("error", (e) => done({ code: e.code === "ENOENT" ? "missing" : 1, out, err: String(e.message) }));
+    child.on("close", (code) => done({ code, out, err }));
+  });
+}
+
+// One statement per -c: CREATE and DROP DATABASE refuse to run inside a transaction, and several
+// statements in one string are one.
+const psql = (conn, db, ...statements) =>
+  run("psql", ["-X", "-q", "-A", "-t", "-v", "ON_ERROR_STOP=1", "-v", "VERBOSITY=verbose", ...statements.flatMap((s) => ["-c", s])], envOf(conn, db));
+
+// Why psql refused, as a class the sentence is written from. Never the server's own words: they
+// name the user and the host, and the sentence leaves this machine.
+export function refusal(err) {
+  const code = /(?:ERROR|FATAL):\s+([0-9A-Z]{5}):/.exec(err)?.[1];
+  // A refusal while connecting carries no code, only the server's words.
+  if (code === "28P01" || code === "28000" || /password authentication failed|no pg_hba\.conf entry|role "[^"]*" does not exist|no password supplied/i.test(err)) return "auth";
+  if (code === "42501") return "rights";
+  if (code === "55006") return "busy";
+  if (code === "3D000" || /database "[^"]*" does not exist/i.test(err)) return "gone";
+  if (/server version mismatch|aborting because of server version/i.test(err)) return "version";
+  if (/Connection refused|could not connect|No such file or directory|timeout expired|could not translate host/i.test(err)) return "down";
+  return "other";
+}
+
+// The database to stand in while a copy is made: never the source, which a template copy needs
+// free of every connection, ours included.
+async function maintenance(conn, source) {
+  for (const db of ["postgres", "template1"].filter((d) => d !== source)) {
+    const r = await psql(conn, db, "select 1");
+    if (r.code === 0) return { db };
+    if (r.code === "missing") return { why: "missing" };
+    const why = refusal(r.err);
+    if (why !== "gone") return { why };
+  }
+  return { why: "other" };
+}
+
+// The copy: a template copy first, which Postgres makes file by file; when the database is in use,
+// which a template copy refuses, a dump of it restored into an empty one. Answers { how } or { why }.
+export async function clonePg(conn, source, clone) {
+  const home = await maintenance(conn, source);
+  if (!home.db) return { why: home.why };
+  const size = await psql(conn, home.db, `select pg_database_size(${literal(source)})`);
+  if (size.code !== 0) return { why: refusal(size.err) };
+  if (Number(size.out.trim()) > PG_CAP) return { why: "big" };
+  const made = await psql(conn, home.db, `CREATE DATABASE ${quote(clone)} TEMPLATE ${quote(source)}`);
+  if (made.code === 0) return { how: "template" };
+  const why = refusal(made.err);
+  if (why !== "busy") return { why };
+  const empty = await psql(conn, home.db, `CREATE DATABASE ${quote(clone)}`);
+  if (empty.code !== 0) return { why: refusal(empty.err) };
+  const dump = spawn("pg_dump", ["--no-owner", "--no-privileges"], { env: envOf(conn, source), stdio: ["ignore", "pipe", "pipe"] });
+  let dumpErr = "";
+  dump.stderr.on("data", (d) => { dumpErr = (dumpErr + d).slice(-4000); });
+  const dumped = new Promise((done) => { dump.on("error", (e) => done(e.code === "ENOENT" ? "missing" : 1)); dump.on("close", done); });
+  const restored = await run("psql", ["-X", "-q", "-v", "ON_ERROR_STOP=1", "-v", "VERBOSITY=verbose"], envOf(conn, clone), dump.stdout);
+  const dumpCode = await dumped;
+  if (dumpCode === 0 && restored.code === 0) return { how: "dump" };
+  await dropPg(conn, clone);
+  if (dumpCode === "missing") return { why: "missing" };
+  // Either side ending stops the other, which then fails for that reason alone: the telling one wins.
+  const whys = [dumpCode === 0 ? null : refusal(dumpErr), restored.code === 0 ? null : refusal(restored.err)].filter(Boolean);
+  return { why: whys.find((w) => w !== "other") ?? "other" };
+}
+
+// An empty database on a server of this machine, for a stand-in of one kept elsewhere: the app's own
+// migrations fill it. Answers { how } or { why }.
+export async function emptyPg(conn, name) {
+  const home = await maintenance(conn);
+  if (!home.db) return { why: home.why };
+  const made = await psql(conn, home.db, `CREATE DATABASE ${quote(name)}`);
+  return made.code === 0 ? { how: "empty" } : { why: refusal(made.err) };
+}
+
+// One migration file, run whole: a failed statement stops it.
+export const applySql = async (conn, db, file) =>
+  (await run("psql", ["-X", "-q", "-v", "ON_ERROR_STOP=1", "-f", file], envOf(conn, db))).code === 0;
+
+// The copy's own connections are ended first: the app is stopped by then, but a pool can outlive it.
+export async function dropPg(conn, clone) {
+  const home = await maintenance(conn);
+  if (!home.db) return false;
+  const r = await psql(conn, home.db,
+    `select pg_terminate_backend(pid) from pg_stat_activity where datname = ${literal(clone)} and pid <> pg_backend_pid()`,
+    `DROP DATABASE IF EXISTS ${quote(clone)}`);
+  return r.code === 0;
+}