@openmeet/snowglobe 0.0.0-stage → 0.3.0-rc.0

package/lib/commands/account.mjs

@@ -0,0 +1,85 @@
+// bin/snowglobe.mjs account <name> <PREFIX> [<pds>]
+//
+// account creates or finds <name> on <pds> (the PDS with bare handles, else the seed PDS):
+// <name>.<domain> there, <name>.<pds>.<domain> on the others. Its login goes into ACCOUNTS_FILE
+// (accounts.env in the snowglobe's state folder by default, mode 600) as <PREFIX>_HANDLE, _DID, _PASSWORD and _PDS, its
+// handle into the names bin/snowglobe.mjs run maps (restart a process under it to pick one up), and
+// its DID alone to stdout. A rerun finds it. It reads the rendered globe, and prints no secret
+// (lib/xrpc.mjs).
+
+import { randomBytes } from 'node:crypto';
+import { ROOT, UsageError, addName, envGet, envPut, globeFacts, loginsFile, paths } from '../env.mjs';
+import { session } from '../state.mjs';
+import { mintInvite, why, xrpc } from '../xrpc.mjs';
+
+const LABEL_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+// The authority's own account, which snowglobe up makes under this prefix. Its name is one the
+// globe keeps for itself, so no other account takes it.
+const AUTHORITY = { name: 'lex-authority', prefix: 'LEX_AUTHORITY' };
+
+export const command = {
+  name: 'account',
+  usage: 'account <name> <PREFIX> [<pds>]',
+  options: {},
+  positionals: [2, 3],
+};
+
+export async function run({ positionals: [name, prefix, pds] }) {
+  console.log(await account({ name, prefix, pds, state: session().state, log: (m) => console.error(m) }));
+}
+
+/**
+ * Create, or find, the account <name> on the globe's PDS `pds` (the one with bare handles, else
+ * the seed PDS, by default), and keep its login in `file` as <prefix>_HANDLE, _DID, _PASSWORD and
+ * _PDS. Its handle is added to the names snowglobe run maps. Resolves to the DID. A rerun signs in
+ * with the kept password and finds the account; a PDS that takes invite codes is sent one
+ * (SG_INVITE_CODE, else a single-use code minted for this account), the others none.
+ */
+export async function account({ name, prefix, pds, file, root = ROOT, state, env = process.env, log = () => {} }) {
+  if (!LABEL_RE.test(name ?? '')) throw new UsageError(`<name> must be one lowercase DNS label: ${name}`);
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(prefix ?? '')) throw new UsageError(`<PREFIX> must be an env var prefix (A-Z, 0-9, _): ${prefix}`);
+  const g = globeFacts({ root, state, env });
+  const where = pds || g.bare || g.seed;
+  if (!g.pds.includes(where)) throw new UsageError(`${where} is not a PDS in this globe (${g.pds.join(', ')})`);
+  const bare = where === g.bare;
+  const handle = bare ? `${name}.${g.domain}` : `${name}.${where}.${g.domain}`;
+  // A bare handle is <name>.<domain>, the same space as the globe's own names.
+  if (bare && g.taken.includes(name) && !(name === AUTHORITY.name && prefix === AUTHORITY.prefix))
+    throw new UsageError(`${handle} is a name the globe uses itself; pick another <name>`);
+  if (handle.length > 253) throw new UsageError(`${handle} is longer than 253 characters`);
+  const pdsUrl = `https://${where}.${g.domain}`;
+  const accounts = loginsFile(file || env.ACCOUNTS_FILE || paths(root, state).accounts);
+  const opts = { root, state, env };
+
+  const save = (did, password) =>
+    envPut(accounts, new RegExp(`^${prefix}_(HANDLE|DID|PASSWORD|PDS)=`), [
+      `${prefix}_HANDLE=${handle}`,
+      `${prefix}_DID=${did}`,
+      `${prefix}_PASSWORD=${password}`,
+      `${prefix}_PDS=${pdsUrl}`,
+    ]);
+
+  const kept = envGet(`${prefix}_PASSWORD`, accounts);
+  if (kept && envGet(`${prefix}_HANDLE`, accounts) === handle) {
+    const res = await xrpc(pdsUrl, 'com.atproto.server.createSession', { body: { identifier: handle, password: kept }, ...opts });
+    if (res.ok && typeof res.json.did === 'string') {
+      if (envGet(`${prefix}_DID`, accounts) !== res.json.did) save(res.json.did, kept);
+      addName(handle, { root, state });
+      log(`Found ${handle} -> ${res.json.did}`);
+      return res.json.did;
+    }
+    log(`${handle} is in ${accounts} but cannot sign in; creating it`);
+  }
+
+  let inviteCode;
+  if (g.invites.includes(where)) inviteCode = env.SG_INVITE_CODE || (await mintInvite(pdsUrl, 1, opts));
+  const password = randomBytes(16).toString('hex');
+  const body = { handle, email: `${name}@${bare ? g.domain : `${where}.${g.domain}`}`, password };
+  if (inviteCode) body.inviteCode = inviteCode;
+  const res = await xrpc(pdsUrl, 'com.atproto.server.createAccount', { body, ...opts });
+  if (!res.ok || typeof res.json.did !== 'string') throw new Error(`createAccount ${handle} on ${pdsUrl} failed: ${why(res)}`);
+  save(res.json.did, password);
+  addName(handle, { root, state });
+  log(`Created ${handle} on ${pdsUrl} -> ${res.json.did}`);
+  return res.json.did;
+}

