@casomoltd/tooling 0.31.3 → 0.32.0

package/README.md

@@ -15,6 +15,7 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 | `@casomoltd/tooling/knip` | Knip config for unused exports/dependencies |
 | `@casomoltd/tooling/jscpd` | Copy-paste detection config |
 | `@casomoltd/tooling/readability` | `scoreText()` — readability scoring for page content |
+| `@casomoltd/tooling/buttondown` | For a repo using the `buttondown` command: `tokenReader()` for its email templates, `loadSettings()` and `buildPayload()` for its tests, `EMAIL_CHROME_HIDES` for its config, and the `Check` type for its own gates |
 
 ### Bin commands
 
@@ -32,6 +33,7 @@ Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
 | `spec-check` | Check a design spec's anchors, contents, figures and numbering |
 | `check-private-refs` | In a public repo, refuse a private tracker link or a name listed under `privateRefs` in `casomo.config.mjs` |
 | `check-personal-data` | Refuse an email, National Insurance number, UK mobile number, date of birth or locally denylisted name; per-repo allowances under `personalData` in `casomo.config.mjs` |
+| `buttondown` | Keep a Buttondown newsletter as code: `diff` and `apply` its fields (settings, skins and email templates) and tags, `check` the skins, sync their tokens, and create drafts. Settings under `buttondown` in `casomo.config.mjs`; the API key from the file `BUTTONDOWN_KEY_FILE` names |
 
 ## Install
 

package/bin/buttondown.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Keep a Buttondown newsletter as code: apply it, gate it, and work with
+ * its drafts. Settings are under `buttondown` in the repo's
+ * casomo.config.mjs (see buttondown/engine.mjs); the API key is read from
+ * the file `BUTTONDOWN_KEY_FILE` names.
+ *
+ *   buttondown [diff]              what live differs in: fields and tags
+ *   buttondown apply               patch what differs
+ *   buttondown check               gate the skins and settings (no key)
+ *   buttondown tokens              rewrite the web skin's TOKENS block
+ *   buttondown emit <dir>          write each long field out as rendered
+ *   buttondown draft <file.md>     create or replace a draft
+ *   buttondown upload <image>      upload an image, print its URL
+ *   buttondown api <METHOD> <path> [json]
+ *                                  any call, for setting up a manual test
+ *
+ * `diff`, `apply` and `check` exit 1 on drift, a refusal or a problem, so a
+ * script can gate on them.
+ */
+import {
+  apply, assertApiPath, client, draft, drift, emit, loadSettings, readKey,
+  runCheck, upload, writeTokens,
+} from "../buttondown/engine.mjs";
+
+const USAGE = "usage: buttondown [diff|apply|check|tokens|emit <dir>|"
+  + "draft <file.md>|upload <image>|api <METHOD> <path> [json]]";
+
+/** Each command with the fewest and most arguments it takes. */
+const ARGS = {
+  diff: [0, 0], apply: [0, 0], check: [0, 0], tokens: [0, 0],
+  emit: [1, 1], draft: [1, 1], upload: [1, 1], api: [2, 3],
+};
+
+const [command = "diff", ...args] = process.argv.slice(2);
+const [fewest, most] = ARGS[command] ?? [];
+if (fewest === undefined || args.length < fewest || args.length > most) {
+  console.error(USAGE);
+  process.exit(2);
+}
+
+const settings = await loadSettings();
+const api = async () => client(settings, await readKey());
+
+switch (command) {
+  case "diff": {
+    const {differs, tags} = await drift(settings, await api());
+    const all = [...differs, ...tags.map((t) => `tag ${t.body.name}`)];
+    console.log(all.length
+      ? `buttondown: live differs in ${all.join(", ")}`
+      : "buttondown: live matches");
+    process.exit(all.length ? 1 : 0);
+    break;
+  }
+  case "apply": {
+    const {refused} = await apply(settings, await api());
+    if (refused.length) {
+      console.error(`buttondown: refused ${refused.join(", ")}`);
+      process.exit(1);
+    }
+    break;
+  }
+  case "check": {
+    const problems = await runCheck(settings);
+    if (problems.length) {
+      console.error(`buttondown check:\n  ${problems.join("\n  ")}`);
+      process.exit(1);
+    }
+    console.log("buttondown check: clean");
+    break;
+  }
+  case "tokens":
+    await writeTokens(settings);
+    console.log("buttondown: TOKENS block written");
+    break;
+  case "emit":
+    for (const field of await emit(settings, args[0])) console.log(field);
+    break;
+  case "draft":
+    await draft(settings, await api(), args[0]);
+    break;
+  case "upload":
+    console.log(await upload(await api(), args[0]));
+    break;
+  case "api": {
+    const [method, url, body] = args;
+    assertApiPath(settings, method, url);
+    const res = await (await api()).call(
+      method.toUpperCase(), url, body && JSON.parse(body),
+    );
+    console.log(res.status, res.data ? JSON.stringify(res.data, null, 2) : "");
+    process.exit(res.ok ? 0 : 1);
+  }
+}

package/bin/utils.mjs

