@bygghammar/cms-platform 0.91.1 → 0.92.1

package/scripts/cms-review.mjs

@@ -0,0 +1,832 @@
+#!/usr/bin/env node
+/**
+ * Review what an upgrade to contract v3 would do to a site's public pages, and
+ * turn the answers into something the migration will accept.
+ *
+ * 0.90.0-m7.12 and 0.91.1 read publication rows differently. The old reader
+ * dropped closed rows before picking the newest; the new one picks the newest
+ * row that has started and only then asks whether it is still open. Where a
+ * page has an expired row newer than its open one, the new reader serves
+ * nothing and the page goes dark. Most pages are unaffected, some the migration
+ * can settle from the data alone, and a few cannot be settled without somebody
+ * saying what the page is supposed to be doing. This is where that somebody
+ * says it.
+ *
+ *   cms-review scan                 what is here, and what it would become
+ *   cms-review show                 the same, read back from the review file
+ *   cms-review resolve <key> <what> record an answer for one page
+ *   cms-review approve              seal the answers against this database
+ *   cms-review options              the startup options the migration reads
+ *   cms-review record               the same approval as an installable record
+ *
+ * An approval reaches a database by one of two roads, and both carry the same
+ * fields in the same spellings because both are printed from one description of
+ * the approval. `options` is the direct road: a connection this machine makes
+ * itself. `record` is the road onto a server nobody connects to from here --
+ * the file it prints is carried over, installed by an administrator with
+ * install-lovable-migration-approval, and replayed into the connection that
+ * applies the migration.
+ *
+ * The database to read comes from CMS_REVIEW_DSN, or DATABASE_URL. It is never
+ * passed on a command line: a connection string in argv is a password in every
+ * `ps` on the machine. A read-only role is enough for scan; nothing here writes.
+ *
+ * Typical run:
+ *
+ *   export CMS_REVIEW_DSN=postgres://...
+ *   cms-review scan
+ *   cms-review resolve marketing-offer leave-hidden --by you@example.com
+ *   cms-review approve --site-key voyara --environment production \
+ *                      --release-sha "$GITHUB_SHA" --by you@example.com
+ *   PGOPTIONS="$(cms-review options)" psql -f 20260905120000_....sql
+ *
+ * or, for a server this machine cannot reach:
+ *
+ *   cms-review record > 20260905120000_....sql.approval
+ *   # carry it over, then, on the host:
+ *   sudo install-lovable-migration-approval <site> <environment> <file>
+ *
+ * The approval binds itself to this database, to this migration file, to the
+ * exact rows the scan saw and to the moment it was evaluated. The migration
+ * checks all of that again on the other side, because the helper and the
+ * database can disagree and the database is the one that knows.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..");
+
+/* ------------------------------------------------------------------ saying */
+
+const bail = (...lines) => {
+  for (const line of lines) console.error(line);
+  process.exit(1);
+};
+
+/* ---------------------------------------------------- the shared classifier */
+
+// Imported from the TypeScript that ships rather than written again here. The
+// migration is already a second implementation of this classification, held to
+// the first by tests/fixtures/publication-review-corpus.json; a third one
+// living in the CLI would be a third opinion about what a page is showing.
+// Node strips the types on the way in, which it has done by default since
+// 22.18 -- older ones get told so rather than a stack trace about `export type`.
+let classifyPage, canonicalInputs, REVIEW_DECISIONS, canonicalJson, digestJson, MIGRATION_MANIFEST;
+try {
+  ({ classifyPage, canonicalInputs, REVIEW_DECISIONS } = await import(
+    join(root, "src/platform/publication-review.ts")
+  ));
+  ({ canonicalJson, digestJson } = await import(join(root, "src/platform/digest.ts")));
+  ({ MIGRATION_MANIFEST } = await import(join(root, "src/platform/migration-manifest.ts")));
+} catch (error) {
+  bail(
+    `cms-review reads this package's TypeScript sources directly, and node ${process.versions.node} could not.`,
+    "Node 22.18 or newer strips types on its own; on an older one, run it under a newer node.",
+    "",
+    String(error?.message ?? error),
+  );
+}
+
+/* -------------------------------------------------------------- the arguments */
+
+// Every --flag takes a value, so the token after one is never a subcommand and
+// never a page key. Reading argv in order rather than searching it is what
+// keeps `cms-review --file r.json scan` from trying to run a subcommand called
+// r.json.
+const flags = new Map();
+const positional = [];
+{
+  const argv = process.argv.slice(2);
+  for (let i = 0; i < argv.length; i += 1) {
+    if (!argv[i].startsWith("--")) {
+      positional.push(argv[i]);
+      continue;
+    }
+    const name = argv[i].slice(2);
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith("--")) bail(`--${name} needs a value.`);
+    flags.set(name, value);
+    i += 1;
+  }
+}
+
+const command = positional[0] ?? "help";
+const flag = (name, fallback) => flags.get(name) ?? fallback;
+
+/*
+ * A process list is world-readable, and it is read: `ps` on a shared VPS, a
+ * shell history file, a CI log that echoes the command it ran. So this CLI has
+ * no option that takes a credential, and rather than silently ignoring one it
+ * says where the credential belongs. The value check catches the same mistake
+ * spelled differently -- a service-role JWT handed to --by, a whole connection
+ * URI handed to --site-key.
+ */
+const CREDENTIAL_FLAGS = new Set([
+  "password", "pass", "pw", "key", "api-key", "anon-key", "secret", "token",
+  "service-role", "service-role-key", "dsn", "database-url", "connection-string",
+]);
+const JWT = /^[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}$/;
+const URI_WITH_PASSWORD = /^[a-z][a-z0-9+.-]*:\/\/[^/@\s]*:[^/@\s]+@/i;
+const ENV_FILE_ADVICE = [
+  "Credentials do not travel on a command line, where every process listing shows them.",
+  "Put the connection string in a root-owned 0600 file and export it from there:",
+  "",
+  "    CMS_REVIEW_DSN=postgres://reviewer:...@host:5432/app",
+  "",
+  "A role with SELECT on pages, page_versions and page_publications is enough to scan.",
+];
+for (const name of flags.keys()) {
+  if (CREDENTIAL_FLAGS.has(name)) bail(`cms-review has no --${name}.`, "", ...ENV_FILE_ADVICE);
+}
+for (const [name, value] of [...flags, ...positional.map((v) => ["an argument", v])]) {
+  if (JWT.test(value) || URI_WITH_PASSWORD.test(value)) {
+    const where = name === "an argument" ? name : `--${name}`;
+    bail(`${where} looks like a credential.`, "", ...ENV_FILE_ADVICE);
+  }
+}
+
+const filePath = resolve(flag("file", ".cms-review.json"));
+
+/* ------------------------------------------------------------- the database */
+
+let pgEnv;
+function connection() {
+  if (pgEnv) return pgEnv;
+  const dsn = process.env.CMS_REVIEW_DSN ?? process.env.DATABASE_URL ?? "";
+  if (!dsn) {
+    bail(
+      "No database to read.",
+      "Set CMS_REVIEW_DSN (or DATABASE_URL) to the site you are reviewing.",
+      "A role with SELECT on pages, page_versions and page_publications is enough.",
+    );
+  }
+  let url;
+  try {
+    url = new URL(dsn);
+  } catch {
+    bail("CMS_REVIEW_DSN is not a connection URL.");
+  }
+  if (!/^postgres(ql)?:$/.test(url.protocol)) {
+    bail(`CMS_REVIEW_DSN must be a postgres:// URL, not ${url.protocol}//`);
+  }
+  // Taken apart into PG* variables rather than handed to psql as an argument,
+  // so the password stays out of argv and out of every process listing.
+  pgEnv = { ...process.env };
+  delete pgEnv.PGSERVICE;
+  delete pgEnv.PGOPTIONS;
+  if (url.hostname) pgEnv.PGHOST = decodeURIComponent(url.hostname);
+  if (url.port) pgEnv.PGPORT = url.port;
+  if (url.username) pgEnv.PGUSER = decodeURIComponent(url.username);
+  if (url.password) pgEnv.PGPASSWORD = decodeURIComponent(url.password);
+  const database = url.pathname.replace(/^\//, "");
+  if (database) pgEnv.PGDATABASE = decodeURIComponent(database);
+  const sslmode = url.searchParams.get("sslmode");
+  if (sslmode) pgEnv.PGSSLMODE = sslmode;
+  return pgEnv;
+}
+
+/** Runs one of the shipped .sql files and returns its single answer. */
+function ask(name) {
+  const result = spawnSync(
+    "psql",
+    ["-X", "-q", "-t", "-A", "-v", "ON_ERROR_STOP=1", "-f", "-"],
+    { input: readFileSync(join(here, name), "utf8"), encoding: "utf8", env: connection() },
+  );
+  if (result.error?.code === "ENOENT") {
+    bail("cms-review needs psql on PATH to read the database.");
+  }
+  if (result.status !== 0) {
+    bail(`Could not read the database (${name}):`, (result.stderr || "").trim());
+  }
+  return result.stdout.trim();
+}
+
+/* ------------------------------------------------------------- the review file */
+
+const FORM = "cms-platform-publication-review";
+const MIGRATION = "20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24";
+
+function load() {
+  if (!existsSync(filePath)) {
+    bail(`No review at ${filePath}.`, "Run `cms-review scan` first.");
+  }
+  let review;
+  try {
+    review = JSON.parse(readFileSync(filePath, "utf8"));
+  } catch (error) {
+    bail(`${filePath} is not readable json: ${error.message}`);
+  }
+  if (review?.form !== FORM) bail(`${filePath} is not a cms-review file.`);
+  return review;
+}
+
+const save = (review) => writeFileSync(filePath, `${JSON.stringify(review, null, 2)}\n`);
+
+/**
+ * PGOPTIONS is split on whitespace by the server, so a value containing any
+ * would arrive as a separate, unparseable argument and the connection would
+ * fail with something that says nothing about notes or e-mail addresses. Caught
+ * where the text is typed instead.
+ */
+function spaceFree(what, value) {
+  if (/\s/.test(value)) bail(`${what} cannot contain spaces or newlines: ${JSON.stringify(value)}`);
+  return value;
+}
+
+/**
+ * A moment, to the second, in UTC.
+ *
+ * Every timestamp an approval carries is written this way, and the reason is
+ * that one of the two roads out of here compares them as text. The server-side
+ * record is read by a shell script that has no date parser and does not want
+ * one: fixed-width, zero-padded and UTC-only is exactly the shape that sorts
+ * correctly under a string comparison, so `expires` and `now` can be compared
+ * without either side agreeing on a timezone database.
+ *
+ * Truncating rather than rounding is deliberate in both directions. An
+ * evaluation moved a fraction of a second earlier widens the window the
+ * migration checks for publication rows that moved underneath the review, and
+ * an expiry moved a fraction earlier expires marginally sooner. Both errors
+ * land on the side of refusing.
+ */
+const atSecond = (when) => `${new Date(when).toISOString().slice(0, 19)}Z`;
+
+/* --------------------------------------------------------------- the commands */
+
+async function scan() {
+  const seen = JSON.parse(ask("review-scan.sql"));
+  // Truncated here, not on the way out, so the moment the pages were classified
+  // against and the moment the approval reports are the same moment. Rounding
+  // one of them later would leave the review describing a classification that
+  // was made a fraction of a second after the time it claims.
+  const evaluatedAt = new Date(Math.floor(Date.now() / 1000) * 1000);
+  const owners = new Map(Object.entries(seen.versionOwners));
+  const items = [];
+  for (const page of seen.pages) {
+    const item = classifyPage(page, evaluatedAt, owners);
+    items.push({
+      ...item,
+      inputsDigest: await digestJson(canonicalInputs(item)),
+      // Whether `publish-legacy-version` is even an honest answer for this page.
+      // The migration refuses to write another page's version into a fresh
+      // publication row under a note claiming preservation; better to know that
+      // while the reviewer is still reading than at three in the morning.
+      legacyVersionOwned:
+        item.legacyVersionId !== null && owners.get(item.legacyVersionId) === item.pageId,
+    });
+  }
+
+  const review = {
+    form: FORM,
+    migration: MIGRATION,
+    databaseIdentity: seen.databaseIdentity,
+    clusterIdentity: seen.clusterIdentity,
+    evaluatedAt: atSecond(evaluatedAt),
+    inputFingerprint: await digestJson(JSON.parse(ask("review-fingerprint.sql"))),
+    items,
+    decisions: [],
+    approval: null,
+  };
+  save(review);
+  report(review);
+  console.log(`\nWritten to ${filePath}.`);
+}
+
+function report(review) {
+  const tally = new Map();
+  for (const item of review.items) {
+    tally.set(item.classification, (tally.get(item.classification) ?? 0) + 1);
+  }
+  console.log(`${review.items.length} live page(s), read at ${review.evaluatedAt}:`);
+  for (const [name, count] of [...tally].sort()) console.log(`  ${String(count).padStart(4)}  ${name}`);
+
+  const answered = new Map(review.decisions.map((d) => [d.pageKey, d]));
+  const open = review.items.filter((i) => i.requiresDecision && !answered.has(i.pageKey));
+  const preserved = review.items.filter((i) => i.classification === "preserved");
+
+  if (preserved.length > 0) {
+    console.log(`\n${preserved.length} page(s) the upgrade keeps alive on its own:`);
+    for (const item of preserved) console.log(`  ${item.pageKey}  ${item.reason ?? ""}`);
+  }
+  if (open.length === 0) {
+    console.log("\nNothing here needs a decision.");
+    return;
+  }
+  console.log(`\n${open.length} page(s) need somebody to say what should happen:`);
+  for (const item of open) {
+    console.log(`  ${item.pageKey}  [${item.classification}]`);
+    console.log(`      ${item.reason ?? ""}`);
+    console.log(
+      `      answers: ${item.legacyVersionOwned ? "publish-legacy-version, " : ""}leave-hidden, no-change`,
+    );
+  }
+  console.log("\n  cms-review resolve <page-key> <answer> --by you@example.com");
+}
+
+function resolve_() {
+  const review = load();
+  const [, pageKey, decision] = positional;
+  if (!pageKey || !decision) bail("Usage: cms-review resolve <page-key> <decision> --by <e-mail>");
+
+  const item = review.items.find((i) => i.pageKey === pageKey);
+  if (!item) bail(`No page called ${pageKey} in this review.`);
+  if (!REVIEW_DECISIONS.includes(decision)) {
+    bail(`${decision} is not an answer. One of: ${REVIEW_DECISIONS.join(", ")}`);
+  }
+  if (!item.requiresDecision) {
+    bail(
+      `${pageKey} classified as ${item.classification}, which the upgrade settles on its own.`,
+      "Recording an answer for it would claim a question was asked that was not.",
+    );
+  }
+  if (decision === "publish-legacy-version" && !item.legacyVersionOwned) {
+    bail(
+      `${pageKey} cannot be republished: the version recorded for it belongs to another page.`,
+      "leave-hidden records the outage honestly; repairing the version pointer is a",
+      "separate, deliberate change and not something an upgrade should do quietly.",
+    );
+  }
+
+  const by = spaceFree("--by", flag("by", ""));
+  if (!by) bail("--by <e-mail> so the record says who decided.");
+  const note = spaceFree("--note", flag("note", ""));
+
+  review.decisions = [
+    ...review.decisions.filter((d) => d.pageKey !== pageKey),
+    {
+      pageId: item.pageId,
+      pageKey,
+      decision,
+      expectedInputsDigest: item.inputsDigest,
+      resolvedByEmail: by,
+      note: note || null,
+    },
+  ].sort((a, b) => (a.pageId < b.pageId ? -1 : 1));
+
+  // An approval describes a set of answers. Changing one of them makes it a
+  // description of something else.
+  if (review.approval) {
+    review.approval = null;
+    console.log("The earlier approval no longer describes these answers, so it was dropped.");
+  }
+  save(review);
+
+  const left = review.items.filter(
+    (i) => i.requiresDecision && !review.decisions.some((d) => d.pageKey === i.pageKey),
+  );
+  console.log(`${pageKey}: ${decision}. ${left.length} page(s) still unanswered.`);
+}
+
+/**
+ * What an approval is about, said out loud before it is sealed.
+ *
+ * Sealing is where a review stops being a document and starts being something
+ * that lets a migration change a database, so this is the last point at which
+ * somebody can notice they are pointed at the wrong one. --confirm-environment
+ * has to be typed to match: where CMS_ENVIRONMENT is set the deployment's own
+ * answer is what must be matched, and where it is not, the operator says the
+ * name twice. A staging manifest cannot then be built against production by
+ * recalling the wrong line from a shell history.
+ */
+function confirmEnvironment(review, { siteKey, environment, releaseSha, packageVersion }) {
+  const declared = process.env.CMS_ENVIRONMENT ?? "";
+  if (declared && declared !== environment) {
+    bail(
+      `This connection says it is ${declared}, and --environment says ${environment}.`,
+      "One of them is wrong, and neither this CLI nor the migration can tell which.",
+    );
+  }
+  const target = connection();
+
+  console.log("Sealing an approval that will let a migration change a live database.\n");
+  console.log(`  site            ${siteKey}`);
+  console.log(`  environment     ${environment}${declared ? "" : "   (declared here; CMS_ENVIRONMENT is not set)"}`);
+  console.log(`  database        ${review.databaseIdentity}`);
+  console.log(`  host            ${target.PGHOST ?? "(unset)"}:${target.PGPORT ?? "5432"}/${target.PGDATABASE ?? "(unset)"}`);
+  console.log(`  release         ${releaseSha}`);
+  console.log(`  package         ${packageVersion}`);
+  console.log(`  migration       ${MIGRATION}`);
+  console.log(`  pages answered  ${review.decisions.length} of ${review.items.length} scanned`);
+  console.log(`  scanned at      ${review.evaluatedAt}\n`);
+
+  if (flag("confirm-environment", "") !== environment) {
+    bail(
+      `Nothing has been sealed. Read the block above; if it is the database you mean,`,
+      `run the same command again with --confirm-environment ${environment}.`,
+    );
+  }
+}
+
+/** Everything an approval speaks for, in the order digestJson will read it. */
+const reviewBody = (review) => ({
+  databaseIdentity: review.databaseIdentity,
+  decisions: payloadOf(review),
+  evaluatedAt: review.evaluatedAt,
+  inputFingerprint: review.inputFingerprint,
+  items: review.items.map((item) => canonicalInputs(item)),
+  migration: review.migration,
+});
+
+/** The decision list as the migration reads it: SQL column names, sorted. */
+const payloadOf = (review) =>
+  review.decisions.map((d) => ({
+    page_id: d.pageId,
+    decision: d.decision,
+    expected_inputs_digest: d.expectedInputsDigest,
+    resolved_by_email: d.resolvedByEmail,
+    note: d.note,
+  }));
+
+async function approve() {
+  const review = load();
+  const open = review.items.filter(
+    (i) => i.requiresDecision && !review.decisions.some((d) => d.pageKey === i.pageKey),
+  );
+  if (open.length > 0) {
+    bail(
+      `${open.length} page(s) have not been answered for:`,
+      ...open.map((i) => `  ${i.pageKey}  [${i.classification}]`),
+      "",
+      "The migration refuses an approval with an unanswered page, so this does too,",
+      "here where you can still do something about it.",
+    );
+  }
+
+  const by = spaceFree("--by", flag("by", ""));
+  if (!by) bail("--by <e-mail> so the record says who approved.");
+  const siteKey = spaceFree("--site-key", flag("site-key", ""));
+  const environment = spaceFree("--environment", flag("environment", ""));
+  const releaseSha = spaceFree("--release-sha", flag("release-sha", process.env.GITHUB_SHA ?? ""));
+  if (!siteKey || !environment || !releaseSha) {
+    bail("--site-key, --environment and --release-sha say which deployment this approves.");
+  }
+
+  const seconds = Number(flag("expires-in", "3600"));
+  if (!Number.isInteger(seconds) || seconds < 60 || seconds > 86_400) {
+    bail("--expires-in is a whole number of seconds between 60 and 86400.");
+  }
+
+  const file = join(root, "migrations", `${MIGRATION}.sql`);
+  if (!existsSync(file)) bail(`This package does not carry ${MIGRATION}.sql.`);
+
+  const packageVersion = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+  confirmEnvironment(review, { siteKey, environment, releaseSha, packageVersion });
+
+  const payload = payloadOf(review);
+  review.approval = {
+    // Hyphens dropped: an approval is carried to a server as a text record
+    // whose reader holds every field to one spelling, and this one it holds to
+    // thirty-two hex digits. PostgreSQL reads that form as a uuid, so nothing
+    // downstream has to know which spelling was chosen -- but the two sides
+    // have to have chosen the same one, and this is where it is chosen.
+    approvalNonce: randomUUID().replace(/-/g, ""),
+    runId: randomUUID(),
+    siteKey,
+    environment,
+    releaseSha,
+    packageVersion,
+    // Bytes, not canonical json: this one is a digest of a file, and what it
+    // pins is that the .sql applied is the .sql reviewed against.
+    migrationDigest: createHash("sha256").update(readFileSync(file)).digest("hex"),
+    manifestDigest: flag("manifest-digest", await manifestDigest()),
+    approvalExpiresAt: atSecond(Date.now() + seconds * 1000),
+    approvedByEmail: by,
+    decisionsDigest: await digestJson(payload),
+    // The manifest's own content. install-lovable-migration-approval recomputes
+    // it and refuses a file that was edited after it was approved -- which is
+    // the same promise decisionsDigest makes to the migration, one step earlier
+    // and about the whole file rather than the answers alone.
+    reviewDigest: await digestJson(reviewBody(review)),
+  };
+  save(review);
+
+  console.log(`Approved by ${by}, for ${siteKey}/${environment}.`);
+  console.log(`Valid until ${review.approval.approvalExpiresAt} -- the migration refuses it after that.`);
+  console.log(`\n  PGOPTIONS="$(cms-review options --file ${filePath})" psql -f ${file}`);
+}
+
+/**
+ * What this package ships, as one value: every canonical migration and its bytes.
+ *
+ * Read off the directory rather than out of `src/platform/migration-manifest.ts`,
+ * even though that file holds the same names and the same digests. The manifest
+ * is what the package *claims*; an approval has to be bound to what the package
+ * *is*. Derive this from the claim and an edited `.sql` whose manifest row was
+ * never regenerated would produce a digest that matched -- exactly the
+ * substitution the binding exists to notice.
+ *
+ * The manifest is still worth reading, for the one question the directory
+ * cannot answer by itself: whether this package's two records of itself agree.
+ */
+async function manifestDigest() {
+  const dir = join(root, "migrations");
+  const files = readdirSync(dir).filter((f) => f.endsWith(".sql")).sort();
+  const entries = files.map((name) => ({
+    name,
+    digest: createHash("sha256").update(readFileSync(join(dir, name))).digest("hex"),
+  }));
+
+  const line = (name, digest) => `${name} ${digest}`;
+  const claimed = MIGRATION_MANIFEST.map((m) => line(m.name, m.sha256)).join("\n");
+  const actual = entries.map((e) => line(e.name, e.digest)).join("\n");
+  if (claimed !== actual) {
+    bail(
+      "This package's migration manifest does not describe its own migrations/ directory.",
+      "",
+      "In a checkout, that means a migration was edited without regenerating the catalog:",
+      "  npm run manifest",
+      "",
+      "In an installed package it means something rather worse, because publishing checks",
+      "this. Re-install from the registry before approving anything against this copy.",
+    );
+  }
+
+  return digestJson(entries);
+}
+
+/**
+ * The fields an approval travels as, in the one order both roads use.
+ *
+ * The order is not cosmetic. The record reader on a server walks this list and
+ * refuses a file whose lines arrive in any other sequence, because two
+ * spellings of one approval are two approvals and only one of them was
+ * reviewed. It is mirrored in APPROVAL_RECORD_KEYS in the deployment
+ * template's lovable-authority-records.sh, and the round-trip gate
+ * (ops/approval-record-roundtrip.mjs) is what keeps the two copies honest.
+ */
+const APPROVAL_RECORD_KEYS = [
+  "approval_nonce",
+  "site_key",
+  "environment",
+  "database_identity",
+  "review_database_identity",
+  "release_sha",
+  "package_version",
+  "migration_name",
+  "migration_digest",
+  "run_id",
+  "input_fingerprint",
+  "manifest_digest",
+  "decision_count",
+  "decisions",
+  "decisions_digest",
+  "evaluated_at",
+  "approval_expires_at",
+  "classified_by_email",
+  "approved_by_email",
+];
+
+/**
+ * One description of a sealed approval, printed two ways.
+ *
+ * Both roads out of here -- the connection this machine makes, and the file an
+ * administrator installs on a server -- carry the same fields with the same
+ * spellings, because both are rendered from this. They were once built
+ * separately, and separately is how they came to disagree about how a nonce is
+ * spelled, how many digits a timestamp has, and whether the decisions travel at
+ * all. A single builder cannot drift from itself.
+ *
+ * Two identities are carried, and they are not alternatives:
+ *
+ *   database_identity         the cluster, as initdb named it. What the
+ *                             deployment tooling compares against the running
+ *                             server, so an approval cannot be spent on a
+ *                             cluster that was thrown away and recreated.
+ *   review_database_identity  the database inside it, by name and oid. What
+ *                             the migration compares, because two databases in
+ *                             one cluster share the first identity and are not
+ *                             the same database to review.
+ *
+ * Each side checks the one it means; neither interprets the other's.
+ */
+function approvalSettings(review) {
+  const a = review.approval;
+  const payload = payloadOf(review);
+  return {
+    approval_nonce: a.approvalNonce,
+    site_key: a.siteKey,
+    environment: a.environment,
+    database_identity: review.clusterIdentity,
+    review_database_identity: review.databaseIdentity,
+    release_sha: a.releaseSha,
+    package_version: a.packageVersion,
+    // The file name, not the internal name. It is what the deployment tooling
+    // has in its hand -- the migration it is about to apply, by its basename --
+    // and the migration strips the suffix back off before comparing.
+    migration_name: `${review.migration}.sql`,
+    migration_digest: a.migrationDigest,
+    run_id: a.runId,
+    input_fingerprint: review.inputFingerprint,
+    manifest_digest: a.manifestDigest,
+    decision_count: String(review.decisions.length),
+    // Canonical text, and the digest beside it is the digest of exactly these
+    // bytes. The server-side reader has no json parser: it digests the field as
+    // it found it and compares. `JSON.stringify` would preserve insertion order
+    // and produce text whose digest is not the one that was sealed.
+    //
+    // Always present, including as the empty list. An approval that answered
+    // nothing still says so, rather than saying nothing -- a missing field and
+    // a field saying "no decisions" are different claims, and the reader is
+    // right to refuse a record that makes neither.
+    decisions: canonicalJson(payload),
+    decisions_digest: a.decisionsDigest,
+    evaluated_at: review.evaluatedAt,
+    approval_expires_at: a.approvalExpiresAt,
+    // Who is answerable for this, carried rather than left behind. Without
+    // these the migration has no address to write into its audit columns and
+    // falls back to a sentinel that is nobody, so an upgrade a person approved
+    // would be recorded as one that nobody approved.
+    classified_by_email: a.approvedByEmail,
+    approved_by_email: a.approvedByEmail,
+  };
+}
+
+/** The sealed approval, or a refusal. Shared by both roads so they agree. */
+function sealed() {
+  const review = load();
+  if (!review.approval) bail("This review has not been approved. Run `cms-review approve`.");
+  if (Date.parse(review.approval.approvalExpiresAt) <= Date.now()) {
+    bail(
+      `This approval expired at ${review.approval.approvalExpiresAt}.`,
+      "Scan again: the database may have moved on since it was read.",
+    );
+  }
+  if (!review.clusterIdentity) {
+    bail(
+      `${filePath} was scanned before an approval carried the cluster's identity.`,
+      "Run `cms-review scan` again: the deployment tooling compares that identity",
+      "against the server it is about to change, and cannot be told it afterwards.",
+    );
+  }
+  return review;
+}
+
+function options() {
+  const review = sealed();
+  const text = Object.entries(approvalSettings(review))
+    .map(([name, value]) => `-c lovable.${name}=${spaceFree(name, String(value))}`)
+    .join(" ");
+
+  // PostgreSQL's startup packet is a little under 10000 bytes and the options
+  // travel inside it. A site with more answered pages than that fits cannot be
+  // approved this way, and saying so here is better than a connection that
+  // fails on the far side without naming a cause.
+  if (Buffer.byteLength(text, "utf8") > 9000) {
+    bail(
+      `These ${review.decisions.length} answers do not fit in a connection's startup options`,
+      `(${Buffer.byteLength(text, "utf8")} bytes, and the server's limit is near 10000).`,
+      "Answer the pages in smaller groups, or resolve some of them in the site before upgrading.",
+    );
+  }
+  process.stdout.write(`${text}\n`);
+}
+
+/*
+ * The shapes the record reader holds each field to.
+ *
+ * A second copy of somebody else's rules, which is worth being uncomfortable
+ * about. They live in approval_field_is_wellformed in the deployment template
+ * and that is where they are enforced; these exist so that a record this
+ * command prints is refused *here*, by name, while the person who ran it is
+ * still watching -- rather than on a server, hours later, by a script that can
+ * only say the file is malformed. The round-trip gate runs a real record
+ * through the real reader, so the copy cannot quietly fall out of step.
+ */
+/*
+ * An address, bounded where the reader bounds it.
+ *
+ * The lookahead counts the whole field. An earlier spelling put the bound
+ * inside the local part instead, which let this command print a 262-byte
+ * address that read_approval_record then refused on the server -- the exact
+ * failure this table exists to move back to the keyboard of whoever ran the
+ * command. The reader counts ${#value} across the whole value, so this counts
+ * the whole value too: the two agree by construction rather than by
+ * resemblance.
+ *
+ * What an address may look like is deliberately not decided here. One printable
+ * token, one @, a dotted domain: enough that it cannot carry a space into
+ * PGOPTIONS or a newline into the record, and no opinion beyond that.
+ */
+const RECORD_EMAIL =
+  /^(?=.{3,254}$)[!-?A-~]+@[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+$/;
+
+const RECORD_SHAPES = {
+  approval_nonce: [/^[0-9a-f]{32}$/, "thirty-two lowercase hex digits"],
+  site_key: [/^[a-z][a-z0-9-]{1,30}$/, "a lowercase letter, then 1-30 letters, digits or hyphens"],
+  environment: [/^(staging|production)$/, "staging or production"],
+  database_identity: [/^[0-9]{1,20}$/, "the cluster's identifier, all digits"],
+  review_database_identity: [/^[!-~]{1,120}$/, "printable, no spaces, at most 120 characters"],
+  release_sha: [/^[0-9a-f]{40}$/, "a full forty-character commit sha"],
+  package_version: [/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/, "a semantic version"],
+  migration_name: [/^[A-Za-z0-9_.-]+\.sql$/, "a migration file name ending in .sql"],
+  migration_digest: [/^[0-9a-f]{64}$/, "a sha256, sixty-four lowercase hex digits"],
+  run_id: [/^[A-Za-z0-9_.:/-]{1,200}$/, "1-200 characters from A-Z a-z 0-9 _ . : / -"],
+  input_fingerprint: [/^[0-9a-f]{64}$/, "a sha256, sixty-four lowercase hex digits"],
+  manifest_digest: [/^[0-9a-f]{64}$/, "a sha256, sixty-four lowercase hex digits"],
+  decision_count: [/^[0-9]{1,6}$/, "a count, at most six digits"],
+  decisions: [/^[ -~]{1,8192}$/, "printable ascii, 1 to 8192 characters"],
+  decisions_digest: [/^[0-9a-f]{64}$/, "a sha256, sixty-four lowercase hex digits"],
+  evaluated_at: [/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/, "a UTC timestamp to the second, ending in Z"],
+  approval_expires_at: [/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/, "a UTC timestamp to the second, ending in Z"],
+  classified_by_email: [RECORD_EMAIL, "an e-mail address, 254 characters at the most"],
+  approved_by_email: [RECORD_EMAIL, "an e-mail address, 254 characters at the most"],
+};
+
+/**
+ * The approval as a file, for a database this machine cannot reach.
+ *
+ * Printed rather than written, so where it lands and who owns it is the
+ * caller's decision and not a surprise. The administrator's install command is
+ * what gives it a home, an owner and a mode.
+ *
+ * Everything is checked against the reader's own shapes before a byte is
+ * printed. A record is refused on the far side rather than repaired, so half a
+ * record is worse than none: the operator who carried it would find out on a
+ * server, and the only thing they could do about it is come back here.
+ */
+function record() {
+  const review = sealed();
+  const settings = approvalSettings(review);
+
+  const wrong = [];
+  for (const key of APPROVAL_RECORD_KEYS) {
+    const value = String(settings[key] ?? "");
+    const [shape, described] = RECORD_SHAPES[key];
+    if (!shape.test(value)) wrong.push([key, value, described]);
+  }
+  if (wrong.length > 0) {
+    bail(
+      "This approval cannot be written as a record a server will accept:",
+      "",
+      ...wrong.flatMap(([key, value, described]) => [
+        `  ${key}`,
+        `    is    ${value === "" ? "(empty)" : JSON.stringify(value)}`,
+        `    wants ${described}`,
+      ]),
+      "",
+      "The record is judged whole, on the host, by a reader that refuses rather",
+      "than repairs -- so it is judged here too, where it can still be reissued.",
+      "`cms-review options` is unaffected: a direct connection carries these",
+      "fields under looser rules than a file left on a server does.",
+    );
+  }
+
+  // The reader's budget, checked before the file exists rather than at install
+  // time on the host. The composed form is what has to fit, so the composed
+  // form is what is measured -- the record itself is a little longer, and
+  // measuring that instead would refuse approvals that would have travelled.
+  const composed = APPROVAL_RECORD_KEYS
+    .map((key) => `-c lovable.${key}=${String(settings[key]).replace(/\\/g, "\\\\").replace(/ /g, "\\ ")}`)
+    .join(" ");
+  if (composed.length > 8192) {
+    bail(
+      `These ${review.decisions.length} answers do not fit in a connection's startup options`,
+      `(${composed.length} bytes composed, and the reader's budget is 8192).`,
+      "Answer the pages in smaller groups, or split the change across migrations.",
+    );
+  }
+
+  process.stdout.write(APPROVAL_RECORD_KEYS.map((key) => `${key}=${settings[key]}\n`).join(""));
+}
+
+/* -------------------------------------------------------------------- go */
+
+switch (command) {
+  case "scan":
+    await scan();
+    break;
+  case "show":
+    report(load());
+    break;
+  case "resolve":
+    resolve_();
+    break;
+  case "approve":
+    await approve();
+    break;
+  case "options":
+    options();
+    break;
+  case "record":
+    record();
+    break;
+  default:
+    // The comment at the top of this file is the manual. Keeping one text means
+    // a reader of the source and a reader of `cms-review help` cannot be told
+    // two different things.
+    console.log(
+      readFileSync(fileURLToPath(import.meta.url), "utf8")
+        .split("*/")[0]
+        .split("/**")[1]
+        .split("\n")
+        .map((line) => line.replace(/^\s*\* ?/, ""))
+        .join("\n")
+        .trim(),
+    );
+    if (command !== "help") console.error(`\nNot a command: ${command}`);
+    process.exit(command === "help" ? 0 : 1);
+}