package/lib/commands/app.mjs

@@ -0,0 +1,86 @@
+// bin/snowglobe.mjs app <name> <port> [<ending>] | --remove <name> | --render
+//
+// app routes https://<name>.app.<domain> to <port> on this machine through the globe's nginx
+// (lib/apps.mjs), and with <ending> every name under <ending>.<domain> too, for an app that hands
+// out handles; the leaf gains that wildcard from the same CA. Kept in https/apps in the
+// snowglobe's state folder (a rerun changes the port, and drops the ending unless given again);
+// nginx's routes and the network page are rendered from it, and nginx reloads after nginx -t if
+// the globe runs (its compose project, see lib/state.mjs). --remove drops a route; --render only
+// renders, as snowglobe up does before starting the globe.
+
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { readApps, renderRoutes, writeApps } from '../apps.mjs';
+import { ROOT, UsageError, dc, globeFacts, paths } from '../env.mjs';
+import { session } from '../state.mjs';
+
+const LABEL_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export const command = {
+  name: 'app',
+  usage: 'app <name> <port> [<ending>] | --remove <name> | --render',
+  options: { remove: { type: 'string' }, render: { type: 'boolean' } },
+  positionals: [0, 3],
+  // --render alone, --remove <name> alone, or a route (<name> <port> [<ending>]) and no option.
+  accepts: ({ positionals, tokens }) => (tokens.some((t) => t.kind === 'option') ? tokens.length === 1 : positionals.length >= 2),
+};
+
+export async function run({ values, positionals: [name, port, ending] }) {
+  const log = (m) => console.error(m);
+  const found = session();
+  if (values.render) renderRoutes({ state: found.state });
+  else if (values.remove !== undefined) await app({ name: values.remove, remove: true, state: found.state, project: found.project, log });
+  else await app({ name, port, ending, state: found.state, project: found.project, log });
+}
+
+/**
+ * Add, change or (remove) drop the route for `name`, issue the leaf if it now lacks a name (an
+ * ending's wildcard, from the same CA), render, and reload nginx in the running globe after
+ * nginx -t. A globe that is not running keeps the route; snowglobe up loads it.
+ */
+export async function app({ name, port, ending, remove = false, root = ROOT, state, project, env = process.env, log = () => {} }) {
+  if (!LABEL_RE.test(name ?? '')) throw new UsageError(`<name> must be one lowercase DNS label: ${name}`);
+  const p = paths(root, state);
+  const g = globeFacts({ root, state, env });
+  mkdirSync(p.https, { recursive: true });
+  const apps = readApps(p);
+  const others = apps.filter((a) => a.name !== name);
+
+  let newLeaf = false;
+  if (remove) {
+    if (others.length === apps.length)
+      throw new Error(`no route named ${name} in ${p.apps}; routed: ${apps.map((a) => a.name).join(' ') || 'none'}`);
+    writeApps(p, others);
+    renderRoutes({ root, state, env });
+    // The leaf keeps a removed ending's name; an extra name on a certificate is harmless.
+    log(`Removed https://${name}.app.${g.domain} (${p.apps})`);
+  } else {
+    if (!/^[1-9][0-9]{0,4}$/.test(String(port ?? '')) || Number(port) > 65535) throw new UsageError(`<port> must be a port number: ${port}`);
+    if (ending) {
+      if (!LABEL_RE.test(ending)) throw new UsageError(`<ending> must be one lowercase DNS label: ${ending}`);
+      if (ending === 'app') throw new UsageError(`<ending> app is where the apps are: ${name}.app.${g.domain}`);
+      // A PDS's handles are its own, and an ending is one app's.
+      if (g.pds.includes(ending)) throw new Error(`${ending}.${g.domain} is the PDS ${ending}'s own`);
+      const owner = others.find((a) => a.ending === ending);
+      if (owner) throw new Error(`handles under ${ending}.${g.domain} already go to ${owner.name} (${p.apps})`);
+    }
+    // A rerun with the same name changes its port, and drops its ending unless given again.
+    writeApps(p, [...others, { name, port: Number(port), ending: ending || null }]);
+    // Loaded here, so the usage, which loads every command, does without the certificate library.
+    const { ensureCerts, leafLacks, leafNames } = await import('../certs.mjs');
+    const names = leafNames(p, g.domain, env.HTTPS_EXTRA_NAMES);
+    if (leafLacks(p.https, names, p.caDir)) ({ newLeaf } = await ensureCerts({ dir: p.https, caDir: p.caDir, domain: g.domain, names, log }));
+    renderRoutes({ root, state, env });
+    log(`https://${name}.app.${g.domain} -> port ${port} on this machine (${p.apps})`);
+    if (ending) log(`https://<handle>.${ending}.${g.domain} -> the same port`);
+  }
+
+  const running = dc(project, ['ps', '-q', '--status', 'running', 'nginx'], { root, state, stdio: 'pipe', encoding: 'utf8' });
+  if (running.status !== 0 || !running.stdout.trim())
+    return log(`nginx is not running in ${project}; it loads the route when snowglobe up starts it`);
+  if (dc(project, ['exec', '-T', 'nginx', 'nginx', '-t', '-q'], { root, state }).status !== 0)
+    throw new Error(`nginx refused the new routes; ${join(p.https, 'nginx')} holds what it read`);
+  // A reload rereads the certificate too.
+  if (dc(project, ['exec', '-T', 'nginx', 'nginx', '-s', 'reload'], { root, state }).status !== 0) throw new Error('nginx did not reload');
+  log(`Reloaded nginx in ${project}${newLeaf ? ', with the new leaf' : ''}`);
+}

