@devdogsuga/backstage 0.1.0

package/dist/commands-D345F-Od.js

@@ -0,0 +1,800 @@
+import { p as isNonInteractive } from "./telemetry-Bjoz29Hl.js";
+import { a as explainError, o as unwrap, r as errorMessage, t as UsageError } from "./ui-CdKo8mLw.js";
+import { t as DONE } from "./dispatch-D048O65I.js";
+import { dirname, join, resolve } from "node:path";
+import { confirm, log, multiselect, spinner, text } from "@clack/prompts";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { render } from "@devdogsuga/brand/render";
+import { ISSUES, issueByVersion } from "@devdogsuga/newsletter";
+import { buildEml, emailImages, previewRenderContext, renderIssueDocument } from "@devdogsuga/newsletter/export";
+import { connect } from "node:tls";
+import { createElement } from "react";
+import { createServer } from "node:http";
+import { createConnection } from "node:net";
+//#region src/newsletter/imap.ts
+/**
+* One-shot IMAP APPEND: place a finished MIME message in a mailbox's Drafts
+* folder, where every Outlook — new, web, Mac, classic — offers it as an
+* editable draft. This is the whole reason for speaking IMAP at all: the
+* mailbox is the one place all the clients agree on, and APPEND is the one
+* verb this workflow needs, so a dependency-free sliver of the protocol beats
+* a client library that models the rest of it.
+*/
+const DEFAULT_HOST$1 = "outlook.office365.com";
+const TIMEOUT_MS$1 = 3e4;
+/** RFC 7628's SASL initial response: user and bearer token, ^A-delimited. */
+function xoauth2(user, accessToken) {
+	return Buffer.from(`user=${user}\x01auth=Bearer ${accessToken}\x01\x01`, "utf8").toString("base64");
+}
+/**
+* The Drafts folder's real name out of `LIST` output, for mailboxes whose
+* folders are not in English. The `\Drafts` attribute is the label Exchange
+* puts on the folder regardless of what it is called.
+*/
+function draftsFromList(lines) {
+	for (const line of lines) {
+		const match = /^\* LIST \(([^)]*)\) (?:"[^"]*"|NIL) (.+)$/.exec(line);
+		if (!match || !/\\Drafts\b/i.test(match[1])) continue;
+		const raw = match[2].trim();
+		return raw.startsWith("\"") && raw.endsWith("\"") ? raw.slice(1, -1).replace(/\\(["\\])/g, "$1") : raw;
+	}
+	return null;
+}
+/** Folder names go back out quoted, so quote-significant bytes get escaped. */
+function quoteMailbox(name) {
+	return `"${name.replace(/([\\"])/g, "\\$1")}"`;
+}
+async function appendDraft(options) {
+	const host = options.host ?? DEFAULT_HOST$1;
+	const socket = connect({
+		host,
+		port: 993,
+		servername: host
+	});
+	socket.setTimeout(TIMEOUT_MS$1);
+	let buffer = "";
+	let sequence = 0;
+	const pending = [];
+	let wake = null;
+	let failure = null;
+	socket.on("data", (chunk) => {
+		buffer += chunk.toString("utf8");
+		let index;
+		while ((index = buffer.indexOf("\r\n")) !== -1) {
+			pending.push(buffer.slice(0, index));
+			buffer = buffer.slice(index + 2);
+		}
+		wake?.();
+	});
+	const fail = (err) => {
+		failure ??= err;
+		socket.destroy();
+		wake?.();
+	};
+	socket.on("error", (err) => fail(err));
+	socket.on("timeout", () => fail(/* @__PURE__ */ new Error(`${host} stopped answering.`)));
+	socket.on("close", () => fail(/* @__PURE__ */ new Error(`${host} closed the connection.`)));
+	const nextLine = async () => {
+		for (;;) {
+			if (pending.length) return pending.shift();
+			if (failure) throw failure;
+			await new Promise((resolvePromise) => {
+				wake = resolvePromise;
+			});
+			wake = null;
+		}
+	};
+	/**
+	* Sends one command and reads to its tagged reply. A `+ ` continuation
+	* hands control back via `onContinue` — APPEND pushes the literal there,
+	* and a failed AUTHENTICATE wants a bare CRLF to surface its tagged NO.
+	*/
+	const command = async (line, onContinue) => {
+		const tag = `T${++sequence}`;
+		socket.write(`${tag} ${line}\r\n`);
+		const untagged = [];
+		for (;;) {
+			const reply = await nextLine();
+			if (reply.startsWith("+ ") || reply === "+") {
+				(onContinue ?? (() => socket.write("\r\n")))();
+				continue;
+			}
+			if (reply.startsWith(`${tag} `)) {
+				const [status = "", ...rest] = reply.slice(tag.length + 1).split(" ");
+				return {
+					status: status.toUpperCase(),
+					text: rest.join(" "),
+					untagged
+				};
+			}
+			if (reply.startsWith("* ")) untagged.push(reply);
+		}
+	};
+	try {
+		await nextLine();
+		const auth = await command(`AUTHENTICATE XOAUTH2 ${xoauth2(options.user, options.accessToken)}`);
+		if (auth.status !== "OK") throw new Error(`${options.user} was refused: ${auth.text || auth.status}. Sign in again if the stored grant has been revoked.`);
+		const literal = Buffer.from(options.message, "utf8");
+		const append = (folder) => command(`APPEND ${quoteMailbox(folder)} (\\Draft \\Seen) {${literal.length}}`, () => {
+			socket.write(literal);
+			socket.write("\r\n");
+		});
+		let placed = await append("Drafts");
+		if (placed.status !== "OK") {
+			const drafts = draftsFromList((await command("LIST \"\" \"*\"")).untagged);
+			if (drafts && drafts !== "Drafts") placed = await append(drafts);
+			if (placed.status !== "OK") throw new Error(`APPEND was refused: ${placed.text || placed.status}`);
+		}
+		await command("LOGOUT");
+	} finally {
+		socket.destroy();
+	}
+}
+//#endregion
+//#region src/newsletter/images.ts
+/**
+* The email's marks as PNG attachments.
+*
+* `@devdogsuga/newsletter` hands over each image as an SVG; a mail client
+* wants a raster. They go through `@devdogsuga/brand/render`, the same Satori
+* and resvg the rest of the club's images use, as an `<img>` of the SVG laid
+* out at the target width. That keeps one rasteriser in the toolchain and
+* keeps the marks vector until the last step: resvg draws the nested SVG at
+* the final size rather than scaling a bitmap.
+*/
+/** The SVG's aspect ratio, from its `viewBox` or else its `width` and `height`. */
+function svgAspect(svg) {
+	const root = /<svg\b[^>]*>/i.exec(svg)?.[0] ?? "";
+	const [, , boxWidth, boxHeight] = (/viewBox\s*=\s*"([^"]+)"/i.exec(root)?.[1] ?? "").trim().split(/[\s,]+/).map(Number);
+	if (boxWidth && boxHeight) return boxWidth / boxHeight;
+	const width = Number(/\bwidth\s*=\s*"([\d.]+)/i.exec(root)?.[1]);
+	const height = Number(/\bheight\s*=\s*"([\d.]+)/i.exec(root)?.[1]);
+	if (width && height) return width / height;
+	throw new Error("The SVG declares neither a viewBox nor a width and height.");
+}
+/** An SVG as PNG bytes, `width` pixels wide. */
+async function rasterize(svg, width) {
+	const height = Math.max(1, Math.round(width / svgAspect(svg)));
+	const src = `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`;
+	const { png } = await render(createElement("img", {
+		src,
+		width,
+		height,
+		style: {
+			width,
+			height
+		}
+	}), {
+		width,
+		height
+	});
+	return png;
+}
+//#endregion
+//#region src/newsletter/loopback.ts
+/**
+* A throwaway HTTP server that catches one OAuth redirect and dies.
+*
+* Entra ignores the port when matching a localhost redirect URI, so the
+* sign-in can come home to `http://localhost:{ephemeral}/` even though
+* Thunderbird registered no port. Bound to 127.0.0.1 only — the redirect
+* never leaves the machine, and nothing off it should reach the listener.
+* The `state` nonce ties the callback to this run: any other process that
+* finds the port cannot feed the flow a code it did not mint.
+*/
+/**
+* What one request to the listener means. `null` is a stray — a favicon
+* probe, a health check — and the server keeps waiting; a wrong or missing
+* state is also a stray, because rejecting the whole sign-in over a request
+* an attacker could send unauthenticated would hand them a denial of
+* service instead.
+*/
+function parseCallback(requestUrl, state) {
+	const url = new URL(requestUrl, "http://localhost");
+	if (url.pathname !== "/") return null;
+	if (url.searchParams.get("state") !== state) return null;
+	const error = url.searchParams.get("error");
+	if (error) return new Error(url.searchParams.get("error_description") ?? error);
+	const code = url.searchParams.get("code");
+	return code ? { code } : null;
+}
+const LANDING = `<!doctype html>
+<meta charset="utf-8">
+<title>DevDogs devtools</title>
+<body style="font-family: system-ui; display: grid; place-items: center; min-height: 90vh; background: #13121b; color: #f3f1f6">
+<p style="max-width: 36rem; text-align: center">%MESSAGE% You can close this tab; the rest happens in the terminal.</p>
+`;
+/** Throws when it cannot bind, which is the caller's cue to fall back. */
+function startLoopback(state) {
+	return new Promise((resolve, reject) => {
+		let settle;
+		const code = new Promise((resolveCode, rejectCode) => {
+			settle = {
+				resolve: resolveCode,
+				reject: rejectCode
+			};
+		});
+		code.catch(() => void 0);
+		const server = createServer((request, response) => {
+			const result = parseCallback(request.url ?? "/", state);
+			if (result === null) {
+				response.writeHead(404).end();
+				return;
+			}
+			const failed = result instanceof Error;
+			response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(LANDING.replace("%MESSAGE%", failed ? "The sign-in did not go through." : "Signed in."));
+			if (failed) settle.reject(result);
+			else settle.resolve(result.code);
+		});
+		server.on("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			if (!address || typeof address === "string") {
+				server.close();
+				reject(/* @__PURE__ */ new Error("The loopback server bound without a port."));
+				return;
+			}
+			resolve({
+				port: address.port,
+				code,
+				close: () => server.close()
+			});
+		});
+	});
+}
+/**
+* Best effort only: the URL is always printed too, so a machine with no
+* opener — SSH, a container, a WSL distro without wslview — costs one click
+* on the printed line instead of a failure.
+*/
+function openInBrowser(url) {
+	const [command, args] = process.platform === "win32" ? ["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+	try {
+		spawn(command, args, {
+			stdio: "ignore",
+			detached: true
+		}).on("error", () => void 0).unref();
+	} catch {}
+}
+//#endregion
+//#region src/newsletter/oauth.ts
+/**
+* Sign-in for the club mailbox, borrowing Thunderbird's app registration.
+*
+* UGA's tenant blocks user consent for every Microsoft Graph mail scope (the
+* Microsoft-managed default policy), so the clean path — a Graph-created
+* draft — needs an EITS-approved app registration. The same policy, though,
+* allowlists a handful of mail clients by application ID for the legacy
+* IMAP/SMTP scopes, Thunderbird among them. This module runs the standard
+* authorization-code flow as that client: the officer signs in as the mailbox
+* in a browser, and the refresh token is theirs — the same grant Thunderbird
+* itself would hold. Presenting another client's ID is a documented
+* convention in open-source mail tooling (mbsync, OfflineIMAP, DavMail), but
+* it is Microsoft's allowlist, and this stops working the day they prune it.
+*
+* The redirect comes back two ways. Entra ignores the port when matching a
+* localhost redirect URI, so the ordinary path is `loopback.ts`: a throwaway
+* server on an ephemeral port that catches the code itself. When that server
+* cannot bind, the flow falls back to Thunderbird's registered
+* `https://localhost` — a dead page whose address bar holds the code, pasted
+* back by hand.
+*
+* No PKCE and no client secret: Thunderbird is registered as a public client,
+* and the code exchange happens entirely on this machine.
+*/
+/**
+* Thunderbird's public client ID, BORROWED: the club has no app registration
+* of its own. If Microsoft or UGA's tenant stops allowing it, drafting and
+* sending need a club-owned registration (an EITS request), and this constant
+* and the redirect below change with it.
+*/
+const CLIENT_ID = "9e5f94bc-e8a4-4e73-b8be-63364c29d753";
+/** The fallback redirect when no loopback server could bind. */
+const PASTE_REDIRECT_URI = "https://localhost";
+const SCOPE = "https://outlook.office365.com/IMAP.AccessAsUser.All https://outlook.office365.com/SMTP.Send offline_access";
+const AUTHORITY = "https://login.microsoftonline.com/organizations/oauth2/v2.0";
+function authorizeUrl(mailbox, redirectUri, state) {
+	const query = new URLSearchParams({
+		client_id: CLIENT_ID,
+		response_type: "code",
+		redirect_uri: redirectUri,
+		scope: SCOPE,
+		login_hint: mailbox,
+		...state ? { state } : {}
+	});
+	return `${AUTHORITY}/authorize?${query.toString()}`;
+}
+/**
+* The code out of whatever the officer pastes: the whole `https://localhost/?
+* code=…` address (the intended gesture — the browser shows a dead page and
+* they copy its location) or the bare code itself.
+*/
+function codeFromRedirect(pasted) {
+	const input = pasted.trim();
+	const error = /[?&#]error=([^&\s]+)/.exec(input);
+	if (error) {
+		const description = /[?&#]error_description=([^&\s]+)/.exec(input);
+		return new Error(description ? decodeURIComponent(description[1].replace(/\+/g, " ")) : decodeURIComponent(error[1]));
+	}
+	const inUrl = /[?&#]code=([^&\s]+)/.exec(input);
+	if (inUrl) return decodeURIComponent(inUrl[1]);
+	if (input && !/[\s/?&=]/.test(input)) return input;
+	return /* @__PURE__ */ new Error("That has no ?code= in it. Paste the whole address bar of the localhost page.");
+}
+async function tokenRequest(grant) {
+	const response = await fetch(`${AUTHORITY}/token`, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			client_id: CLIENT_ID,
+			scope: SCOPE,
+			...grant
+		})
+	});
+	const body = await response.json();
+	if (!response.ok || !body.access_token || !body.refresh_token) throw new Error(body.error_description ?? body.error ?? `Token endpoint answered ${response.status}.`);
+	return {
+		accessToken: body.access_token,
+		refreshToken: body.refresh_token
+	};
+}
+function redeemCode(code, redirectUri) {
+	return tokenRequest({
+		grant_type: "authorization_code",
+		code,
+		redirect_uri: redirectUri
+	});
+}
+function refreshTokens(refreshToken) {
+	return tokenRequest({
+		grant_type: "refresh_token",
+		refresh_token: refreshToken
+	});
+}
+/**
+* Outside the repo on purpose: the refresh token opens the club mailbox, and
+* nothing that opens the club mailbox belongs anywhere `git add` can reach.
+*/
+function grantPath() {
+	const xdg = process.env.XDG_CONFIG_HOME;
+	const configHome = xdg === void 0 || xdg === "" ? join(homedir(), ".config") : xdg;
+	return join(configHome, "devdogsuga", "newsletter-mailbox.json");
+}
+async function readGrant() {
+	try {
+		const parsed = JSON.parse(await readFile(grantPath(), "utf8"));
+		return typeof parsed.mailbox === "string" && typeof parsed.refreshToken === "string" ? {
+			mailbox: parsed.mailbox,
+			refreshToken: parsed.refreshToken
+		} : null;
+	} catch {
+		return null;
+	}
+}
+async function writeGrant(grant) {
+	const path = grantPath();
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(grant, null, 2)}\n`, { mode: 384 });
+	await chmod(path, 384);
+}
+//#endregion
+//#region src/newsletter/smtp.ts
+/**
+* One-shot SMTP submission: send a finished MIME message byte-for-byte.
+*
+* This exists because a draft cannot survive being sent from Outlook. The
+* web Outlook composer is a rich-text editor with a style whitelist, and
+* sending a pushed draft re-serializes whatever that editor kept: forensics
+* on a received copy showed the head `<style>` replaced with Outlook's own,
+* every `background-image` and `bgcolor` gone, and most class attributes
+* dropped — all of the newsletter's dark-mode defenses, stripped in transit.
+* (Classic Outlook mangles differently, into Word HTML, but just as surely.)
+* Submitting over SMTP bypasses every composer: recipients get the authored
+* document, stylesheet and all. Like `imap.ts`, this speaks just the sliver
+* of the protocol the workflow needs — EHLO, STARTTLS, AUTH, one message.
+*/
+const DEFAULT_HOST = "smtp.office365.com";
+const TIMEOUT_MS = 3e4;
+/**
+* The name recipients see beside the club address. Without one, clients fall
+* back to the bare address, and Outlook shows it as the tenant stores it:
+* "devdogs@UGA.EDU".
+*/
+const SENDER_NAME = "DevDogs";
+/**
+* An RFC 5322 mailbox with a display name. Quoted so any punctuation is safe;
+* a name outside ASCII travels as an RFC 2047 encoded word, which is never
+* quoted.
+*/
+function namedMailbox(name, address) {
+	return `${/^[\x20-\x7e]*$/.test(name) ? `"${name.replace(/(["\\])/g, "\\$1")}"` : `=?UTF-8?B?${Buffer.from(name, "utf8").toString("base64")}?=`} <${address}>`;
+}
+/**
+* RFC 5322 origination headers for a message built as a draft. `buildEml`
+* deliberately emits none of these — draft-ness is their absence — so the
+* send path prepends them. The submission server stamps `Message-ID`.
+*/
+function originationHeaders(from, to, date = /* @__PURE__ */ new Date(), fromName = SENDER_NAME) {
+	return [
+		`From: ${namedMailbox(fromName, from)}`,
+		`To: ${to.map((address) => `<${address}>`).join(", ")}`,
+		`Date: ${date.toUTCString().replace(/GMT$/, "+0000")}`,
+		""
+	].join("\r\n");
+}
+/** RFC 5321 §4.5.2 transparency: a line-leading `.` doubles inside DATA. */
+function dotStuff(message) {
+	return message.replace(/(^|\r\n)\./g, "$1..");
+}
+/**
+* `true` when an SMTP reply line ends its reply: `250 done` rather than the
+* `250-more coming` continuation form (RFC 5321 §4.2.1).
+*/
+function endsReply(line) {
+	return /^\d{3}(?: |$)/.test(line);
+}
+async function submitMessage(options) {
+	const host = options.host ?? DEFAULT_HOST;
+	if (!options.recipients.length) throw new Error("No recipients.");
+	let buffer = "";
+	const pending = [];
+	let wake = null;
+	let failure = null;
+	const fail = (err) => {
+		failure ??= err;
+		socket.destroy();
+		wake?.();
+	};
+	/** (Re)binds the line reader — once to the TCP socket, again after TLS. */
+	const adopt = (next) => {
+		next.setTimeout(TIMEOUT_MS);
+		next.on("data", (chunk) => {
+			buffer += chunk.toString("utf8");
+			let index;
+			while ((index = buffer.indexOf("\r\n")) !== -1) {
+				pending.push(buffer.slice(0, index));
+				buffer = buffer.slice(index + 2);
+			}
+			wake?.();
+		});
+		next.on("error", (err) => fail(err));
+		next.on("timeout", () => fail(/* @__PURE__ */ new Error(`${host} stopped answering.`)));
+		next.on("close", () => fail(/* @__PURE__ */ new Error(`${host} closed the connection.`)));
+		return next;
+	};
+	let socket = adopt(createConnection({
+		host,
+		port: 587
+	}));
+	const nextLine = async () => {
+		for (;;) {
+			if (pending.length) return pending.shift();
+			if (failure) throw failure;
+			await new Promise((resolvePromise) => {
+				wake = resolvePromise;
+			});
+			wake = null;
+		}
+	};
+	/** Reads one full reply; throws unless its code is in `expect`. */
+	const reply = async (expect, doing) => {
+		let line;
+		do
+			line = await nextLine();
+		while (!endsReply(line));
+		const code = Number(line.slice(0, 3));
+		if (!expect.includes(code)) throw new Error(`${doing}: ${line}`);
+		return line;
+	};
+	const command = (line, expect, doing) => {
+		socket.write(`${line}\r\n`);
+		return reply(expect, doing);
+	};
+	try {
+		await reply([220], `${host} refused the connection`);
+		await command(`EHLO [127.0.0.1]`, [250], "EHLO was refused");
+		await command("STARTTLS", [220], "STARTTLS was refused");
+		for (const event of [
+			"data",
+			"timeout",
+			"close"
+		]) socket.removeAllListeners(event);
+		socket.setTimeout(0);
+		socket = adopt(connect({
+			socket,
+			servername: host
+		}));
+		await command(`EHLO [127.0.0.1]`, [250], "EHLO after STARTTLS was refused");
+		await command(`AUTH XOAUTH2 ${xoauth2(options.user, options.accessToken)}`, [235], `${options.user} was refused. Sign in again if the stored grant lacks SMTP.Send — grants from before --send existed only asked for IMAP`);
+		await command(`MAIL FROM:<${options.from}>`, [250], `The sender ${options.from} was refused`);
+		for (const recipient of options.recipients) await command(`RCPT TO:<${recipient}>`, [250, 251], `The recipient ${recipient} was refused`);
+		await command("DATA", [354], "DATA was refused");
+		const body = dotStuff(options.message);
+		socket.write(body.endsWith("\r\n") ? body : `${body}\r\n`);
+		await command(".", [250], "The message was refused");
+		socket.write("QUIT\r\n");
+	} finally {
+		socket.destroy();
+	}
+}
+//#endregion
+//#region src/newsletter/commands.ts
+/**
+* `pnpm backstage newsletter render|draft|send <issue…>`
+*
+* The DevDogs Changelog, from the issues published in `@devdogsuga/newsletter`:
+*
+*   * `render`: writes `.eml` and `.html` files and touches nothing else.
+*   * `draft`: appends each issue to the Drafts folder of the club mailbox
+*     over IMAP, for review in any Outlook.
+*   * `send`: submits each issue over SMTP, byte for byte as authored, to the
+*     recipients named with `--to`. There is no default audience, and every
+*     send asks first, naming the issue and the full recipient list.
+*
+* Drafts and sends always use the club mailbox. Sending goes through SMTP and
+* not Outlook because Outlook's composers rewrite the HTML: they strip the
+* styles, classes and `bgcolor` attributes the dark-mode defences rely on.
+*
+* Credentials: none stored for you to manage. The first `draft` or `send`
+* opens a browser to sign in as the club mailbox (see `oauth.ts`); the
+* refresh token is cached outside any repository, so later runs, including
+* non-interactive ones, reuse it. No env file and no checkout.
+*/
+/** The account every draft and send goes through. There is no override. */
+const CLUB_MAILBOX = "devdogs@uga.edu";
+const NEWSLETTER_FORMATS = ["eml", "html"];
+const SUBCOMMANDS = [
+	"render",
+	"draft",
+	"send"
+];
+function expandHome(value) {
+	return value === "~" || value.startsWith("~/") ? resolve(homedir(), value.slice(2)) : value;
+}
+function commaList(value) {
+	return (value ?? "").split(",").map((part) => part.trim()).filter(Boolean);
+}
+/** Reads one subcommand's arguments, or throws a {@link UsageError} saying what is wrong. */
+function parseNewsletterArgs(argv, cwd) {
+	const [subcommand, ...rest] = argv;
+	if (!subcommand || !SUBCOMMANDS.includes(subcommand)) throw new UsageError(subcommand ? `Unknown newsletter command "${subcommand}". Try ${SUBCOMMANDS.join(", ")}.` : `Name what to do: ${SUBCOMMANDS.join(", ")}.`);
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: rest,
+			options: {
+				format: { type: "string" },
+				out: { type: "string" },
+				to: { type: "string" },
+				yes: { type: "boolean" },
+				"dry-run": { type: "boolean" }
+			},
+			allowPositionals: true
+		});
+	} catch (err) {
+		throw new UsageError(`${errorMessage(err)} (There is no --mailbox: the club mailbox is always used.)`);
+	}
+	const { values } = parsed;
+	const wrongSubcommand = (flag, belongsTo) => {
+		if (values[flag] !== void 0 && subcommand !== belongsTo) throw new UsageError(`--${flag} belongs to \`newsletter ${belongsTo}\`.`);
+	};
+	wrongSubcommand("format", "render");
+	wrongSubcommand("out", "render");
+	wrongSubcommand("to", "send");
+	const to = commaList(values.to);
+	if (subcommand === "send") {
+		if (!to.length) throw new UsageError("`newsletter send` needs --to, a comma-separated list of addresses.");
+		const notAddresses = to.filter((value) => !value.includes("@"));
+		if (notAddresses.length) throw new UsageError(`--to takes email addresses, not ${notAddresses.join(", ")}.`);
+	}
+	const formats = commaList(values.format ?? "eml,html");
+	const bad = formats.filter((value) => !NEWSLETTER_FORMATS.includes(value));
+	if (bad.length) throw new UsageError(`Unknown format ${bad.join(", ")}. Try eml or html.`);
+	return {
+		subcommand,
+		versions: parsed.positionals,
+		formats: [...new Set(formats)],
+		out: resolve(cwd, expandHome(values.out ?? "changelog-exports")),
+		to,
+		yes: values.yes === true
+	};
+}
+function destination(out, version, format) {
+	return resolve(out, `changelog-v${version}.${format}`);
+}
+/** The confirmation text for a send: the issues and every recipient. */
+function sendSummary(versions, to) {
+	return `Send ${versions.map((version) => `v${version}`).join(", ")} from ${CLUB_MAILBOX} to ${to.length} recipient${to.length === 1 ? "" : "s"}: ${to.join(", ")}?`;
+}
+/**
+* Asks before a send, every time. `--yes` answers it; with no terminal it is
+* the only way through, so an unattended run cannot send by accident.
+*/
+async function confirmSend(options, versions) {
+	if (options.yes) return true;
+	if (isNonInteractive()) throw new UsageError(`${sendSummary(versions, options.to)} No terminal to ask. Pass --yes to send.`);
+	return unwrap(await confirm({
+		message: sendSummary(versions, options.to),
+		initialValue: false
+	}));
+}
+async function pickIssues() {
+	if (isNonInteractive()) throw new UsageError("No terminal to choose issues. Name one, or pass * for all.");
+	return unwrap(await multiselect({
+		message: "Which issues?",
+		options: ISSUES.map((issue) => ({
+			value: issue.version,
+			label: `v${issue.version}`,
+			hint: issue.tagline
+		})),
+		initialValues: [ISSUES[ISSUES.length - 1]?.version ?? ""].filter(Boolean),
+		required: true
+	}));
+}
+/**
+* The browser sign-in, redirect caught by a loopback server: open the URL,
+* wait for the code to knock, exchange it. Five minutes is the patience —
+* authorization codes do not live much longer anyway.
+*/
+async function signInViaLoopback(server, state) {
+	const redirectUri = `http://localhost:${server.port}/`;
+	const url = authorizeUrl(CLUB_MAILBOX, redirectUri, state);
+	log.step(`Sign in as ${CLUB_MAILBOX} in the browser window that just opened:`);
+	log.message(url);
+	openInBrowser(url);
+	const wait = spinner();
+	wait.start("Waiting for the sign-in to come back");
+	try {
+		const timeout = new Promise((_, rejectLate) => {
+			setTimeout(() => rejectLate(/* @__PURE__ */ new Error("Five minutes passed with no sign-in. Run it again.")), 3e5).unref();
+		});
+		const code = await Promise.race([server.code, timeout]);
+		wait.stop("The sign-in came back.");
+		return await redeemCode(code, redirectUri);
+	} catch (err) {
+		wait.stop("No sign-in.");
+		throw err;
+	} finally {
+		server.close();
+	}
+}
+/** The pasted fallback for a machine where no local port would bind. */
+async function signInViaPaste() {
+	log.step(`Open this and sign in as ${CLUB_MAILBOX}:`);
+	log.message(authorizeUrl(CLUB_MAILBOX, PASTE_REDIRECT_URI));
+	const code = codeFromRedirect(unwrap(await text({
+		message: "The browser will land on a dead localhost page. Paste its full address:",
+		validate: (value) => {
+			const code = codeFromRedirect(value ?? "");
+			return code instanceof Error ? code.message : void 0;
+		}
+	})));
+	if (code instanceof Error) throw code;
+	return redeemCode(code, PASTE_REDIRECT_URI);
+}
+/**
+* An access token for the club mailbox: the stored grant refreshed when there
+* is one, a browser sign-in when there is not.
+*/
+async function mailboxAccessToken() {
+	const stored = await readGrant();
+	if (stored?.mailbox === "devdogs@uga.edu") try {
+		const tokens = await refreshTokens(stored.refreshToken);
+		await writeGrant({
+			mailbox: CLUB_MAILBOX,
+			refreshToken: tokens.refreshToken
+		});
+		return tokens.accessToken;
+	} catch (err) {
+		log.warn(`The stored sign-in was refused (${errorMessage(err)}).`);
+	}
+	if (isNonInteractive()) throw new UsageError(`No terminal to sign in as ${CLUB_MAILBOX}. Run \`pnpm backstage newsletter draft <issue>\` interactively once; after that this works anywhere.`);
+	const state = randomBytes(16).toString("hex");
+	const server = await startLoopback(state).catch(() => null);
+	const tokens = server ? await signInViaLoopback(server, state) : await signInViaPaste();
+	await writeGrant({
+		mailbox: CLUB_MAILBOX,
+		refreshToken: tokens.refreshToken
+	});
+	log.info(`Signed in. The grant lives in ${grantPath()} — mode 600, keep it that way.`);
+	return tokens.accessToken;
+}
+/** The email's marks, rasterised once: they are the same in every issue. */
+async function attachments() {
+	return Promise.all(emailImages().map(async (image) => ({
+		cid: image.cid,
+		filename: image.filename,
+		contentType: "image/png",
+		base64: (await rasterize(image.svg, image.rasterWidth)).toString("base64")
+	})));
+}
+async function runNewsletter(argv) {
+	try {
+		await newsletter(parseNewsletterArgs(argv, process.cwd()));
+	} catch (err) {
+		explainError("Could not do that.", err, [
+			"pnpm backstage newsletter render '*' --out ~/changelog",
+			"pnpm backstage newsletter draft 3.0.1",
+			"pnpm backstage newsletter send 3.0.1 --to a@uga.edu,b@uga.edu"
+		]);
+		process.exitCode = 1;
+	}
+}
+async function newsletter(parsed) {
+	const unknown = parsed.versions.filter((version) => version !== "*" && !issueByVersion(version));
+	if (unknown.length) throw new UsageError(`No issue called ${unknown.join(", ")}. Try ${ISSUES.map((issue) => issue.version).join(", ")}, or *.`);
+	const chosen = parsed.versions.length ? parsed.versions : await pickIssues();
+	const versions = chosen.includes("*") ? ISSUES.map((issue) => issue.version) : [...new Set(chosen)];
+	if (parsed.subcommand === "render") {
+		const images = parsed.formats.includes("eml") ? await attachments() : [];
+		const written = [];
+		for (const version of versions) {
+			const issue = issueByVersion(version);
+			for (const format of parsed.formats) {
+				const file = destination(parsed.out, version, format);
+				await mkdir(dirname(file), { recursive: true });
+				await writeFile(file, format === "eml" ? buildEml({
+					subject: issue.title,
+					html: renderIssueDocument(issue),
+					images
+				}) : renderIssueDocument(issue, previewRenderContext()));
+				written.push(file);
+			}
+		}
+		for (const file of written) log.success(file);
+		log.info(`${written.length} file${written.length === 1 ? "" : "s"} written. An .eml opens in classic Outlook for review; send with \`newsletter send\`.`);
+		return;
+	}
+	if (parsed.subcommand === "send" && !await confirmSend(parsed, versions)) {
+		log.info("Nothing sent.");
+		return;
+	}
+	const images = await attachments();
+	const message = (version) => {
+		const issue = issueByVersion(version);
+		return buildEml({
+			subject: issue.title,
+			html: renderIssueDocument(issue),
+			images,
+			unsent: false
+		});
+	};
+	const accessToken = await mailboxAccessToken();
+	if (parsed.subcommand === "draft") {
+		for (const version of versions) {
+			await appendDraft({
+				user: CLUB_MAILBOX,
+				accessToken,
+				message: message(version)
+			});
+			log.success(`v${version} → Drafts of ${CLUB_MAILBOX}`);
+		}
+		log.info("Open any Outlook as the club account to review, but send with `newsletter send`, not from Outlook: its composers rewrite the HTML.");
+		return;
+	}
+	for (const version of versions) {
+		await submitMessage({
+			user: CLUB_MAILBOX,
+			accessToken,
+			from: CLUB_MAILBOX,
+			recipients: parsed.to,
+			message: originationHeaders(CLUB_MAILBOX, parsed.to) + message(version)
+		});
+		log.success(`v${version} → sent to ${parsed.to.join(", ")}`);
+	}
+}
+const handleNewsletter = async (rest) => {
+	await runNewsletter(rest);
+	return process.exitCode ? null : DONE;
+};
+//#endregion
+export { handleNewsletter };