@devdogsuga/devtools 0.1.0 → 0.1.2

package/dist/setup.js

@@ -1,30 +1,53 @@
 /**
  * One-command onboarding, the first thing a new contributor runs.
  *
- * Checks prerequisites (warns, never hard-fails on optional tools), seeds the
- * root `.env`, and points at the database and OAuth steps. Deliberately does NOT run remote
- * Supabase commands: linking a remote project needs credentials that are not
- * in `.env` yet.
+ * Hosted Supabase (a student's own free-tier project) is the DEFAULT path:
+ * pick app(s) -> hosted or local -> prerequisite checks -> for hosted, a
+ * short wizard collects the project's URL and keys, validates the DB_URL,
+ * writes `.env`, runs the migrations, and chains straight into `devtools
+ * oauth` against that same project. Local keeps today's `db start` flow
+ * unchanged.
  *
  * Was `scripts/setup.ts` at the repo root, resolving paths from
  * `process.cwd()`, so it only worked when invoked from the root. Same class of
  * bug that made the Supabase CLI look for `supabase_db_platform`. It resolves
  * from `findRepoRoot()` now and works from anywhere.
  */
-import { execSync } from "node:child_process";
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join } from "node:path";
-import { log, note } from "@clack/prompts";
+import { confirm, log, note, password, select, spinner, text } from "@clack/prompts";
 import { loadRegistry } from "./env/discovery.js";
 import { renderInit, resolveSections } from "./env/example.js";
 import { discoverRepoRoot } from "./repo/root.js";