package/lib/commands/certs.mjs

@@ -0,0 +1,36 @@
+// bin/snowglobe.mjs certs [--check]
+//
+// certs makes the CA if there is none (one per user, kept in the state root's ca/ folder, so it is
+// trusted once for every snowglobe), and issues the leaf nginx serves when it lacks one of the
+// rendered globe's names, or another CA signed it (lib/certs.mjs). --check only says whether it would: exit 0 when
+// the leaf carries every name, 1 when it lacks one. HTTPS_EXTRA_NAMES adds names
+// (space-separated), on every run. Any failure exits 2, since 1 is --check's answer.
+
+import { ROOT, paths, resolveDomain } from '../env.mjs';
+import { session } from '../state.mjs';
+
+export const command = {
+  name: 'certs',
+  usage: 'certs [--check]',
+  options: { check: { type: 'boolean' } },
+  positionals: [0, 0],
+  // --check once at most.
+  accepts: ({ tokens }) => tokens.length <= 1,
+};
+
+export async function run({ values }) {
+  try {
+    // Loaded here, so the usage, which loads every command, does without the certificate library.
+    const { ensureCerts, leafLacks, leafNames } = await import('../certs.mjs');
+    const { state } = session();
+    const p = paths(ROOT, state);
+    const { domain } = resolveDomain({ root: ROOT, state });
+    const names = leafNames(p, domain, process.env.HTTPS_EXTRA_NAMES);
+    if (values.check) return leafLacks(p.https, names, p.caDir) ? 1 : 0;
+    await ensureCerts({ dir: p.https, caDir: p.caDir, domain, names, log: (m) => console.error(m) });
+    return 0;
+  } catch (e) {
+    console.error(`snowglobe certs: ${e.message}`);
+    return 2;
+  }
+}

package/lib/commands/check.mjs

