@atelic-action/ui 0.15.1 → 0.16.1

package/src/scripts/check-access.ts

@@ -0,0 +1,93 @@
+/**
+ * The build guard for a private artifact, and the first step of `bun run
+ * build`. The practice's FOOTPRINT.md, Privacy: anything that carries a
+ * private signal is never hosted publicly, and a private artifact deploys
+ * only to a host with the wall armed. So when site.config.ts says
+ * `access: "private"` and the build is running on Vercel, the three
+ * variables that arm the wall must be set on the project, or the build
+ * fails before anything ships. A local build of a private artifact passes
+ * with a warning, because the wall only ever runs on the host.
+ *
+ * Usage: atelic-check-access   (run by `bun run build`, from the site's root)
+ * Exits 1 when a private artifact would deploy without its wall.
+ */
+import { loadSite } from "./site-config";
+
+/** What arms the wall (ACCESS-GATE.md, Turn It On). */
+export const WALL_VARIABLES = ["GATE_SESSION_SECRET", "GATE_ALLOWLIST", "RESEND_API_KEY"] as const;
+
+export interface AccessDecision {
+	verdict: "pass" | "warn" | "fail";
+	message: string;
+}
+
+function list(names: readonly string[]): string {
+	if (names.length === 1) return names[0];
+	return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+
+/**
+ * The decision, kept pure so it can be tested without a build: the
+ * artifact's `access` line and the environment the build runs in.
+ * `VERCEL` is set by Vercel on every build, and nowhere else.
+ */
+export function decideAccess(
+	access: unknown,
+	env: Record<string, string | undefined>,
+): AccessDecision {
+	if (access === "public") {
+		return {
+			verdict: "pass",
+			message: "[access] public: built from public signals, no wall needed.",
+		};
+	}
+	if (access !== "private") {
+		return {
+			verdict: "fail",
+			message:
+				'[access] src/site.config.ts has no access line. Set access to "public" (built only from public signals) or "private" (anything from the owner\'s own consoles), per the practice\'s FOOTPRINT.md, Privacy.',
+		};
+	}
+	const missing = WALL_VARIABLES.filter((name) => !env[name]?.trim());
+	if (!env.VERCEL) {
+		const owed = missing.length
+			? ` Before it deploys, set ${list(missing)} on its Vercel project, or the build there fails.`
+			: "";
+		return {
+			verdict: "warn",
+			message: `[access] private, built locally: the wall only runs on the host, so this build is not a deploy.${owed}`,
+		};
+	}
+	if (missing.length === 0) {
+		return {
+			verdict: "pass",
+			message: "[access] private, and the wall's variables are set on this project.",
+		};
+	}
+	return {
+		verdict: "fail",
+		message: `[access] This artifact is private (src/site.config.ts, access: "private"), and the wall is not armed on this Vercel project. Set ${list(missing)} in the project's Settings, Environment Variables, for this environment, then redeploy. ACCESS-GATE.md says what each one holds. Nothing private deploys without the wall.`,
+	};
+}
+
+/**
+ * The command: reads the config of the site in `cwd` and decides. The
+ * config is found from the working directory, since this file no longer
+ * lives in the site.
+ */
+export async function main(cwd: string = process.cwd()): Promise<void> {
+	let access: unknown;
+	try {
+		access = (await loadSite(cwd)).access;
+	} catch (error) {
+		console.error(`[access] ${(error as Error).message}`);
+		process.exit(1);
+	}
+	const decision = decideAccess(access, process.env);
+	if (decision.verdict === "fail") {
+		console.error(decision.message);
+		process.exit(1);
+	}
+	if (decision.verdict === "warn") console.warn(decision.message);
+	else console.log(decision.message);
+}

package/src/scripts/check-links.ts

@@ -0,0 +1,104 @@
+/**
+ * External link checker: scans every prerendered page in dist/client for
+ * outbound hrefs and media sources, then verifies each URL responds.
+ * Internal link integrity is already enforced at build time by the
+ * prerender crawler; this covers the links that rot silently — booking
+ * portals, map embeds, hosted images, font stylesheets.
+ *
+ * Usage: atelic-check-links, or `bun run check:links` in a site (requires a
+ * completed `bun build`, and runs from the site's root)
+ * Exits 1 if any external link is dead.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = "dist/client";
+const ATTR_URL = /(?:href|src)="(https?:\/\/[^"]+)"/g;
+// Hosts that reject bots or are placeholders; skip rather than false-alarm.
+// Substack 403s datacenter IPs (GitHub runners) regardless of user agent.
+const SKIP_HOSTS = new Set(["example.com", "schema.org", "www.schema.org", "substack.com"]);
+const SKIP_SUFFIXES = [".example.com", ".substack.com"];
+
+function htmlFiles(dir: string): string[] {
+	return readdirSync(dir).flatMap((name) => {
+		const path = join(dir, name);
+		if (statSync(path).isDirectory()) return htmlFiles(path);
+		return name.endsWith(".html") ? [path] : [];
+	});
+}
+
+function canonicalHost(html: string): string | null {
+	const match = html.match(/rel="canonical" href="(https?:\/\/[^"]+)"/);
+	return match ? new URL(match[1]).hostname : null;
+}
+
+function collectUrls(): Map<string, Set<string>> {
+	const urls = new Map<string, Set<string>>();
+	const files = htmlFiles(ROOT);
+	// The site's own canonical/OG URLs reference the production domain, which
+	// may not be cut over yet — and internal integrity is already enforced by
+	// the prerender crawler. Skip the canonical host entirely.
+	const ownHost = files.map((f) => canonicalHost(readFileSync(f, "utf8"))).find(Boolean);
+	for (const file of files) {
+		// Preconnect hints are bare origins (they often 404 at "/") — they warm
+		// connections, they aren't content links.
+		const html = readFileSync(file, "utf8").replace(/<link rel="preconnect"[^>]*>/g, "");
+		for (const match of html.matchAll(ATTR_URL)) {
+			const url = match[1].replace(/&amp;/g, "&");
+			const host = new URL(url).hostname;
+			if (SKIP_HOSTS.has(host) || SKIP_SUFFIXES.some((s) => host.endsWith(s))) continue;
+			if (ownHost && (host === ownHost || host === `www.${ownHost}`)) continue;
+			if (!urls.has(url)) urls.set(url, new Set());
+			urls.get(url)?.add(file.replace(`${ROOT}/`, ""));
+		}
+	}
+	return urls;
+}
+
+async function probe(url: string): Promise<number> {
+	const attempt = async (method: "HEAD" | "GET") => {
+		const res = await fetch(url, {
+			method,
+			redirect: "follow",
+			signal: AbortSignal.timeout(15000),
+			headers: { "user-agent": "Mozilla/5.0 (link-check; +https://atelic.me)" },
+		});
+		return res.status;
+	};
+	try {
+		const status = await attempt("HEAD");
+		// Some hosts reject HEAD; retry with GET before judging.
+		return status >= 400 ? await attempt("GET") : status;
+	} catch {
+		try {
+			return await attempt("GET");
+		} catch {
+			return 0;
+		}
+	}
+}
+
+/** The command: checks the build in the working directory. */
+export async function main(): Promise<void> {
+	const urls = collectUrls();
+	console.log(`[links] checking ${urls.size} external URLs across ${ROOT}`);
+
+	let failures = 0;
+	for (const [url, pages] of urls) {
+		const status = await probe(url);
+		const ok = status >= 200 && status < 400;
+		if (!ok) {
+			failures++;
+			console.error(`  DEAD (${status || "no response"}): ${url}`);
+			console.error(`        referenced by: ${[...pages].join(", ")}`);
+		} else {
+			console.log(`  ok (${status}): ${url}`);
+		}
+	}
+
+	if (failures > 0) {
+		console.error(`[links] ${failures} dead external link(s)`);
+		process.exit(1);
+	}
+	console.log("[links] all external links alive");
+}

package/src/scripts/check-wall.ts

@@ -0,0 +1,357 @@
+/**
+ * The deploy proof for a private artifact: the wall answers before any link
+ * goes out (the practice's FOOTPRINT.md, Privacy). It asks the live host
+ * for each document with no cookie and passes only when every one answers
+ * with the wall's redirect to /login. A document that answers 200 is
+ * readable by anyone holding the link, and a 5xx is a host that is down
+ * rather than walled; both fail.
+ *
+ * The documents are /writeup, plus /report and /proposal when this repo
+ * carries those routes. The wall holds files too (needsSession in @atelic-action/ui/gate), so it
+ * also asks for the printed copy at /writeup.pdf, the first real screenshot
+ * under public/images/, and, when the repo has been built, the first chunk
+ * under /assets/doc/, where a document's content compiles to. Each of those
+ * must answer with the same redirect: the wall holds a path whether or not
+ * the file is there, so a 404 means the wall never ran for it.
+ *
+ * One thing must stay open on purpose: when public/brand/ has a file, it
+ * asks for the first and requires a 200. Brand marks live there because the
+ * header draws them on every page, the login page included, and a mark the
+ * wall held would leave the login page asking for a file it cannot have.
+ *
+ * Then it proves the two sign in functions answer, because a wall whose
+ * functions cannot load holds every page and can send no link. It posts an
+ * address on no allowlist to /api/auth/request-link, so nothing is ever
+ * sent, and requires the 200 every address gets. It asks
+ * /api/auth/verify for a token that is not one and requires the function's
+ * own 302 back to /login?e=expired. A 5xx from either is a function that
+ * failed to load: on 2026-10-01 both failed on an extensionless import.
+ *
+ * Usage: atelic-check-wall <host> [path ...], or `bun run check:wall <host>`
+ * in a site, from the site's root
+ *   bun run check:wall summit.atelic.me
+ *   bun run check:wall https://summit.atelic.me /writeup /report
+ * The sign in functions are asked only when no path is named.
+ * Exits 1 unless every path answers as it must.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * One thing to ask the host for. Every probe but a sign in one is a GET with
+ * no body.
+ */
+export type Probe =
+	| {
+			path: string;
+			/**
+			 * A page the wall must stand in front of, a file it must hold back, or a
+			 * brand mark it must leave open.
+			 */
+			kind: "document" | "file" | "open";
+	  }
+	| {
+			path: string;
+			/**
+			 * A sign in function that must answer for itself: the request for a
+			 * link is a POST that must answer 200, and the verify is a GET that
+			 * must answer its own redirect back to /login.
+			 */
+			kind: "signin";
+			method: "GET" | "POST";
+			/** Sent as JSON with a POST. */
+			body?: Record<string, string>;
+	  };
+
+/** The shape of an answer the classifier reads; a fetch Response fits it. */
+export interface WallAnswer {
+	status: number;
+	headers: { get(name: string): string | null };
+}
+
+export interface WallVerdict {
+	ok: boolean;
+	reason: string;
+}
+
+/** A bare host or a full URL, as its origin. */
+export function toOrigin(host: string): string {
+	const withScheme = /^https?:\/\//.test(host) ? host : `https://${host}`;
+	return new URL(withScheme).origin;
+}
+
+export interface WallTargets {
+	/** Whether this repo carries a route, by its file name in src/routes/. */
+	hasRoute: (name: string) => boolean;
+	/** The first file under public/images/, as a path from the host root. */
+	image?: string;
+	/** The first chunk under dist/client/assets/doc/, when the repo is built. */
+	docChunk?: string;
+	/** The first file under public/brand/, which must stay open. */
+	brand?: string;
+}
+
+/** The paths to ask for: the documents this repo carries, the held files, then the open mark. */
+export function wallProbes({ hasRoute, image, docChunk, brand }: WallTargets): Probe[] {
+	const probes: Probe[] = [{ path: "/writeup", kind: "document" }];
+	if (hasRoute("report")) probes.push({ path: "/report", kind: "document" });
+	if (hasRoute("proposal")) probes.push({ path: "/proposal", kind: "document" });
+	probes.push({ path: "/writeup.pdf", kind: "file" });
+	if (image) probes.push({ path: image, kind: "file" });
+	if (docChunk) probes.push({ path: docChunk, kind: "file" });
+	if (brand) probes.push({ path: brand, kind: "open" });
+	return probes;
+}
+
+/** The address the sign in request posts: on no allowlist, so no link is ever sent. */
+export const CHECK_EMAIL = "wall-check@example.com";
+
+/** The two sign in functions, asked by default after the wall's own probes. */
+export function signinProbes(): Probe[] {
+	return [
+		{
+			path: "/api/auth/request-link",
+			kind: "signin",
+			method: "POST",
+			body: { email: CHECK_EMAIL },
+		},
+		{ path: "/api/auth/verify?token=not-a-token", kind: "signin", method: "GET" },
+	];
+}
+
+/** The first file in a directory, sorted, as `prefix/name`; none if it is empty or absent. */
+export function firstFile(dir: string, prefix: string): string | undefined {
+	if (!existsSync(dir)) return undefined;
+	const name = readdirSync(dir, { withFileTypes: true })
+		.filter((entry) => entry.isFile() && !entry.name.startsWith("."))
+		.map((entry) => entry.name)
+		.sort()[0];
+	return name ? `${prefix}/${encodeURIComponent(name)}` : undefined;
+}
+
+const HOST_DOWN =
+	"the host is failing, not walled. On 2026-09-09 a new artifact host answered MIDDLEWARE_INVOCATION_FAILED on every page (ATE-537): verify the host answers before any link goes out.";
+
+/** Whether a brand mark answered open, as it must. */
+function classifyOpen(answer: WallAnswer, origin: string): WallVerdict {
+	const { status } = answer;
+	if (status === 200) {
+		return { ok: true, reason: `${status}: open on purpose, a brand mark the header draws` };
+	}
+	if (status >= 300 && status < 400) {
+		const location = answer.headers.get("location");
+		const toLogin = location && new URL(location, origin).pathname === "/login";
+		return {
+			ok: false,
+			reason: toLogin
+				? `${status} to /login: the wall holds a brand mark, so the login page asks for a file it cannot have. Brand marks stay open under /brand/ (needsSession in @atelic-action/ui/gate)`
+				: `${status} to ${location ?? "nowhere"}: a brand mark should answer 200`,
+		};
+	}
+	if (status > 200 && status < 300) {
+		return {
+			ok: false,
+			reason: `${status}: a brand mark should answer 200 with the file, not another success code`,
+		};
+	}
+	if (status === 404) {
+		return { ok: false, reason: "404: the brand mark is not on the host. Check the deploy" };
+	}
+	if (status >= 500) return { ok: false, reason: `${status}: ${HOST_DOWN}` };
+	if (status === 0) return { ok: false, reason: `no answer: ${HOST_DOWN}` };
+	return { ok: false, reason: `${status}: a brand mark should answer 200` };
+}
+
+const FUNCTION_FAILED =
+	"the sign in function failed to load. On 2026-10-01 the first host with the wall armed answered FUNCTION_INVOCATION_FAILED here (ERR_MODULE_NOT_FOUND on an extensionless import), so the wall held every page and could send no link: the two files under api/auth/ must each be a re export from @atelic-action/ui, whose gate ships compiled for this reason";
+
+/** Whether a sign in function answered for itself, as it must. */
+function classifySignin(
+	probe: Extract<Probe, { kind: "signin" }>,
+	answer: WallAnswer,
+	origin: string,
+): WallVerdict {
+	const { status } = answer;
+	if (status >= 500) return { ok: false, reason: `${status}: ${FUNCTION_FAILED}` };
+	if (status === 0) return { ok: false, reason: `no answer: ${HOST_DOWN}` };
+	if (status === 401 || status === 403) {
+		return {
+			ok: false,
+			reason: `${status}: Vercel Deployment Protection or another lock answered, not the function. Turn Deployment Protection off (DEPLOY.md)`,
+		};
+	}
+	if (status === 404) {
+		return { ok: false, reason: "404: the sign in function is not on the host. Check the deploy" };
+	}
+	const location = answer.headers.get("location");
+	if (probe.method === "POST") {
+		if (status === 200) {
+			return { ok: true, reason: "200: the request for a link answered, sending nothing" };
+		}
+		return {
+			ok: false,
+			reason: `${status}${location ? ` to ${location}` : ""}: the request for a link answers 200 to every address`,
+		};
+	}
+	// A token that is not one gets the function's own redirect, marked expired;
+	// the wall's redirect carries ?next= instead, so the two cannot be mistaken.
+	const target = location ? new URL(location, origin) : undefined;
+	if (
+		status === 302 &&
+		target?.pathname === "/login" &&
+		target.searchParams.get("e") === "expired"
+	) {
+		return { ok: true, reason: "302 to /login?e=expired: the verify answered a bad token" };
+	}
+	return {
+		ok: false,
+		reason: `${status}${location ? ` to ${location}` : ""}: the verify answers a bad token with a 302 to /login?e=expired`,
+	};
+}
+
+/**
+ * Whether one answer is the wall (or, for a brand mark, open, or for a sign
+ * in function, its own answer), and if not, what it is instead.
+ */
+export function classifyWall(probe: Probe, answer: WallAnswer, origin: string): WallVerdict {
+	if (probe.kind === "open") return classifyOpen(answer, origin);
+	if (probe.kind === "signin") return classifySignin(probe, answer, origin);
+	const { status } = answer;
+	if (status >= 300 && status < 400) {
+		const location = answer.headers.get("location");
+		if (location && new URL(location, origin).pathname === "/login") {
+			return { ok: true, reason: `${status} to /login: the wall answered` };
+		}
+		return {
+			ok: false,
+			reason: `${status} to ${location ?? "nowhere"}, not the wall's /login: something other than the wall answered`,
+		};
+	}
+	if (status >= 200 && status < 300) {
+		const type = answer.headers.get("content-type") ?? "no content type";
+		return probe.kind === "file"
+			? {
+					ok: false,
+					reason: `${status} (${type}): the file is served outside the wall, so anyone with its address can open it. Check the middleware is the current one (needsSession in @atelic-action/ui/gate) and that the wall is armed`,
+				}
+			: {
+					ok: false,
+					reason: `${status} (${type}): the document is served with no wall, so anyone with the link can read it. Arm the wall (ACCESS-GATE.md), redeploy, and run this again`,
+				};
+	}
+	if (status === 404) {
+		return probe.kind === "file"
+			? {
+					ok: false,
+					reason:
+						"404: the wall never ran for this file. It holds a path whether or not the file is there, so a miss means the middleware let the request through",
+				}
+			: {
+					ok: false,
+					reason: "404: the host does not serve this page. Check the deploy and the prerender list",
+				};
+	}
+	if (status === 401 || status === 403) {
+		return {
+			ok: false,
+			reason: `${status}: Vercel Deployment Protection or another lock answered, not the wall. Turn Deployment Protection off (DEPLOY.md) so the wall is what a reader meets`,
+		};
+	}
+	if (status >= 500) return { ok: false, reason: `${status}: ${HOST_DOWN}` };
+	if (status === 0) return { ok: false, reason: `no answer: ${HOST_DOWN}` };
+	return { ok: false, reason: `${status}: an answer the wall never gives` };
+}
+
+export type Fetcher = (url: string, init: RequestInit) => Promise<WallAnswer>;
+
+/** The request for one probe: a GET unless a sign in probe says otherwise, with no cookie. */
+export function probeRequest(probe: Probe): RequestInit {
+	const headers: Record<string, string> = {
+		"user-agent": "Mozilla/5.0 (wall-check; +https://atelic.me)",
+	};
+	const init: RequestInit = {
+		method: probe.kind === "signin" ? probe.method : "GET",
+		redirect: "manual",
+		headers,
+		signal: AbortSignal.timeout(15000),
+	};
+	if (probe.kind === "signin" && probe.body) {
+		headers["content-type"] = "application/json";
+		init.body = JSON.stringify(probe.body);
+	}
+	return init;
+}
+
+/** Asks for every probe with no cookie and never follows a redirect. */
+export async function checkWall(origin: string, probes: Probe[], fetcher: Fetcher) {
+	const results: Array<Probe & WallVerdict> = [];
+	for (const probe of probes) {
+		let answer: WallAnswer;
+		try {
+			answer = await fetcher(`${origin}${probe.path}`, probeRequest(probe));
+		} catch {
+			answer = { status: 0, headers: { get: () => null } };
+		}
+		results.push({ ...probe, ...classifyWall(probe, answer, origin) });
+	}
+	return results;
+}
+
+/**
+ * The command. The routes, the images, the brand marks, and the build it
+ * reads are the site's, found from the working directory.
+ */
+export async function main(args: string[], root: string = process.cwd()): Promise<void> {
+	const [host, ...paths] = args;
+	if (!host) {
+		console.error("usage: bun run check:wall <host> [path ...]");
+		process.exit(2);
+	}
+	const origin = toOrigin(host);
+	const probes: Probe[] = paths.length
+		? paths.map((path) => ({
+				path,
+				kind: path.startsWith("/brand/")
+					? "open"
+					: /\.[a-z0-9]+$/i.test(path)
+						? "file"
+						: "document",
+			}))
+		: [
+				...wallProbes({
+					hasRoute: (name) => existsSync(join(root, "src", "routes", `${name}.tsx`)),
+					image: firstFile(join(root, "public", "images"), "/images"),
+					docChunk: firstFile(join(root, "dist", "client", "assets", "doc"), "/assets/doc"),
+					brand: firstFile(join(root, "public", "brand"), "/brand"),
+				}),
+				...signinProbes(),
+			];
+	if (!probes.some((probe) => probe.path.startsWith("/images/"))) {
+		console.warn("[wall] no file under public/images/ to ask for; the screenshots go unproven");
+	}
+	if (!probes.some((probe) => probe.path.startsWith("/assets/doc/"))) {
+		console.warn(
+			"[wall] no build in dist/client/assets/doc/; run bun run build first to prove the content chunks",
+		);
+	}
+	console.log(`[wall] asking ${origin} for ${probes.length} paths with no cookie`);
+	const results = await checkWall(origin, probes, (url, init) => fetch(url, init));
+	for (const result of results) {
+		const line = `  ${result.ok ? "ok" : "FAIL"} ${result.path}: ${result.reason}`;
+		if (result.ok) console.log(line);
+		else console.error(line);
+	}
+	const failed = results.filter((result) => !result.ok).length;
+	if (failed > 0) {
+		console.error(
+			`[wall] ${failed} of ${results.length} failed. No link goes out until this passes.`,
+		);
+		process.exit(1);
+	}
+	const signin = probes.some((probe) => probe.kind === "signin");
+	console.log(
+		signin
+			? "[wall] the wall holds every document and file asked for, the brand mark is open, and the sign in functions answered"
+			: "[wall] the wall holds every document and file asked for, and the brand mark is open",
+	);
+}

package/src/scripts/reader-link.ts

@@ -0,0 +1,108 @@
+/**
+ * Mint a named reader and print the two things that come of it: the line
+ * that goes in site.config.ts and the link that goes in the email. Every
+ * link sent to a named person carries their token, so their open lands on
+ * their contact in HubSpot (DEPLOY.md, Who Opened It).
+ *
+ * The config line holds the reader sealed: a digest of the token and the
+ * email encrypted under it. The token itself appears only in the link, so
+ * keep the link; it cannot be printed again.
+ *
+ * A writeup's reader also gets the printed copy's QR: public/images/qr.png
+ * is written to carry the same link, so a scan of the sheet lands on that
+ * person's contact as an emailed open does. Mint the reader before printing.
+ *
+ * The sheet belongs to the first reader named. A later reader never
+ * repoints it: with a reader already in analytics.identify the QR is left
+ * alone unless --qr asks for it.
+ *
+ * Usage: atelic-reader-link <email> [path] [--token <existing token>] [--qr | --no-qr],
+ *   or `bun run reader <email>` in a site, from the site's root.
+ *   path defaults to /writeup. --token seals an email under a token that is
+ *   already in a sent link, so that link keeps working. --qr writes the QR
+ *   for this reader even when another is already named; --no-qr never writes it.
+ */
+import { resolve } from "node:path";
+import QRCode from "qrcode";
+import { mintToken, readerLink, sealReader } from "../artifact/readers";
+import { loadSite } from "./site-config";
+
+export const USAGE =
+	"Usage: bun run reader <email> [path] [--token <existing token>] [--qr | --no-qr]";
+
+/** What the command line asked for. */
+export interface ReaderArgs {
+	email: string;
+	/** The page the link opens, always with one leading slash and none trailing. */
+	path: string;
+	/** A token already in a sent link, when --token gave one. */
+	token?: string;
+	/** --qr: write the QR for this reader even when another is already named. */
+	forceQr: boolean;
+	/** --no-qr: never write the QR. */
+	noQr: boolean;
+}
+
+/** Reads the command line; undefined when it does not name a reader, which is a usage error. */
+export function parseReaderArgs(flags: string[]): ReaderArgs | undefined {
+	const noQr = flags.includes("--no-qr");
+	const forceQr = flags.includes("--qr");
+	const args = flags.filter((flag) => flag !== "--no-qr" && flag !== "--qr");
+	const at = args.indexOf("--token");
+	const given = at === -1 ? undefined : args[at + 1];
+	const rest = at === -1 ? args : args.filter((_, index) => index !== at && index !== at + 1);
+	const [email, givenPath = "/writeup"] = rest;
+	// "writeup", "/writeup", and "/writeup/" are one page.
+	const path = `/${givenPath.replace(/^\/+|\/+$/g, "")}`;
+
+	if (!email?.includes("@") || (at !== -1 && !given)) return undefined;
+	return { email, path, token: given, forceQr, noQr };
+}
+
+/**
+ * The command. The config it reads and the QR it writes are the site's,
+ * found from the working directory.
+ */
+export async function main(flags: string[], cwd: string = process.cwd()): Promise<void> {
+	const parsed = parseReaderArgs(flags);
+	if (!parsed) {
+		console.error(USAGE);
+		process.exit(1);
+	}
+	const { email, path, forceQr, noQr } = parsed;
+	let site: Awaited<ReturnType<typeof loadSite>>;
+	try {
+		site = await loadSite(cwd);
+	} catch (error) {
+		console.error(`[reader] ${(error as Error).message}`);
+		process.exit(1);
+	}
+
+	const token = parsed.token ?? mintToken();
+	const reader = await sealReader(email, token);
+	console.log("Add to analytics.identify in src/site.config.ts:");
+	console.log(`  { id: "${reader.id}", sealed: "${reader.sealed}" }, // ${email.split("@")[1]}`);
+	console.log("");
+	console.log("Send this link, and only to that person. Keep it: it cannot be printed again.");
+	const link = readerLink(site.url, token, path);
+	console.log(`  ${link}`);
+
+	// The sheet's QR is the reader's link. A private artifact identifies by sign
+	// in and never by a token, so its QR stays on the bare host.
+	const named = site.analytics?.identify.length ?? 0;
+	const sheetIsFree = named === 0 || forceQr;
+	if (path === "/writeup" && !noQr && site.access === "public" && !sheetIsFree) {
+		console.log("");
+		console.log(
+			"Left public/images/qr.png alone: a reader is already named, and the sheet is theirs. Pass --qr to give the sheet to this reader.",
+		);
+	}
+	if (path === "/writeup" && !noQr && site.access === "public" && sheetIsFree) {
+		const qr = resolve(cwd, "public/images/qr.png");
+		await QRCode.toFile(qr, link, { width: 330, margin: 4, errorCorrectionLevel: "M" });
+		console.log("");
+		console.log(
+			"Wrote public/images/qr.png with that link. Print the sheet after this, never before.",
+		);
+	}
+}