@@ -52,6 +52,7 @@ export async function loadConfig(filename, dir = process.cwd()) {
 
 /** The keys a repo's `casomo.config.mjs` may hold, one per gate. */
 export const CASOMO_CONFIG_KEYS = {
+  buttondown: "buttondown",
   personalData: "personalData",
   privateRefs: "privateRefs",
 };

package/bin/verify-pack.mjs

@@ -19,6 +19,7 @@ const ALLOWED_PREFIXES = [
   "readability/",
   "report/",
   "styles/",
+  "buttondown/",
 ];
 const ALLOWED_FILES = ["README.md", "package.json", "LICENSE", "LICENSE.md"];
 

package/buttondown/engine.mjs

@@ -0,0 +1,747 @@
+/**
+ * A Buttondown newsletter kept as code: its settings, skins and emails live
+ * in the repo, and this applies them to the live newsletter and gates them.
+ * The `buttondown` command drives it; `index.mjs` is the narrow public entry
+ * a repo's own files import.
+ *
+ * A repo configures it under `buttondown` in its `casomo.config.mjs`:
+ *
+ *   import {EMAIL_CHROME_HIDES} from "@casomoltd/tooling/buttondown";
+ *
+ *   export default {
+ *     buttondown: {
+ *       newsletter: {id, publicId, username}, // the one newsletter written
+ *       globals: "src/app/globals.css",       // the site's design tokens
+ *       dir: "buttondown",                    // newsletter.json and fields/
+ *       tokens: [["--color-accent", "--color-brand-accent"]], // target, source
+ *       extra: [["--radius", "0"]],           // uncommented lines after them
+ *       asserts: {"--radius-lg": "0"},        // tokens the skins depend on
+ *       allowedHides: {...EMAIL_CHROME_HIDES, ".selector": "why"},
+ *       linkClasses: {onDark: "on-dark"},     // each needs an `a.<class>` rule
+ *       ownLinks: ["/rss"],                   // hrefs that are not socials
+ *       paletteFiles: ["buttondown/assets/icon.svg"],
+ *       checks: ["buttondown/checks.mjs"],    // the repo's own gates
+ *     },
+ *   };
+ *
+ * `newsletter.json` holds the newsletter's short fields, `tags.json` its
+ * tags, and each file in `fields/` is the field it is named after: a
+ * stylesheet is read verbatim, and an `.mjs` file's default export is the
+ * field's value.
+ */
+import {existsSync} from "node:fs";
+import {mkdir, readdir, readFile, writeFile} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {pathToFileURL} from "node:url";
+import {loadCasomoConfig} from "../bin/utils.mjs";
+
+export const START = "/* TOKENS: generated by `buttondown tokens` */";
+export const END = "/* END TOKENS */";
+
+/**
+ * Buttondown's email chrome, for a repo whose emails draw their own header
+ * and footer bands. Not allowed by default: a repo opts in by spreading it
+ * into `allowedHides`.
+ */
+export const EMAIL_CHROME_HIDES = {
+  ".social-links": "the web footer's links, duplicated in an email",
+  ".newsletter-masthead": "replaced by the repo's own header band",
+  ".newsletter-icon": "the icon slot above the repo's own mark",
+  ".email-preamble": "the forwarding prompt between title and prose",
+  ".colophon": "the sender-and-date line under the hidden masthead",
+  ".email-actions--unsubscribe": "duplicated by the repo's own footer",
+  ".powered-by-icon": "the logo tile above the kept attribution line",
+};
+
+const API = "https://api.buttondown.com/v1";
+
+/** The API's own path prefix, which every request path sits under. */
+const API_PATH = new URL(API).pathname;
+
+/** The status of an email not yet sent. */
+const DRAFT = "draft";
+
+const FRONT_MATTER = /^---\n([\s\S]*?)\n---\n/;
+
+/** The two skins, by the Buttondown field each file fills. */
+const SKIN = {web: "web_css.css", email: "css.css"};
+
+/** Fields Buttondown stores behind its image proxy. */
+const IMAGE_FIELDS = new Set(["icon", "image"]);
+
+/** The newsletter's identity, which only casomo.config.mjs may carry: a
+ *  field of that name in newsletter.json would be sent as a setting. */
+const IDENTITY = ["id", "publicId", "username"];
+
+/** Hrefs Buttondown draws itself, which no socials entry names. */
+const BUTTONDOWN_LINKS = ["buttondown.com"];
+
+/** Values of `content:` that remove text rather than inject it. */
+const NO_CONTENT = new Set(["none", "normal", '""', "''"]);
+
+/** Shorter fields are settings, not documents, and `emit` leaves them to
+ *  newsletter.json, where they already read plainly. */
+const EMIT_MIN_LENGTH = 200;
+
+/** The repo's settings, every path absolute. Throws where the newsletter
+ *  or the tokens file is not named, since either would otherwise be
+ *  guessed. */
+export async function loadSettings(root = process.cwd()) {
+  const config = await loadCasomoConfig("buttondown", root);
+  const {id, username} = config.newsletter ?? {};
+  if (!id || !username) {
+    throw new Error(
+      "casomo.config.mjs needs buttondown.newsletter with an id and a "
+      + "username: it is the one newsletter this repo may write to",
+    );
+  }
+  if (!config.globals) {
+    throw new Error("casomo.config.mjs needs buttondown.globals: the "
+      + "stylesheet the site's design tokens are declared in");
+  }
+  const at = (p) => path.resolve(root, p);
+  return {
+    root,
+    newsletter: config.newsletter,
+    dir: at(config.dir ?? "buttondown"),
+    globals: at(config.globals),
+    tokens: config.tokens ?? [],
+    extra: config.extra ?? [],
+    asserts: config.asserts ?? {},
+    allowedHides: config.allowedHides ?? {},
+    linkClasses: Object.values(config.linkClasses ?? {}),
+    ownLinks: [...BUTTONDOWN_LINKS, ...(config.ownLinks ?? [])],
+    paletteFiles: (config.paletteFiles ?? []).map(at),
+    checks: (config.checks ?? []).map(at),
+  };
+}
+
+/**
+ * The value of one custom property, declared in a `:root` or `@theme`
+ * block: a `.dark {}` or `@media` override elsewhere in the file is a
+ * variant, not the token. Throws if absent, since a renamed token would
+ * otherwise leave a stale copy behind.
+ */
+export function readToken(css, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  for (const m of css.matchAll(
+    new RegExp(`^\\s*${escaped}:\\s*([^;]+);`, "gm"),
+  )) {
+    if (isBaseBlock(css, m.index)) {
+      return m[1].trim();
+    }
+  }
+  throw new Error(`${name} not found in a :root or @theme block`);
+}
+
+/** A reader for one stylesheet's tokens, for a repo's email blocks. */
+export async function tokenReader(file) {
+  const css = await readFile(file, "utf8");
+  return (name) => readToken(css, name);
+}
+
+/** Every field the newsletter is set to: newsletter.json, then fields/. */
+export async function buildPayload(settings) {
+  const payload = JSON.parse(
+    await readFile(path.join(settings.dir, "newsletter.json"), "utf8"),
+  );
+  for (const field of IMAGE_FIELDS) {
+    if (payload[field] && !URL.canParse(payload[field])) {
+      throw new Error(`${field} must be an absolute URL, got `
+        + JSON.stringify(payload[field]));
+    }
+  }
+  const identity = IDENTITY.filter((key) => key in payload);
+  if (identity.length) {
+    throw new Error(
+      `newsletter.json holds ${identity.join(", ")}: the newsletter's `
+      + "identity belongs in casomo.config.mjs, not among its fields",
+    );
+  }
+  const dir = path.join(settings.dir, "fields");
+  for (const file of (await readdir(dir)).sort()) {
+    const field = file.replace(/\.[a-z]+$/, "");
+    if (field in payload) {
+      throw new Error(
+        `${field} is set in both newsletter.json and fields/${file}`,
+      );
+    }
+    const full = path.join(dir, file);
+    if (!file.endsWith(".mjs")) {
+      payload[field] = await readFile(full, "utf8");
+      continue;
+    }
+    // A module may build a structured field too, such as `socials` from
+    // the site's own footer links, so the two cannot drift apart.
+    const value = (await import(pathToFileURL(full).href)).default;
+    if (typeof value !== "string" && (!value || typeof value !== "object")) {
+      throw new Error(`fields/${file} must default-export a string, an `
+        + `array or an object, got ${value === null ? "null" : typeof value}`);
+    }
+    payload[field] = value;
+  }
+  return payload;
+}
+
+/** The generated block of the web skin, from the site's tokens. */
+export function tokensBlock(settings, css) {
+  return [
+    START,
+    ...settings.tokens.map(
+      ([target, source]) =>
+        `  ${target}: ${readToken(css, source)}; /* ${source} */`,
+    ),
+    // A value starting `--` is read from the tokens; any other is literal.
+    ...settings.extra.map(
+      ([target, value]) =>
+        `  ${target}: ${
+          value.startsWith("--") ? readToken(css, value) : value
+        };`,
+    ),
+    END,
+  ].join("\n");
+}
+
+/** Rewrites the web skin's TOKENS block from the site's tokens. */
+export async function writeTokens(settings) {
+  const css = await readFile(settings.globals, "utf8");
+  const file = skinPath(settings, "web");
+  const web = await readFile(file, "utf8");
+  const {s, e} = markers(web);
+  await writeFile(
+    file, web.slice(0, s) + tokensBlock(settings, css) + web.slice(e),
+  );
+}
+
+/** Every problem with the repo's skins and settings; empty when clean. */
+export async function runCheck(settings) {
+  const css = await readFile(settings.globals, "utf8");
+  const web = await readIf(skinPath(settings, "web"));
+  const email = await readIf(skinPath(settings, "email"));
+  const payload = await buildPayload(settings);
+  const problems = [];
+
+  if (settings.tokens.length || settings.extra.length) {
+    const {s, e} = markers(web);
+    if (web.slice(s, e) !== tokensBlock(settings, css)) {
+      problems.push("the TOKENS block is stale: run `buttondown tokens`");
+    }
+  }
+  for (const [name, want] of Object.entries(settings.asserts)) {
+    const got = readToken(css, name);
+    if (got !== want) {
+      problems.push(`${name} is ${got} in the site's tokens; the skins `
+        + `depend on it being ${want}`);
+    }
+  }
+
+  // The palette is every hex the tokens file declares. Only hex is
+  // checked: an rgb() or named colour in a skin is not caught.
+  const palette = new Set(
+    [...css.matchAll(/#[0-9a-f]{3,8}\b/gi)].map((m) => longHex(m[0])),
+  );
+  const sources = [
+    ["web skin", cssValues(web)],
+    ["email skin", cssValues(email)],
+    ...await Promise.all(settings.paletteFiles.map(async (file) => [
+      path.relative(settings.root, file),
+      attributeValues(await readFile(file, "utf8")),
+    ])),
+  ];
+  for (const [where, values] of sources) {
+    for (const hex of offPalette(values, palette)) {
+      problems.push(`off-palette colour ${hex} in ${where}`);
+    }
+  }
+
+  for (const [where, text] of [["web skin", web], ["email skin", email]]) {
+    for (const selector of hides(text)) {
+      if (!(selector in settings.allowedHides)) {
+        problems.push(`${where} hides ${selector}, which allowedHides `
+          + "does not list: restyle Buttondown's markup, don't hide it");
+      }
+    }
+    for (const selector of injections(text)) {
+      problems.push(`${where} injects text with content: in ${selector}`);
+    }
+  }
+
+  const urls = [
+    ...(payload.socials ?? []).map((s) => s.url),
+    ...settings.ownLinks,
+  ];
+  for (const selector of orphanHrefs(web, urls)) {
+    problems.push(`${selector} in the web skin matches no socials URL`);
+  }
+
+  const emailRules = stripComments(email);
+  for (const name of settings.linkClasses) {
+    if (!new RegExp(`a\\.${name}(?![\\w-])`).test(emailRules)) {
+      problems.push(`email class "${name}" has no a.${name} rule, so `
+        + "the template's link colour would override it");
+    }
+  }
+
+  for (const file of settings.checks) {
+    const check = (await import(pathToFileURL(file).href)).default;
+    const found = await check({
+      root: settings.root, payload, css, web, email, readToken,
+    });
+    if (!Array.isArray(found)) {
+      throw new Error(`${path.relative(settings.root, file)} must resolve `
+        + "to an array of problems");
+    }
+    problems.push(...found);
+  }
+  return problems;
+}
+
+/** The API key, from the file `BUTTONDOWN_KEY_FILE` names: a path can be
+ *  passed around freely, while a key on a command line sits in the shell
+ *  history and in `ps`. */
+export async function readKey(env = process.env) {
+  const file = env.BUTTONDOWN_KEY_FILE;
+  if (!file) {
+    throw new Error("set BUTTONDOWN_KEY_FILE to the file holding the key");
+  }
+  const key = (await readFile(file.replace(/^~(?=\/)/, os.homedir()),
+    "utf8")).trim();
+  if (!key) throw new Error(`${file} is empty`);
+  return key;
+}
+
+/**
+ * A client for the one newsletter. The key reaches every newsletter on the
+ * account, so each request carries Buttondown-Context with this id, and
+ * Buttondown refuses an unknown id rather than falling back to the
+ * account's default newsletter.
+ */
+export function client(settings, key) {
+  const {newsletter} = settings;
+  async function call(method, url, body, {form} = {}) {
+    const res = await fetch(new URL(API + url), {
+      method,
+      headers: {
+        Authorization: `Token ${key}`,
+        "Buttondown-Context": newsletter.id,
+        ...(form ? {} : {"Content-Type": "application/json"}),
+      },
+      body: form ?? (body === undefined ? undefined : JSON.stringify(body)),
+    });
+    const text = await res.text();
+    let data = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      // Reported as the detail, so a non-JSON refusal still says why.
+      data = {detail: text};
+    }
+    return {ok: res.ok, status: res.status, data};
+  }
+
+  /** Writing to the wrong newsletter must not happen, so the newsletter
+   *  read before a write and the one a write returns are both checked.
+   *  Buttondown names a newsletter by its UUID and, on some endpoints, a
+   *  prefixed `publicId`; only those two are accepted. */
+  function assertNewsletter(got, when) {
+    const ids = [newsletter.id, newsletter.publicId].filter(Boolean);
+    if (!ids.includes(got?.id) || got?.username !== newsletter.username) {
+      throw new Error(`${when}: got ${got?.username} (${got?.id}), `
+        + `expected ${newsletter.username} (${newsletter.id})`);
+    }
+  }
+
+  async function live() {
+    const res = await call("GET", newsletterPath(newsletter));
+    if (!res.ok) throw new Error(`GET newsletter: ${detail(res)}`);
+    assertNewsletter(res.data, "before writing");
+    return res.data;
+  }
+
+  /** Every page of a list endpoint. A failed page throws: an empty list
+   *  would read as "none on the account" and skip what is there. */
+  async function list(url) {
+    const items = [];
+    for (let next = url; next;) {
+      const res = await call("GET", next);
+      if (!res.ok) throw new Error(`GET ${next}: ${detail(res)}`);
+      items.push(...res.data.results);
+      const more = res.data.next && new URL(res.data.next);
+      next = more ? more.pathname.slice(API_PATH.length) + more.search : null;
+    }
+    return items;
+  }
+
+  return {call, assertNewsletter, live, list};
+}
+
+/**
+ * Refuses an `api` call that writes newsletter settings anywhere but this
+ * newsletter. Judged on the path the server routes: percent-decoded, then
+ * normalised, so `/%6eewsletters/<other>`, `/./newsletters/<other>` and
+ * `<own>/../<other>` are seen for what they are. A path still encoded after
+ * one decoding is refused outright rather than guessed at.
+ */
+export function assertApiPath(settings, method, url) {
+  if (method.toUpperCase() === "GET") return;
+  const decoded = decodeURIComponent(new URL(API + url).pathname);
+  if (decoded.includes("%")) {
+    throw new Error(`api refuses an encoded path: ${url}`);
+  }
+  const {pathname} = new URL(decoded, API);
+  const own = API_PATH + newsletterPath(settings.newsletter);
+  if (pathname.startsWith(`${API_PATH}/newsletters`)
+    && pathname !== own && !pathname.startsWith(`${own}/`)) {
+    throw new Error(`api writes under /newsletters only to ${own}`);
+  }
+}
+
+/** Whether a live value already says what the repo wants. */
+export function same(field, got, want) {
+  if (IMAGE_FIELDS.has(field)) {
+    if (!want) return !got;
+    let url;
+    try {
+      url = new URL(got);
+    } catch {
+      // Unset, or not a URL at all: not the image the repo names.
+      return false;
+    }
+    // Buttondown stores an image behind its proxy, with the original URL
+    // percent-encoded in the path, so compare the decoded host and path.
+    const decoded = decodeURIComponent(`${url.origin}${url.pathname}`);
+    const w = new URL(want);
+    return decoded.endsWith(`${w.host}${w.pathname}`);
+  }
+  if (typeof want === "string") {
+    return typeof got === "string" && got.trim() === want.trim();
+  }
+  if (Array.isArray(want)) {
+    return Array.isArray(got) && got.length === want.length
+      && want.every((item, i) => same(field, got[i], item));
+  }
+  if (want && typeof want === "object") {
+    // A live object may carry keys the repo does not set.
+    return !!got && typeof got === "object"
+      && Object.entries(want).every(([k, v]) => same(k, got[k], v));
+  }
+  return got === want;
+}
+
+/** What live differs in: the newsletter's fields and its tags. */
+export async function drift(settings, api) {
+  const [payload, current, tags] = await Promise.all([
+    buildPayload(settings), api.live(), tagDrift(settings, api),
+  ]);
+  return {
+    payload,
+    differs: Object.keys(payload).filter(
+      (field) => !same(field, current[field], payload[field]),
+    ),
+    tags,
+  };
+}
+
+/**
+ * Patches what differs, in one call where Buttondown takes it. A
+ * plan-gated field makes Buttondown refuse the whole call, naming a
+ * feature rather than the field, so a refusal falls back to one field at
+ * a time. Returns what was refused, so a caller can fail on a partial
+ * write.
+ */
+export async function apply(settings, api, log = console.log) {
+  const {payload, differs, tags} = await drift(settings, api);
+  const refused = [];
+  if (!differs.length && !tags.length) {
+    log("buttondown: live already matches");
+    return {refused};
+  }
+  if (differs.length) {
+    const url = newsletterPath(settings.newsletter);
+    const body = Object.fromEntries(differs.map((f) => [f, payload[f]]));
+    const whole = await api.call("PATCH", url, body);
+    if (whole.ok) {
+      api.assertNewsletter(whole.data, "after writing");
+      log(`buttondown: updated ${differs.join(", ")}`);
+    } else {
+      log(`buttondown: whole PATCH refused (${detail(whole)}); `
+        + "field by field:");
+      for (const field of differs) {
+        const one = await api.call("PATCH", url, {[field]: payload[field]});
+        if (one.ok) {
+          api.assertNewsletter(one.data, "after writing");
+          log(`  ok       ${field}`);
+        } else {
+          refused.push(field);
+          log(`  REFUSED  ${field}: ${detail(one)}`);
+        }
+      }
+    }
+  }
+  for (const {tagId, body} of tags) {
+    if (!tagId) {
+      refused.push(`tag ${body.name}`);
+      log(`  tag ${body.name}: not on the account`);
+      continue;
+    }
+    const res = await api.call("PATCH", `/tags/${tagId}`, body);
+    if (!res.ok) refused.push(`tag ${body.name}`);
+    log(`  tag ${body.name}: ${res.ok ? "updated" : `REFUSED ${detail(res)}`}`);
+  }
+  return {refused};
+}
+
+/**
+ * A draft from a markdown file whose first line, after any front matter,
+ * is `# Subject`. Front matter carries the email's id once it exists, so a
+ * re-run replaces that draft rather than creating a second; `slug` and
+ * `description` are passed through. An email already sent is refused:
+ * replacing it would rewrite the published archive.
+ */
+export async function draft(settings, api, file, log = console.log) {
+  const raw = await readFile(file, "utf8");
+  const m = raw.match(FRONT_MATTER);
+  const fm = Object.fromEntries((m?.[1] ?? "").split("\n")
+    .filter((line) => line.includes(":"))
+    .map((line) => {
+      const at = line.indexOf(":");
+      return [line.slice(0, at).trim(), line.slice(at + 1).trim()];
+    }));
+  const lines = (m ? raw.slice(m[0].length) : raw).trimStart().split("\n");
+  if (!lines[0]?.startsWith("# ")) {
+    throw new Error("after any front matter, the first line must be "
+      + "`# Subject`");
+  }
+  if ("id" in fm && !fm.id) {
+    throw new Error("front matter has an empty `id:`; delete the line to "
+      + "create a draft");
+  }
+  // The marker says the body is markdown (Buttondown's `plaintext` mode).
+  // Without it Buttondown guesses, and a draft once stored as rich text
+  // takes the next PATCH as rich text too.
+  const body = {
+    subject: lines[0].slice(2).trim(),
+    body: "<!-- buttondown-editor-mode: plaintext -->\n"
+      + lines.slice(1).join("\n").trim(),
+    ...Object.fromEntries(["slug", "description"]
+      .filter((k) => k in fm).map((k) => [k, fm[k]])),
+  };
+  if (fm.id) {
+    const current = await api.call("GET", `/emails/${fm.id}`);
+    if (!current.ok) throw new Error(`GET email: ${detail(current)}`);
+    if (current.data.status !== DRAFT) {
+      throw new Error(`${fm.id} is ${current.data.status}, not a draft; `
+        + "replacing it would rewrite what was published");
+    }
+    const res = await api.call("PATCH", `/emails/${fm.id}`, body);
+    if (!res.ok) throw new Error(`refused: ${detail(res)}`);
+    log(`updated draft ${res.data.id}`);
+    return;
+  }
+  const res = await api.call("POST", "/emails", {...body, status: DRAFT});
+  if (!res.ok) throw new Error(`refused: ${detail(res)}`);
+  const withId = m
+    ? `---\nid: ${res.data.id}\n${raw.slice(4)}`
+    : `---\nid: ${res.data.id}\n---\n${raw}`;
+  await writeFile(file, withId);
+  log(`created draft ${res.data.id}; id written back into ${file}`);
+}
+
+/** Uploads an image and returns its Buttondown URL: the newsletter's
+ *  images must be Buttondown's own, not linked from elsewhere. */
+export async function upload(api, file) {
+  const form = new FormData();
+  form.append("image", new Blob([await readFile(file)]), path.basename(file));
+  const res = await api.call("POST", "/images", undefined, {form});
+  if (!res.ok || !res.data?.image) {
+    throw new Error(`upload refused: ${detail(res)}`);
+  }
+  return res.data.image;
+}
+
+/** Writes each long field out as rendered, so what Buttondown receives
+ *  can be read and diffed directly. */
+export async function emit(settings, dir) {
+  const payload = await buildPayload(settings);
+  await mkdir(dir, {recursive: true});
+  const written = [];
+  for (const [field, value] of Object.entries(payload)) {
+    if (typeof value !== "string" || value.length < EMIT_MIN_LENGTH) continue;
+    await writeFile(path.join(dir, field), value);
+    written.push(field);
+  }
+  return written;
+}
+
+/** Comments removed by index rather than a lazy regex, which backtracks
+ *  between its two literals. */
+export function stripComments(text) {
+  let out = "";
+  let at = 0;
+  for (;;) {
+    const open = text.indexOf("/*", at);
+    if (open === -1) return out + text.slice(at);
+    out += text.slice(at, open);
+    const close = text.indexOf("*/", open + 2);
+    if (close === -1) return out;
+    at = close + 2;
+  }
+}
+
+/** Why a call failed: Buttondown's `detail`, else its whole body, which
+ *  names the fields it refused, else the status. */
+const detail = (res) =>
+  JSON.stringify(res.data?.detail ?? res.data ?? res.status);
+
+const newsletterPath = (newsletter) => `/newsletters/${newsletter.id}`;
+
+const skinPath = (settings, kind) =>
+  path.join(settings.dir, "fields", SKIN[kind]);
+
+const readIf = async (file) =>
+  existsSync(file) ? readFile(file, "utf8") : "";
+
+/** Whether `index` sits directly in a top-level `:root` or `@theme` block:
+ *  `:root.dark`, `:root[data-theme]` and a `:root` nested in an at-rule are
+ *  variants of the token, not the token. */
+function isBaseBlock(css, index) {
+  const depth = [...css.slice(0, index)].reduce(
+    (d, c) => d + (c === "{") - (c === "}"), 0,
+  );
+  const head = enclosing(css, index);
+  return depth === 1 && (head === ":root" || /^@theme(\s|$)/.test(head));
+}
+
+/** The head of the block enclosing `index`, or "" at the top level. */
+function enclosing(css, index) {
+  let depth = 0;
+  for (let i = index; i >= 0; i -= 1) {
+    if (css[i] === "}") depth += 1;
+    if (css[i] === "{") {
+      if (depth === 0) {
+        const head = css.slice(0, i);
+        return head.slice(Math.max(head.lastIndexOf("}"),
+          head.lastIndexOf(";"), head.lastIndexOf("{")) + 1).trim();
+      }
+      depth -= 1;
+    }
+  }
+  return "";
+}
+
+/** The one TOKENS block's bounds; anything else is refused, since a
+ *  missing, repeated or reversed pair would slice the wrong text. */
+function markers(web) {
+  const s = web.indexOf(START);
+  const e = web.indexOf(END);
+  if (s === -1 || e === -1 || e < s
+    || web.indexOf(START, s + 1) !== -1 || web.indexOf(END, e + 1) !== -1) {
+    throw new Error("the web skin needs exactly one TOKENS block, start "
+      + "before end");
+  }
+  return {s, e: e + END.length};
+}
+
+function longHex(hex) {
+  const h = hex.slice(1).toLowerCase();
+  return h.length <= 4 ? `#${[...h].map((c) => c + c).join("")}` : `#${h}`;
+}
+
+/** Each rule as [selector, body], selectors whitespace-normalised. A rule
+ *  inside an at-rule takes the text after the at-rule's own brace. */
+function rules(text) {
+  return stripComments(text).split("}").flatMap((chunk) => {
+    const brace = chunk.lastIndexOf("{");
+    if (brace === -1) return [];
+    const head = chunk.slice(0, brace);
+    const selector = head.slice(head.lastIndexOf("{") + 1)
+      .split(/\s+/).join(" ").trim();
+    return [[selector, chunk.slice(brace + 1)]];
+  });
+}
+
+/** Each declaration in a stylesheet as [property, value]. */
+function declarations(text) {
+  return rules(text).flatMap(([, body]) => body.split(";").flatMap((decl) => {
+    const at = decl.indexOf(":");
+    return at === -1
+      ? []
+      : [[decl.slice(0, at).trim(), decl.slice(at + 1).trim()]];
+  }));
+}
+
+/** Declaration values only, so a selector such as `a:not(#cafe)` is not
+ *  read as a colour. */
+const cssValues = (text) =>
+  declarations(text).map(([, value]) => value).join(" ");
+
+/** An SVG's attribute values. */
+const attributeValues = (text) =>
+  [...text.matchAll(/="([^"]*)"/g)].map((m) => m[1]).join(" ");
+
+function offPalette(values, palette) {
+  return [...new Set(
+    [...values.matchAll(/#[0-9a-f]{3,8}\b/gi)]
+      .map((m) => m[0])
+      .filter((hex) => !palette.has(longHex(hex))),
+  )];
+}
+
+function hides(text) {
+  return rules(text)
+    .filter(([, body]) => body.split(";").some((decl) =>
+      /^(display:none|font-size:0)(!important)?$/.test(
+        decl.replace(/\s/g, ""),
+      )))
+    .map(([selector]) => selector);
+}
+
+function injections(text) {
+  return rules(text)
+    .filter(([selector, body]) => !selector.startsWith("@")
+      && body.split(";").some((decl) => {
+        // Anchored: justify-, align- and place-content end in content too.
+        const m = decl.match(/^\s*content\s*:\s*(.*?)\s*(!important)?\s*$/);
+        return m && !NO_CONTENT.has(m[1]);
+      }))
+    .map(([selector]) => selector);
+}
+
+/** Every href attribute selector the skin keys on that names no socials
+ *  URL, quoted either way or unquoted. */
+function orphanHrefs(text, urls) {
+  const matches = {
+    "=": (url, v) => url === v,
+    "~=": (url, v) => url.split(/\s+/).includes(v),
+    "|=": (url, v) => url === v || url.startsWith(`${v}-`),
+    "*=": (url, v) => url.includes(v),
+    "^=": (url, v) => url.startsWith(v),
+    "$=": (url, v) => url.endsWith(v),
+  };
+  return [...stripComments(text).matchAll(
+    /\[\s*href\s*([~|*^$]?=)\s*(?:"([^"]*)"|'([^']*)'|([^\s\]]+))(?:\s+[is])?\s*\]/gi,
+  )]
+    .filter(([, op, d, s, bare]) =>
+      !urls.some((url) => matches[op](url, d ?? s ?? bare)))
+    .map(([whole]) => whole);
+}
+
+/**
+ * Each tag in tags.json whose live fields differ, keyed by id rather than
+ * name: a tag's name is the label a subscriber reads in their preferences,
+ * so renaming one is an ordinary edit, and a lookup by name would miss on
+ * exactly that edit. The name is the fallback for a tag whose id is not
+ * written in yet; a tag found by neither comes back without a `tagId`.
+ */
+async function tagDrift(settings, api) {
+  const file = path.join(settings.dir, "tags.json");
+  if (!existsSync(file)) return [];
+  const live = await api.list("/tags");
+  return JSON.parse(await readFile(file, "utf8")).flatMap(({id, ...body}) => {
+    const current = live.find((t) => t.id === id)
+      ?? (id ? undefined : live.find((t) => t.name === body.name));
+    if (current && same("tag", current, body)) return [];
+    return [{tagId: current?.id, body}];
+  });
+}

package/buttondown/index.d.mts

@@ -0,0 +1,66 @@
+/** A newsletter field's value: a string, or the structured settings
+ *  Buttondown takes as JSON (socials, theme_configuration). */
+export type FieldValue =
+  | string
+  | number
+  | boolean
+  | null
+  | FieldValue[]
+  | {[key: string]: FieldValue};
+
+/** Every field the newsletter is set to, by Buttondown field name. */
+export type Payload = Record<string, FieldValue>;
+
+/** The one newsletter a repo may write to. */
+export interface Newsletter {
+  id: string;
+  /** The prefixed id some Buttondown endpoints return for the same one. */
+  publicId?: string;
+  username: string;
+}
+
+/** A repo's settings, as resolved from `buttondown` in casomo.config.mjs,
+ *  with every path absolute. */
+export interface Settings {
+  root: string;
+  newsletter: Newsletter;
+  dir: string;
+  globals: string;
+  tokens: [target: string, source: string][];
+  extra: [target: string, value: string][];
+  asserts: Record<string, string>;
+  allowedHides: Record<string, string>;
+  linkClasses: string[];
+  ownLinks: string[];
+  paletteFiles: string[];
+  checks: string[];
+}
+
+/** What a repo's own gate receives: the default export of each file
+ *  under `checks` takes this and resolves to its problems, empty when
+ *  clean. */
+export interface CheckContext {
+  root: string;
+  payload: Payload;
+  /** The site's tokens stylesheet. */
+  css: string;
+  /** The web skin and the email skin, as written. */
+  web: string;
+  email: string;
+  readToken(css: string, name: string): string;
+}
+
+export type Check = (context: CheckContext) => Promise<string[]>;
+
+/** Buttondown's email chrome, for a repo whose emails draw their own
+ *  bands: spread into `allowedHides` to allow hiding it. */
+export const EMAIL_CHROME_HIDES: Readonly<Record<string, string>>;
+
+export function loadSettings(root?: string): Promise<Settings>;
+
+export function buildPayload(settings: Settings): Promise<Payload>;
+
+/** A reader for one stylesheet's `:root` and `@theme` tokens. */
+export function tokenReader(
+  file: string | URL,
+): Promise<(name: string) => string>;

package/buttondown/index.mjs

@@ -0,0 +1,7 @@
+/**
+ * The public face of the Buttondown engine: what a repo's own files
+ * import. Everything else is the `buttondown` command's (engine.mjs).
+ */
+export {
+  buildPayload, EMAIL_CHROME_HIDES, loadSettings, tokenReader,
+} from "./engine.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casomoltd/tooling",
-  "version": "0.31.3",
+  "version": "0.32.0",
   "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots, design specs)",
   "license": "MIT",
   "repository": {
@@ -17,13 +17,14 @@
     "readability/",
     "report/",
     "styles/",
+    "buttondown/",
     "README.md",
     "!**/*.test.mjs"
   ],
   "scripts": {
     "check": "node bin/check-gates.mjs && node bin/verify-pack.mjs && npm run check:private-refs && npm run check:personal-data && npm run typecheck && npm run test && npm run lint:md",
     "typecheck": "tsc --noEmit -p hooks/tsconfig.json",
-    "test": "node hooks/test.mts && node bin/check-gates.test.mjs && node bin/check-personal-data.test.mjs && node bin/casomo-config.test.mjs && node commitlint/index.test.mjs",
+    "test": "node hooks/test.mts && node bin/check-gates.test.mjs && node bin/check-personal-data.test.mjs && node bin/casomo-config.test.mjs && node bin/buttondown.test.mjs && node commitlint/index.test.mjs",
     "lint:md": "remark --frail --quiet --no-stdout --rc-path bin/skills-lint.config.mjs skills agents docs",
     "build": "echo 'no-op: source-only repo, nothing to build'",
     "prepare": "husky || true",
@@ -46,10 +47,15 @@
     "./commitlint": "./commitlint/index.cjs",
     "./knip": "./knip/index.json",
     "./jscpd": "./jscpd/index.json",
-    "./readability": "./readability/index.mjs"
+    "./readability": "./readability/index.mjs",
+    "./buttondown": {
+      "types": "./buttondown/index.d.mts",
+      "default": "./buttondown/index.mjs"
+    }
   },
   "bin": {
     "build-report": "./bin/build-report.mjs",
+    "buttondown": "./bin/buttondown.mjs",
     "check-gates": "./bin/check-gates.mjs",
     "check-hooks": "./bin/check-hooks.sh",
     "check-linear": "./bin/check-linear.sh",