@@ -0,0 +1,37 @@
+// bin/snowglobe.mjs check [<file>]
+//
+// check checks the file and exits 0 if it is sound, 1 with one line per problem if not
+// (lib/config.mjs has the rules). It touches nothing, and needs no Docker.
+//
+// With no <file>, SG_FILE, else ./snowglobe.yml or the nearest one in a folder above, else the
+// default globe at the repo root (snowglobe.default.yml: one PDS, a PLC directory and Jetstream). render, up and the
+// other commands find their file the same way (lib/state.mjs).
+
+import { loadGlobe } from '../config.mjs';
+import { findFile } from '../state.mjs';
+
+export const command = {
+  name: 'check',
+  usage: 'check [<file>]',
+  options: {},
+  positionals: [0, 1],
+};
+
+/**
+ * Load and check `file` (or the file check reads with none), with `domain` in place of its own
+ * when given. Each problem goes to stderr as one line; `globe` is null when there is one.
+ */
+export function checkedGlobe(file, { domain } = {}) {
+  const path = findFile({ file });
+  const { globe, errors } = loadGlobe(path, { domain });
+  for (const e of errors) console.error(`${path}: ${e}`);
+  return { path, globe: errors.length ? null : globe };
+}
+
+export function run({ positionals }) {
+  const { path, globe } = checkedGlobe(positionals[0]);
+  if (!globe) return 1;
+  const extra = globe.grouphosts.length ? `, ${globe.grouphosts.length} group host(s)` : '';
+  console.log(`${path}: ok: globe ${globe.globe} at ${globe.domain}, PDSs ${globe.pds.map((p) => p.name).join(' ')}${extra}`);
+  return 0;
+}

package/lib/commands/down.mjs

@@ -0,0 +1,37 @@
+// bin/snowglobe.mjs down [-v]
+//
+// down stops the compose project of the snowglobe in this folder (or above, see lib/state.mjs;
+// SG_PROJECT if set), on the globe up last rendered (globe/ in its state folder), and a service an
+// earlier render ran and this one does not with it.
+//   -v  also drop the project's volumes: every account, DID and record is gone. The PLC's
+//       database is a named volume, so without -v the DIDs survive with the PDSes.
+//
+// The state folder is never deleted. After -v, the next up starts over: the base init reseeds
+// alice and bob and rewrites accounts.env from scratch, dropping the logins the tools wrote there
+// (their accounts are gone too), and the lexicon authority is made again. The CA, the leaf and
+// the app routes stay either way. The project is guarded as up guards it.
+
+import { ROOT, dc, guardProject } from '../env.mjs';
+import { session } from '../state.mjs';
+
+export const command = {
+  name: 'down',
+  usage: 'down [-v]',
+  options: { volumes: { type: 'boolean', short: 'v' } },
+  positionals: [0, 0],
+  accepts: ({ tokens }) => tokens.length <= 1,
+};
+
+export function run({ values }) {
+  return down({ volumes: values.volumes });
+}
+
+export function down({ volumes = false, file, root = ROOT, env = process.env } = {}) {
+  // The shared devnet is refused before anything is looked up, even by a file that is not there.
+  if (env.SG_PROJECT) guardProject(env);
+  const found = session({ file, env });
+  const project = guardProject(env, found.name);
+  const res = dc(project, ['down', '--remove-orphans', ...(volumes ? ['-v'] : [])], { root, state: found.state, env });
+  if (res.error) throw res.error;
+  return res.status ?? 1;
+}

package/lib/commands/env.mjs