-function has(cmd) {
+import { EnvDocument } from "./env/document.js";
+import { dbPush } from "./db/run.js";
+import { validateSessionPoolerUrl } from "./db/pooler.js";
+import { runOAuthSetup } from "./oauth/wizard.js";
+import { runEnvironmentDoctor } from "./environment-doctor.js";
+import { unwrap } from "./ui.js";
+function has(cmd, args = ["--version"]) {
     try {
-        execSync(cmd, { stdio: ["ignore", "pipe", "ignore"] });
-        return true;
+        return execFileSync(cmd, args, {
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf8",
+        }).trim();
     }
     catch {
-        return false;
+        return null;
+    }
+}
+/** Reads `packageManager` out of a checkout's root `package.json`, when one
+ * is reachable — for the "does the installed pnpm match the pin" line. */
+function readPnpmPin(repoRoot) {
+    if (!repoRoot)
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"));
+        return pkg.packageManager?.replace(/^pnpm@/, "").split("+")[0] ?? null;
+    }
+    catch {
+        return null;
     }
 }
 export async function runSetup() {
@@ -42,13 +65,22 @@ export async function runSetup() {
     checks.push(major > 22 || (major === 22 && minor >= 12)
         ? `OK    Node ${node}`
         : `WARN  Node ${node} — this repo needs >= 22.12 for pnpm 11 (see .nvmrc)`);
-    checks.push(has("corepack --version")
-        ? "OK    corepack available"
-        : "WARN  corepack not found — run `corepack enable` for the pinned pnpm");
-    checks.push(has("docker info")
-        ? "OK    Docker running (local Supabase stack available)"
-        : "INFO  Docker not running — fine against a hosted project, needed to run Supabase on this machine");
-    checks.push(has("flutter --version")
+    // Never corepack — this repo does not use it. Node via fnm, then `npm
+    // install -g pnpm`; pnpm self-switches to the pinned version on its first
+    // run here (pmOnFail=download).
+    const pnpmVersion = has("pnpm");
+    const repoRootForPin = discoverRepoRoot();
+    const pin = readPnpmPin(repoRootForPin);
+    if (!pnpmVersion) {
+        checks.push("WARN  pnpm not found — run `npm install -g pnpm` (never `corepack enable`)");
+    }
+    else if (pin && pnpmVersion !== pin) {
+        checks.push(`WARN  pnpm ${pnpmVersion} — this repo is pinned to ${pin}; any pnpm command here self-switches`);
+    }
+    else {
+        checks.push(`OK    pnpm ${pnpmVersion}`);
+    }
+    checks.push(has("flutter", ["--version"])
         ? "OK    Flutter installed (study-group-finder buildable)"
         : "INFO  Flutter not installed — only needed for apps/study-group-finder");
     // ── No repo yet? ───────────────────────────────────────────────────────────
@@ -65,39 +97,23 @@ export async function runSetup() {
         note([
             "No DevDogsUGA checkout found in this directory or its parents.",
             "",
-            "1. git clone https://github.com/devdogsuga/DevDogsUGA.git",
+            "1. git clone https://github.com/DevDogsUGA/DevDogsUGA.git",
             "2. cd DevDogsUGA && pnpm install",
             "3. pnpm devtools setup   — run again from inside the clone to seed .env",
         ].join("\n"), "Next steps");
         return;
     }
+    note(checks.join("\n"), "Prerequisites");
     // ── Env ────────────────────────────────────────────────────────────────────
-    // Seeded from the SAME renderer as `env init` and the generated
-    // .env.example, rather than by copying the example file: a copy would carry
-    // the example's "GENERATED ... Do not edit this file" header into the one
-    // file that is meant to be edited. Like init, an existing file is untouched.
     const env = join(repoRoot, ".env");
-    let seededEnv = false;
-    // The apps the picker chose, so "Next steps" boots what this contributor is
-    // actually here for rather than a hardcoded default. Null when the .env
-    // already existed (no picker ran) — the generic `pnpm dev` picker covers it.
     let chosenApps = null;
     if (existsSync(env)) {
-        checks.push("OK    .env already exists (left untouched)");
+        log.info("OK    .env already exists (left untouched)");
     }
     else {
         await loadRegistry();
-        // The project picker: a contributor's .env carries the sections for the
-        // projects they picked (plus the shared Supabase stack), not all six.
-        // The operator tooling is offered as a ROLE in the same picker, off by
-        // default: no app reads those keys, and every command that needs one
-        // refuses by name with the recovery step. Re-running `env init` later
-        // APPENDS the sections for a new project without touching filled values.
         const sections = await resolveSections();
         if (sections) {
-            // Lead with the two projects most contributors join; platform is shared
-            // auth infrastructure you depend on but rarely edit, and sandbox is
-            // dormant, trailing last as the one almost nobody touches.
             const order = [
                 "schedule-builder",
                 "study-group-finder",
@@ -107,17 +123,40 @@ export async function runSetup() {
             chosenApps = order.filter((app) => sections.has(app));
         }
         writeFileSync(env, renderInit("development", new Date().toISOString().slice(0, 10), sections), { flag: "wx" });
-        checks.push("OK    created .env (same as `pnpm devtools env init`)");
-        seededEnv = true;
-    }
-    note(checks.join("\n"), "Prerequisites");
-    if (seededEnv) {
+        log.success("Created .env (same as `pnpm devtools env init`)");
         log.info(".env starts blank. Supabase on this machine fills the connection block " +
             "for you; only a hosted project needs values typed in.");
     }
-    // Boot what the contributor picked. study-group-finder still goes through
-    // the same `pnpm dev --filter` picker path (pnpm runs its `flutter run`
-    // task), so the shape is uniform; the SDK note is the only difference.
+    // ── Local or hosted? ────────────────────────────────────────────────────────
+    const target = unwrap(await select({
+        message: "Which Supabase should this checkout use?",
+        options: [
+            {
+                value: "hosted",
+                label: "Hosted (your own free-tier project)",
+                hint: "recommended — set one up at supabase.com in a couple of minutes",
+            },
+            {
+                value: "local",
+                label: "Local (Docker)",
+                hint: "needs Docker Desktop, OrbStack, or Docker Engine in WSL2",
+            },
+        ],
+        initialValue: "hosted",
+    }));
+    if (target === "hosted") {
+        await runHostedWizard(repoRoot);
+        // A read-only check of what just happened.
+        await runEnvironmentDoctor({ app: chosenApps?.[0] });
+    }
+    else {
+        // .env stays blank until `db start`, so checking now would only report
+        // the expected gap. Point at doctor instead.
+        printLocalNextSteps(chosenApps);
+        log.info("After `pnpm devtools db start`, run `pnpm devtools doctor` to check your setup.");
+    }
+}
+function printLocalNextSteps(chosenApps) {
     const startSteps = chosenApps && chosenApps.length > 0
         ? chosenApps.map((app) => app === "study-group-finder"
             ? `     pnpm dev --filter study-group-finder   (Flutter — needs the SDK)`
@@ -143,10 +182,99 @@ export async function runSetup() {
                 "     pnpm devtools workflows run --app schedule-builder --tier development",
             ]
             : []),
-        "",
-        "Working against a hosted Supabase project instead? Fill in .env",
-        "(dashboard → Project Settings), then:",
-        "  pnpm devtools db connect <project-ref>",
-        "  pnpm devtools db types",
     ].join("\n"), "Next steps");
 }
+/**
+ * The hosted onboarding wizard: create a project on supabase.com by hand
+ * (this only asks for what comes out of it), then API URL, publishable key,
+ * secret key, and the Session pooler DB_URL — validated before anything is
+ * written. Non-clobbering: an already-filled key is left alone unless the
+ * contributor confirms overwriting it.
+ */
+async function runHostedWizard(repoRoot) {
+    note([
+        "1. Create a free project at https://supabase.com/dashboard",
+        "2. Project Settings → API: copy the Project URL, the publishable key,",
+        "   and the secret key.",
+        "3. Project Settings → Database → Connection string → Session pooler:",
+        "   copy that string (port 5432, not 6543).",
+    ].join("\n"), "Create a hosted Supabase project");
+    const envPath = join(repoRoot, ".env");
+    const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+    const doc = EnvDocument.parse(existing);
+    const apiUrl = await promptEnvValue(doc, "API_URL", "Project URL", "https://<ref>.supabase.co");
+    const publishableKey = await promptEnvValue(doc, "PUBLISHABLE_KEY", "Publishable key", "sb_publishable_...");
+    const secretKey = await promptSecretValue(doc, "SECRET_KEY", "Secret key");
+    let dbUrl;
+    for (;;) {
+        const candidate = await promptSecretValue(doc, "DB_URL", "Session pooler DB_URL");
+        const validation = validateSessionPoolerUrl(candidate);
+        if (validation.ok) {
+            dbUrl = candidate;
+            break;
+        }
+        log.error(validation.message ?? "That DB_URL is not usable.");
+        if (validation.faqId) {
+            log.info(`https://devdogsuga.org/docs/platform/getting-started/troubleshooting#${validation.faqId}`);
+        }
+        doc.set("DB_URL", ""); // clear so the next loop iteration re-prompts
+    }
+    doc.set("API_URL", apiUrl);
+    doc.set("PUBLISHABLE_KEY", publishableKey);
+    doc.set("SECRET_KEY", secretKey);
+    doc.set("DB_URL", dbUrl);
+    writeFileSync(envPath, doc.toString());
+    log.success("Wrote .env");
+    const s = spinner();
+    s.start("Running migrations against your project");
+    const code = await dbPush(dbUrl, { yes: true });
+    if (code === 0) {
+        s.stop("Migrations applied");
+    }
+    else {
+        s.stop("Migrations failed — see the Supabase CLI output above");
+        log.warn("Fix the problem above, then re-run `pnpm devtools setup` (your .env answers are kept), or run `pnpm devtools db migrate` and `pnpm devtools oauth` yourself.");
+        process.exitCode = 1;
+        return;
+    }
+    log.info('Now configuring "Sign in with DevDogs" against the same project.');
+    const hostedTarget = {
+        kind: "hosted",
+        apiUrl,
+        serviceRoleKey: secretKey,
+    };
+    await runOAuthSetup(undefined, undefined, undefined, hostedTarget);
+    // runOAuthSetup already printed the dashboard redirect-URL step.
+    note("pnpm dev --filter <your app>", "Then run your app");
+}
+async function promptEnvValue(doc, key, label, placeholder) {
+    const current = doc.get(key);
+    if (current) {
+        const overwrite = unwrap(await confirm({
+            message: `${label} is already set in .env. Overwrite it?`,
+            initialValue: false,
+        }));
+        if (!overwrite)
+            return current;
+    }
+    return unwrap(await text({
+        message: label,
+        placeholder,
+        validate: (v) => (v?.trim() ? undefined : "Required"),
+    })).trim();
+}
+async function promptSecretValue(doc, key, label) {
+    const current = doc.get(key);
+    if (current) {
+        const overwrite = unwrap(await confirm({
+            message: `${label} is already set in .env. Overwrite it?`,
+            initialValue: false,
+        }));
+        if (!overwrite)
+            return current;
+    }
+    return unwrap(await password({
+        message: label,
+        validate: (v) => (v?.trim() ? undefined : "Required"),
+    })).trim();
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@devdogsuga/devtools",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "Contributor CLI for a DevDogsUGA checkout: database, env, images, emails, cron, deploy. Ships built JS; run via `pnpm dlx @devdogsuga/devtools` (or the `devtools`/`devtools-ci` bins once installed) from inside a DevDogsUGA clone.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/devdogsuga/Backstage.git",
+    "url": "https://github.com/DevDogsUGA/Backstage.git",
     "directory": "packages/devtools"
   },
   "publishConfig": {
@@ -38,7 +38,7 @@
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "zod": "4.4.3",
-    "@devdogsuga/telemetry": "0.1.0"
+    "@devdogsuga/telemetry": "0.1.1"
   },
   "peerDependencies": {
     "@devdogsuga/brand": "*",
@@ -62,9 +62,9 @@
     "@vitest/coverage-v8": "^4.1.11",
     "react": "^19.2.8",
     "vitest": "^4.1.11",
-    "@devdogsuga/brand": "0.1.0",
-    "@devdogsuga/db": "0.1.0",
-    "@devdogsuga/config": "0.1.0",
+    "@devdogsuga/config": "0.1.1",
+    "@devdogsuga/db": "0.1.1",
+    "@devdogsuga/brand": "0.1.1",
     "@devdogsuga/env": "0.1.0"
   },
   "scripts": {

package/dist/newsletter/commands.d.ts

@@ -1,16 +0,0 @@
-export type NewsletterFormat = "eml" | "html";
-export declare const NEWSLETTER_FORMATS: readonly ["eml", "html"];
-export interface NewsletterOptions {
-    versions: string[];
-    formats: NewsletterFormat[];
-    out: string;
-    /** Append each issue as a draft in the club mailbox. */
-    push: boolean;
-    /** Send each issue over SMTP, to `to`, byte-for-byte as authored. */
-    send: boolean;
-    to: string[];
-    mailbox: string;
-}
-export declare function parseNewsletterArgs(argv: readonly string[], cwd: string): NewsletterOptions | Error;
-export declare function destination(out: string, version: string, format: NewsletterFormat): string;
-export declare function runNewsletter(argv: string[]): Promise<void>;

package/dist/newsletter/commands.js

@@ -1,311 +0,0 @@
-/**
- * `pnpm devtools newsletter [version…] [--format eml,html] [--out dir]
- * [--push] [--send --to addresses] [--mailbox address]`.
- */
-import { mkdir, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
-import { randomBytes } from "node:crypto";
-import { isTTY, log, multiselect, spinner, text as askText, } from "@clack/prompts";
-import { Resvg } from "@resvg/resvg-js";
-import { positionals } from "../args.js";
-import { errorMessage, explain, unwrap } from "../ui.js";
-import { loadNewsletter, loadNewsletterExport } from "../repo/peers.js";
-import { appendDraft } from "./imap.js";
-import { originationHeaders, submitMessage } from "./smtp.js";
-import { openInBrowser, startLoopback } from "./loopback.js";
-import { authorizeUrl, codeFromRedirect, grantPath, PASTE_REDIRECT_URI, readGrant, redeemCode, refreshTokens, writeGrant, } from "./oauth.js";
-/** The account the newsletter goes out from; `--mailbox` overrides. */
-const CLUB_MAILBOX = "devdogs@uga.edu";
-export const NEWSLETTER_FORMATS = ["eml", "html"];
-function flagValue(argv, flag) {
-    const index = argv.indexOf(flag);
-    if (index === -1)
-        return undefined;
-    const value = argv[index + 1];
-    return value && !value.startsWith("--") ? value : undefined;
-}
-function expandHome(value) {
-    return value === "~" || value.startsWith("~/")
-        ? resolve(homedir(), value.slice(2))
-        : value;
-}
-export function parseNewsletterArgs(argv, cwd) {
-    const push = argv.includes("--push");
-    const send = argv.includes("--send");
-    const to = (flagValue(argv, "--to") ?? "")
-        .split(",")
-        .map((value) => value.trim())
-        .filter(Boolean);
-    // A send is deliberate twice over: the flag names the act and --to names
-    // who receives it. Neither is inferred and neither is prompted for.
-    if (send && !to.length) {
-        return new Error("--send needs --to, a comma-separated recipient list.");
-    }
-    if (to.length && !send) {
-        return new Error("--to only means something with --send.");
-    }
-    // Both formats by default: the .eml is the point of the command, and the
-    // .html is how it gets proofread before an officer opens Outlook. Except
-    // under --push or --send, where a caller who wanted files too would have
-    // said so — the draft in the mailbox, or the send, IS the output.
-    const rawFormats = (flagValue(argv, "--format") ?? (push || send ? "" : "eml,html"))
-        .split(",")
-        .map((value) => value.trim())
-        .filter(Boolean);
-    const badFormats = rawFormats.filter((value) => !NEWSLETTER_FORMATS.includes(value));
-    if (badFormats.length)
-        return new Error(`Unknown format ${badFormats.join(", ")}. Try eml or html.`);
-    return {
-        // Versions can only be validated against the built package, which loads
-        // lazily inside the run — so they pass through here unchecked.
-        versions: positionals(argv),
-        formats: [...new Set(rawFormats)],
-        out: resolve(cwd, expandHome(flagValue(argv, "--out") ?? "changelog-exports")),
-        push,
-        send,
-        to,
-        mailbox: flagValue(argv, "--mailbox") ?? CLUB_MAILBOX,
-    };
-}
-export function destination(out, version, format) {
-    return resolve(out, `changelog-v${version}.${format}`);
-}
-async function interactive(options, all) {
-    if (options.versions.length)
-        return options;
-    if (!isTTY(process.stdout)) {
-        throw new Error("No terminal to choose issues. Name one, or pass * for all.");
-    }
-    const versions = unwrap(await multiselect({
-        message: "Which issues?",
-        options: all.map((issue) => ({
-            value: issue.version,
-            label: `v${issue.version}`,
-            hint: issue.tagline,
-        })),
-        initialValues: [all[all.length - 1]?.version ?? ""].filter(Boolean),
-        required: true,
-    }));
-    const outputs = unwrap(await multiselect({
-        message: "Which outputs?",
-        options: [
-            {
-                value: "push",
-                label: "Draft in the club mailbox",
-                hint: `lands in Drafts of ${options.mailbox}; review in any Outlook`,
-            },
-            {
-                value: "eml",
-                label: "Outlook draft (.eml)",
-                hint: "classic Outlook opens it for review",
-            },
-            { value: "html", label: "HTML preview", hint: "open in a browser" },
-        ],
-        initialValues: [...NEWSLETTER_FORMATS],
-        required: true,
-    }));
-    const formats = outputs.filter((output) => output !== "push");
-    let out = options.out;
-    if (formats.length) {
-        const entered = unwrap(await askText({
-            message: "Where should the files go?",
-            placeholder: "./changelog-exports",
-            defaultValue: "./changelog-exports",
-        })).trim();
-        out = resolve(process.cwd(), expandHome(entered || "changelog-exports"));
-    }
-    return {
-        ...options,
-        versions,
-        formats,
-        out,
-        push: options.push || outputs.includes("push"),
-    };
-}
-/**
- * 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(mailbox, server, state) {
-    const redirectUri = `http://localhost:${server.port}/`;
-    const url = authorizeUrl(mailbox, redirectUri, state);
-    log.step(`Sign in as ${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(new Error("Five minutes passed with no sign-in. Run it again.")), 5 * 60_000).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(mailbox) {
-    log.step(`Open this and sign in as ${mailbox}:`);
-    log.message(authorizeUrl(mailbox, PASTE_REDIRECT_URI));
-    const pasted = unwrap(await askText({
-        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 : undefined;
-        },
-    }));
-    const code = codeFromRedirect(pasted);
-    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(mailbox) {
-    const stored = await readGrant();
-    if (stored && stored.mailbox === mailbox) {
-        try {
-            const tokens = await refreshTokens(stored.refreshToken);
-            // Microsoft rotates refresh tokens; keeping the old one means the next
-            // run signs in from scratch.
-            await writeGrant({ mailbox, refreshToken: tokens.refreshToken });
-            return tokens.accessToken;
-        }
-        catch (err) {
-            log.warn(`The stored sign-in was refused (${errorMessage(err)}).`);
-        }
-    }
-    if (!isTTY(process.stdout)) {
-        throw new Error(`No terminal to sign in as ${mailbox}. Run \`pnpm devtools newsletter --push\` 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(mailbox, server, state)
-        : await signInViaPaste(mailbox);
-    await writeGrant({ mailbox, refreshToken: tokens.refreshToken });
-    log.info(`Signed in. The grant lives in ${grantPath()} — mode 600, keep it that way.`);
-    return tokens.accessToken;
-}
-export async function runNewsletter(argv) {
-    const parsed = parseNewsletterArgs(argv, process.cwd());
-    if (parsed instanceof Error) {
-        explain("Could not read that.", parsed.message, [
-            "pnpm devtools newsletter",
-            "pnpm devtools newsletter '*' --format eml,html --out ~/changelog",
-        ]);
-        process.exitCode = 1;
-        return;
-    }
-    try {
-        // Dynamic so every unrelated devtools command can still run before the
-        // newsletter package has been built on a fresh checkout.
-        const { ISSUES, issueByVersion } = await loadNewsletter();
-        const { buildEml, emailImages, previewRenderContext, renderIssueDocument } = await loadNewsletterExport();
-        const unknown = parsed.versions.filter((version) => version !== "*" && !issueByVersion(version));
-        if (unknown.length) {
-            explain("Could not read that.", `No issue called ${unknown.join(", ")}. Try ${ISSUES.map((issue) => issue.version).join(", ")}, or *.`, ["pnpm devtools newsletter", "pnpm devtools newsletter '*'"]);
-            process.exitCode = 1;
-            return;
-        }
-        const options = await interactive(parsed, ISSUES);
-        const versions = options.versions.includes("*")
-            ? ISSUES.map((issue) => issue.version)
-            : [...new Set(options.versions)];
-        // Rasterised once: the marks are the same in every issue. 2x the display
-        // size the components declare, so the email stays sharp on dense screens.
-        const images = options.formats.includes("eml") || options.push || options.send
-            ? emailImages().map((image) => ({
-                cid: image.cid,
-                filename: image.filename,
-                contentType: "image/png",
-                base64: Buffer.from(new Resvg(image.svg, {
-                    fitTo: { mode: "width", value: image.rasterWidth },
-                    // The marks are pure paths; nothing here needs a host font.
-                    font: { loadSystemFonts: false },
-                })
-                    .render()
-                    .asPng()).toString("base64"),
-            }))
-            : [];
-        const written = [];
-        for (const version of versions) {
-            const issue = issueByVersion(version);
-            for (const format of options.formats) {
-                const file = destination(options.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);
-        if (written.length) {
-            log.info(`${written.length} file${written.length === 1 ? "" : "s"} written. An .eml opens in classic Outlook for review; send with --send.`);
-        }
-        if (options.push || options.send) {
-            const accessToken = await mailboxAccessToken(options.mailbox);
-            if (options.push) {
-                for (const version of versions) {
-                    const issue = issueByVersion(version);
-                    await appendDraft({
-                        user: options.mailbox,
-                        accessToken,
-                        message: buildEml({
-                            subject: issue.title,
-                            html: renderIssueDocument(issue),
-                            images,
-                            unsent: false,
-                        }),
-                    });
-                    log.success(`v${version} → Drafts of ${options.mailbox}`);
-                }
-                log.info("Open any Outlook as the club account to review — but send with " +
-                    "`--send`, not from Outlook: its composers rewrite the HTML.");
-            }
-            if (options.send) {
-                for (const version of versions) {
-                    const issue = issueByVersion(version);
-                    await submitMessage({
-                        user: options.mailbox,
-                        accessToken,
-                        from: options.mailbox,
-                        recipients: options.to,
-                        message: originationHeaders(options.mailbox, options.to) +
-                            buildEml({
-                                subject: issue.title,
-                                html: renderIssueDocument(issue),
-                                images,
-                                unsent: false,
-                            }),
-                    });
-                    log.success(`v${version} → sent to ${options.to.join(", ")}`);
-                }
-            }
-        }
-    }
-    catch (err) {
-        explain("Could not export the changelog.", errorMessage(err), [
-            "Build it with `pnpm --filter @devdogsuga/newsletter build`.",
-            "Then try `pnpm devtools newsletter '*' --out ~/changelog`.",
-        ]);
-        process.exitCode = 1;
-    }
-}