@@ -0,0 +1,145 @@
+// bin/snowglobe.mjs env [--app <name>] [--secrets] [--dotenv]
+//
+// env prints the settings an app is handed, from the apps[].env of the snowglobe.yml in this folder
+// (or above), as `export NAME='value'` lines for `eval "$(snowglobe env)"`, plus
+// NODE_EXTRA_CA_CERTS, the CA that signs the snowglobe's certificates. --dotenv prints NAME=value
+// instead, for a framework's own file (.env.local, .dev.vars) or PowerShell. With one app in the
+// file it is that app's; with several --app says which; with none only the CA is set.
+//
+// A secret (accounts.<name>.password) is left out unless --secrets is given, and a comment line
+// names each one left out. snowglobe run hands the same settings over, secrets included. Values
+// known only after up are read from the state folder; before then env says which are missing.
+// lib/settings.mjs has the names.
+
+import { existsSync } from 'node:fs';
+import { ROOT, UsageError, envGet, paths, resolveDomain, setting } from '../env.mjs';
+import { session } from '../state.mjs';
+import { isSecret, lookup, parseValue } from '../settings.mjs';
+import { accountPrefixes } from '../up.mjs';
+import { checkedGlobe } from './check.mjs';
+
+export const command = {
+  name: 'env',
+  usage: 'env [--app <name>] [--secrets] [--dotenv]',
+  options: { app: { type: 'string' }, secrets: { type: 'boolean' }, dotenv: { type: 'boolean' } },
+  positionals: [0, 0],
+};
+
+export function run({ values }) {
+  const s = appSettings({ app: values.app, secrets: values.secrets });
+  process.stdout.write(formatEnv(s, { dotenv: values.dotenv }));
+  if (!s.caExists) console.error(`snowglobe env: ${s.ca} does not exist yet; snowglobe up (or certs) makes it`);
+}
+
+/**
+ * The snowglobe a command reads settings from: { path, globe, state, p, later }. `later` gives the
+ * names known only after up, from the state folder (undefined where it has none yet). Throws,
+ * after printing each problem, when the file has any.
+ */
+function load({ file, root = ROOT, env = process.env } = {}) {
+  const found = session({ file, env });
+  const { set } = resolveDomain({ root, state: found.state, env });
+  const { path, globe } = checkedGlobe(found.path, { domain: set || undefined });
+  if (!globe) throw new Error(`${path} has problems (above)`);
+  const p = paths(root, found.state);
+  const home = (globe.pds.find((x) => x.bare_handles) ?? globe.pds[0]).name;
+  const prefixes = new Map(accountPrefixes(globe.accounts, home).map((a) => [a.name, a.prefix]));
+  const later = (name) => {
+    const [head, ...rest] = name.split('.');
+    const kept = (key) => envGet(key, p.accounts) || undefined;
+    // Each exists only once up has run; a path or port guessed before then would be wrong.
+    if (name === 'ca.file') return existsSync(p.ca) ? p.ca : undefined;
+    if (name === 'accounts.file') return existsSync(p.accounts) ? p.accounts : undefined;
+    // The mail page's port is a setting, not recorded in the state; the rendered globe says up has run.
+    if (name === 'services.mail.url') return !existsSync(p.compose) ? undefined : `http://127.0.0.1:${setting('SG_MAILDEV_WEB_PORT', { root, env }) || '1081'}`;
+    if (name === 'lexicons.authority.did') return kept('LEX_AUTHORITY_DID');
+    if (head === 'accounts') return kept(`${prefixes.get(rest[0])}_${rest[1].toUpperCase()}`);
+    return undefined;
+  };
+  return { path, globe, state: found.state, p, later };
+}
+
+// The text of a value with its placeholders filled, or the names that could not be.
+function fill(globe, text, later) {
+  const out = [];
+  for (const part of parseValue(text).parts) {
+    if (part.text !== undefined) out.push(part.text);
+    else {
+      const r = lookup(globe, part.name, later);
+      if (r.error) throw new Error(r.error);
+      out.push(r.value);
+    }
+  }
+  return out.join('');
+}
+
+/**
+ * The settings of one app of the file: { vars, left, ca, caExists }. vars is [{ name, value }] in the
+ * order the file gives them; left is [{ name, via }] for the secrets not included (without
+ * `secrets`), via the secret names in the value. The app is `app`, or the file's one app; with
+ * several `app` is required, with none vars is empty. NODE_EXTRA_CA_CERTS joins vars unless the
+ * app sets it itself.
+ */
+export function appSettings({ app, secrets = false, file, root = ROOT, env = process.env } = {}) {
+  const { path, globe, p, later } = load({ file, root, env });
+  const names = globe.apps.map((a) => a.name);
+  let chosen = null;
+  if (app !== undefined) {
+    chosen = globe.apps.find((a) => a.name === app);
+    if (!chosen) throw new UsageError(`${path} has no app named ${app} (${names.join(', ') || 'it lists none'})`);
+  } else if (globe.apps.length === 1) chosen = globe.apps[0];
+  else if (globe.apps.length > 1) throw new UsageError(`${path} lists several apps (${names.join(', ')}); say which with --app <name>`);
+
+  const vars = [];
+  const left = [];
+  for (const [name, text] of Object.entries(chosen?.env ?? {})) {
+    const via = parseValue(text).parts.filter((x) => x.name && isSecret(x.name)).map((x) => x.name);
+    if (via.length && !secrets) left.push({ name, via });
+    else {
+      try {
+        const value = fill(globe, text, later);
+        // Said by name only: the value may hold a login.
+        if (value.includes('\0')) throw new Error('the value contains a NUL character, which a process cannot be given');
+        vars.push({ name, value });
+      } catch (e) {
+        throw new Error(`${path}: apps[${globe.apps.indexOf(chosen)}].env.${name}: ${e.message}`);
+      }
+    }
+  }
+  if (!vars.some((v) => v.name === 'NODE_EXTRA_CA_CERTS')) vars.push({ name: 'NODE_EXTRA_CA_CERTS', value: p.ca, auto: true });
+  return { vars, left, ca: p.ca, caExists: existsSync(p.ca) };
+}
+
+/**
+ * The values of `names` (such as 'domain' or 'lexicons.authority.did') in the snowglobe file reads,
+ * for a script that wants a fact without an app to map it. Throws on a name the file has no value for.
+ */
+export function resolveNames(names, { file, root = ROOT, env = process.env } = {}) {
+  const { globe, later } = load({ file, root, env });
+  return names.map((n) => fill(globe, `\${${n}}`, later));
+}
+
+const quoteSh = (v) => `'${v.replace(/'/g, `'\\''`)}'`;
+// A dotenv value as dotenv (16) reads it, and Vite, which expands $NAME and ${NAME} after it. Bare
+// when plain; else in the first quote the value does not hold, single first because dotenv takes
+// that literally (double quotes expand \n and \r). null when no form reads back as the value: a
+// $ that starts a name, a carriage return, or a value with every quote in it.
+function quoteDotenv(v) {
+  if (/^[A-Za-z0-9_@%+=:,./-]*$/.test(v)) return v;
+  if (/\$[A-Za-z_{]/.test(v) || v.includes('\r')) return null;
+  for (const q of ["'", '`', '"']) if (!v.includes(q) && !(q === '"' && /\\[nr]/.test(v))) return `${q}${v}${q}`;
+  return null;
+}
+
+/** The lines env prints for `settings` (appSettings): export lines, or NAME=value with `dotenv`. */
+export function formatEnv({ vars, left }, { dotenv = false } = {}) {
+  const line = (v) => {
+    if (!dotenv) return `export ${v.name}=${quoteSh(v.value)}`;
+    const q = quoteDotenv(v.value);
+    if (q === null) throw new Error(`${v.name} cannot be written as a dotenv value (it holds a $ that starts a name, a carriage return, or every kind of quote); use snowglobe env without --dotenv`);
+    return `${v.name}=${q}`;
+  };
+  const note = (l) => `# ${l.name} left out: ${l.via.join(', ')} ${l.via.length > 1 ? 'are secrets' : 'is a secret'}; --secrets includes it`;
+  const lines = [...vars.filter((v) => v.name !== 'NODE_EXTRA_CA_CERTS').map(line), ...left.map(note), ...vars.filter((v) => v.name === 'NODE_EXTRA_CA_CERTS').map(line)];
+  return lines.map((l) => `${l}\n`).join('');
+}

package/lib/commands/invite.mjs

@@ -0,0 +1,48 @@
+// bin/snowglobe.mjs invite <VAR> [<file>] [--pds <pds>]
+//
+// invite mints an invite code, INVITE_USES uses (100), on a PDS with invites: required (the only
+// one, unless --pds names it) and writes <VAR>=<code> to <file> (accounts.env in the snowglobe's state folder).
+// SG_PDS_ADMIN_PASSWORD as the globe was started with. It reads the rendered globe, and
+// prints no secret (lib/xrpc.mjs).
+
+import { ROOT, UsageError, envPut, globeFacts, loginsFile, paths } from '../env.mjs';
+import { session } from '../state.mjs';
+import { mintInvite } from '../xrpc.mjs';
+
+export const command = {
+  name: 'invite',
+  usage: 'invite <VAR> [<file>] [--pds <pds>]',
+  options: { pds: { type: 'string' } },
+  positionals: [1, 2],
+};
+
+export async function run({ values, positionals: [variable, file] }) {
+  await invite({ variable, file, pds: values.pds, state: session().state, log: (m) => console.error(m) });
+}
+
+/**
+ * Mint an invite code on `pds`, a PDS of the globe that takes them (the only one, by default),
+ * with INVITE_USES uses (100 by default), and keep it as <variable>=<code> in `file`
+ * (accounts.env in the snowglobe's state folder by default). The code is never printed.
+ */
+export async function invite({ variable, pds, file, root = ROOT, state, env = process.env, log = () => {} }) {
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(variable ?? '')) throw new UsageError(`<VAR> must be an env var name (A-Z, 0-9, _): ${variable}`);
+  const uses = env.INVITE_USES ?? '100';
+  if (!/^[1-9][0-9]*$/.test(uses)) throw new UsageError('INVITE_USES must be a positive number');
+  const g = globeFacts({ root, state, env });
+  let where = pds;
+  if (!where) {
+    if (g.invites.length !== 1)
+      throw new UsageError(
+        g.invites.length
+          ? `more than one PDS takes invite codes (${g.invites.join(', ')}); name one with --pds`
+          : 'no PDS in this globe takes invite codes (invites: required)',
+      );
+    where = g.invites[0];
+  } else if (!g.pds.includes(where)) throw new UsageError(`${where} is not a PDS in this globe (${g.pds.join(', ')})`);
+  else if (!g.invites.includes(where)) throw new UsageError(`${where} takes no invite codes (its invites are open)`);
+  const code = await mintInvite(`https://${where}.${g.domain}`, Number(uses), { root, state, env });
+  const target = loginsFile(file || paths(root, state).accounts);
+  envPut(target, new RegExp(`^${variable}=`), [`${variable}=${code}`]);
+  log(`Wrote ${variable} to ${target}: an invite code for ${where}, ${uses} uses`);
+}

package/lib/commands/lexicons.mjs

@@ -0,0 +1,94 @@
+// bin/snowglobe.mjs lexicons <dir>
+//
+// lexicons publishes every lexicon document under <dir> into the lexicon authority
+// (LEX_AUTHORITY_* in ACCOUNTS_FILE), leaving one that holds the same document alone, and prints
+// each NSID. SG_PUBLIC=1 for a globe on the cluster, with ACCOUNTS_FILE its operator logins.
+// It prints no secret (lib/xrpc.mjs).
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT, UsageError, envGet, paths } from '../env.mjs';
+import { session } from '../state.mjs';
+import { why, xrpc } from '../xrpc.mjs';
+
+const NSID_RE = /^[a-zA-Z]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z]([a-zA-Z0-9-]*[a-zA-Z0-9])?){2,}$/;
+
+export const command = {
+  name: 'lexicons',
+  usage: 'lexicons <dir>',
+  options: {},
+  positionals: [1, 1],
+};
+
+export async function run({ positionals: [dir] }) {
+  await lexicons({ dir, state: session().state, log: (m) => console.error(m), out: (nsid) => console.log(nsid) });
+}
+
+// JSON with its keys sorted at every depth, so two equal documents compare equal as text.
+function canonical(v) {
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
+  if (v && typeof v === 'object')
+    return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(',')}}`;
+  return JSON.stringify(v);
+}
+
+// Every *.json file under dir, at any depth, in byte order of their paths.
+function jsonFiles(dir) {
+  const out = [];
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const f = join(d, e.name);
+      if (e.isDirectory()) walk(f);
+      else if (e.isFile() && e.name.endsWith('.json')) out.push(f);
+    }
+  };
+  walk(dir);
+  return out.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+}
+
+/**
+ * Publish the lexicons under `dir` (each *.json whose "lexicon" is 1 and whose "id" is an NSID;
+ * other JSON is skipped) into the lexicon authority as com.atproto.lexicon.schema records keyed by
+ * NSID. A record already holding the same document is left alone. `out` gets each NSID. The login
+ * is LEX_AUTHORITY_* in ACCOUNTS_FILE, else accounts.env in the snowglobe's state folder, which snowglobe up writes. With
+ * SG_PUBLIC=1 the authority's PDS is a public name (a globe on the cluster).
+ */
+export async function lexicons({ dir, root = ROOT, state, env = process.env, log = () => {}, out = () => {} }) {
+  if (!dir || !existsSync(dir) || !statSync(dir).isDirectory()) throw new UsageError(`no folder ${dir}`);
+  const accounts = env.ACCOUNTS_FILE || paths(root, state).accounts;
+  const did = envGet('LEX_AUTHORITY_DID', accounts);
+  const pdsUrl = envGet('LEX_AUTHORITY_PDS', accounts);
+  const password = envGet('LEX_AUTHORITY_PASSWORD', accounts);
+  if (!did || !pdsUrl || !password) throw new Error(`no LEX_AUTHORITY_* login in ${accounts}; run snowglobe up`);
+  const opts = { root, state, env };
+
+  const session = await xrpc(pdsUrl, 'com.atproto.server.createSession', { body: { identifier: did, password }, ...opts });
+  if (!session.ok || typeof session.json.accessJwt !== 'string') throw new Error(`the authority cannot sign in: ${why(session)}`);
+  const auth = `Bearer ${session.json.accessJwt}`;
+
+  const n = { published: 0, unchanged: 0, skipped: 0 };
+  for (const f of jsonFiles(dir)) {
+    let doc;
+    try {
+      doc = JSON.parse(readFileSync(f, 'utf8'));
+    } catch {}
+    const nsid = doc?.lexicon === 1 && typeof doc.id === 'string' ? doc.id : '';
+    if (!NSID_RE.test(nsid)) {
+      log(`skipped (not a lexicon document): ${f}`);
+      n.skipped++;
+      continue;
+    }
+    const record = { ...doc, $type: 'com.atproto.lexicon.schema' };
+    const key = { repo: did, collection: 'com.atproto.lexicon.schema', rkey: nsid };
+    const current = await xrpc(pdsUrl, 'com.atproto.repo.getRecord', { query: key, ...opts });
+    if (current.ok && current.json.value && canonical(current.json.value) === canonical(record)) n.unchanged++;
+    else {
+      const put = await xrpc(pdsUrl, 'com.atproto.repo.putRecord', { body: { ...key, record }, auth, ...opts });
+      if (!put.ok || typeof put.json.uri !== 'string') throw new Error(`putRecord ${nsid} failed: ${why(put)}`);
+      n.published++;
+    }
+    out(nsid);
+  }
+  log(`Authority ${did}: ${n.published} published, ${n.unchanged} unchanged, ${n.skipped} skipped`);
+  return n;
+}

package/lib/commands/render.mjs

@@ -0,0 +1,63 @@
+// bin/snowglobe.mjs render [<file>] [--out <dir>] [--domain <domain>]
+//
+// render checks the file as check does (exit 1 with one line per problem), then writes the https
+// globe it describes into <dir> (globe/ in the snowglobe's state folder by default, see
+// lib/state.mjs): compose.yml, nginx's servers, the leaf certificate's names and globe.env, the
+// facts the other commands read (lib/render.mjs). Nothing in them is secret. --domain replaces the file's domain, for a copy beside another globe. A group
+// host with no image or build folder in the file is built from the folder its kind's variable
+// names (SG_OPENSOCIAL_BUILD, a checkout of atproto-group-host); with neither, render fails.
+
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { withGroupHostSources } from '../config.mjs';
+import { ROOT, paths } from '../env.mjs';
+import { loadBase, renderGlobe } from '../render.mjs';
+import { claimState, session } from '../state.mjs';
+import { checkedGlobe } from './check.mjs';
+
+export const command = {
+  name: 'render',
+  usage: 'render [<file>] [--out <dir>] [--domain <domain>]',
+  options: { out: { type: 'string' }, domain: { type: 'string' } },
+  positionals: [0, 1],
+};
+
+export function run({ values, positionals }) {
+  const { path, globe } = checkedGlobe(positionals[0], { domain: values.domain });
+  if (!globe) return 1;
+  let out;
+  try {
+    // Into the state folder, the file takes it over; into --out, it only reads where the state is.
+    const s = session({ file: path });
+    if (values.out === undefined) claimState(s);
+    out = writeGlobe(globe, path, values.out ?? paths(ROOT, s.state).globe, process.env, s.state);
+  } catch (e) {
+    for (const line of e.message.split('\n')) console.error(`${path}: ${line}`);
+    return 1;
+  }
+  console.log(`${path}: wrote ${out}: globe ${globe.globe} at ${globe.domain}, PDSs ${globe.pds.map((p) => p.name).join(' ')}`);
+  return 0;
+}
+
+/**
+ * Write the checked `globe`, read from `path`, into `out`, a folder; returns it. `state` is the
+ * snowglobe's state folder, which the compose file mounts from. Throws, before writing anything,
+ * when a group host has nowhere to get its image from.
+ */
+export function writeGlobe(globe, path, out, env, state) {
+  globe = withGroupHostSources(globe, env);
+  // The compose file mounts nginx's part of the output, by a path from the repo root, which is
+  // the compose project directory (lib/env.mjs dc).
+  out = resolve(out);
+  const rel = relative(ROOT, out);
+  const globeDir = rel && !rel.startsWith('..') && !isAbsolute(rel) ? rel : out;
+  const files = renderGlobe(globe, loadBase(ROOT), { stateDir: state, globeDir, source: basename(path) });
+  for (const [name, text] of Object.entries(files)) {
+    const target = join(out, name);
+    mkdirSync(dirname(target), { recursive: true });
+    // Written aside and renamed, so nothing reads half a file.
+    writeFileSync(`${target}.tmp`, text);
+    renameSync(`${target}.tmp`, target);
+  }
+  return out;
+}