@shbernal/buzon 0.0.0-stage → 0.0.1

package/src/core/extract.ts

@@ -0,0 +1,173 @@
+const ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  zwnj: '',
+  shy: '',
+}
+
+export function decodeEntities(text: string): string {
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z][a-z0-9]+);/gi, (match, entity: string) => {
+    const name = entity.toLowerCase()
+    if (!name.startsWith('#')) return ENTITIES[name] ?? match
+    const code = name.startsWith('#x') ? Number.parseInt(name.slice(2), 16) : Number(name.slice(1))
+    return Number.isFinite(code) && code >= 0 && code <= 0x10ffff
+      ? String.fromCodePoint(code)
+      : match
+  })
+}
+
+const ANCHOR = /<a\b([^>]*)>([\s\S]*?)<\/a\s*>/gi
+const HREF = /\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i
+
+/** Readable text from an HTML part, with each link's target after its text. */
+export function htmlToText(html: string): string {
+  return decodeEntities(
+    html
+      .replace(/<\s*(script|style|head|svg|title)\b[^>]*>[\s\S]*?<\s*\/\s*\1\s*>/gi, ' ')
+      .replace(/<!--[\s\S]*?-->/g, ' ')
+      .replace(ANCHOR, (_, attributes: string, inner: string) => {
+        const href = anchorHref(attributes)
+        const text = inner.replace(/<[^>]+>/g, ' ').trim()
+        return href && href !== decodeEntities(text) ? ` ${text} (${href}) ` : ` ${text} `
+      })
+      .replace(/<\s*br\s*\/?>/gi, '\n')
+      .replace(/<\/\s*(p|div|tr|li|table|section|article|header|footer|h[1-6])\s*>/gi, '\n')
+      .replace(/<[^>]+>/g, ' '),
+  )
+    .replace(/[ \t\r\f\v ]+/g, ' ')
+    .replace(/ ?\n ?/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+function anchorHref(attributes: string): string | undefined {
+  const match = HREF.exec(attributes)
+  const raw = match?.[1] ?? match?.[2] ?? match?.[3]
+  return raw === undefined ? undefined : decodeEntities(raw.trim())
+}
+
+export type Link = { url: string; text: string }
+
+export function htmlLinks(html: string): Link[] {
+  const links: Link[] = []
+  for (const [, attributes, inner] of html.matchAll(ANCHOR)) {
+    const url = anchorHref(attributes!)
+    if (url) links.push({ url, text: htmlToText(inner!) })
+  }
+  return links
+}
+
+/**
+ * Bare URLs, without the punctuation that usually closes the sentence around them. The rest
+ * of the URL's line is its text, or the line above when the URL stands alone.
+ */
+export function textLinks(text: string): Link[] {
+  const links: Link[] = []
+  const lines = text.split(/\r?\n/)
+  lines.forEach((line, index) => {
+    for (const [url] of line.matchAll(/https?:\/\/[^\s<>"'\]]+/gi)) {
+      const label = line.replace(url, ' ').trim() || (lines[index - 1] ?? '').trim()
+      links.push({ url: url.replace(/[.,;:!?)]+$/, ''), text: label })
+    }
+  })
+  return links
+}
+
+const UNWANTED =
+  /unsubscribe|opt[-_ ]?out|preferences|manage[-_ ]?(subscription|e?mail)|list-manage/i
+const ASSET = /\.(png|jpe?g|gif|svg|webp|ico|css|js|woff2?|ttf)([?#]|$)/i
+const TRACKING = /\/(open|pixel|beacon)(\.gif)?([/?#]|$)/i
+const LINK_KEYWORDS =
+  /verif|confirm|activat|token|magic|log-?in|sign-?in|sign-?up|auth|validat|reset/gi
+
+const score = (link: Link) =>
+  (link.text.match(LINK_KEYWORDS)?.length ?? 0) * 2 + (link.url.match(LINK_KEYWORDS)?.length ?? 0)
+
+/**
+ * The link that most looks like a verification link: HTML anchors first, else URLs in the text
+ * part. Unsubscribe, tracking and asset links never count, and neither does a link with no
+ * keyword in its text or URL, so a mail without one is no match.
+ */
+export function bestLink(mail: { html: string; text: string }): string | undefined {
+  const fromHtml = mail.html ? htmlLinks(mail.html) : []
+  const candidates = (fromHtml.length > 0 ? fromHtml : textLinks(mail.text)).filter(
+    (link) =>
+      /^https?:\/\//i.test(link.url) &&
+      !UNWANTED.test(link.url) &&
+      !UNWANTED.test(link.text) &&
+      !ASSET.test(link.url) &&
+      !TRACKING.test(link.url),
+  )
+  let best: { url: string; score: number } | undefined
+  for (const link of candidates) {
+    const value = score(link)
+    if (value > 0 && (!best || value > best.score)) best = { url: link.url, score: value }
+  }
+  return best?.url
+}
+
+/** The instance's own extraction, saved in the row's `metadata` shortly after the mail lands. */
+export function serverCode(metadata: unknown): string | undefined {
+  if (typeof metadata !== 'string' || !metadata) return undefined
+  try {
+    const { ai_extract } = JSON.parse(metadata) as {
+      ai_extract?: { type?: string; result?: string }
+    }
+    return ai_extract?.type === 'auth_code' && ai_extract.result ? ai_extract.result : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const CODE_KEYWORD =
+  /(?<!(promo|coupon|discount|gift|referral|invite|zip|postal|country|area|error|status|tracking|order|reference|voucher)[\s-]?)\bcodes?\b|verification|\bverify\b|\botp\b|passcode|\bpin\b|one[\s-]?time|验证码|c[óo]digo|codice|код/giu
+const DIGIT_CODE = /(?<![\w+\-/.,:$€£#])(\d{3}[ -]\d{3}|\d{4,8})(?![\w/%]|[.,:]\d)/g
+const ALNUM_CODE =
+  /(?<![\w\-+/#])((?=[A-Za-z0-9]*\d)(?=[A-Za-z0-9]*[A-Za-z])[A-Za-z0-9]{6,8})(?![\w\-/])/g
+/** How far from a keyword a code may sit, in characters. */
+const NEAR = 120
+
+function isDate(digits: string): boolean {
+  const year = Number(digits.slice(0, 4))
+  if (year < 1900 || year > 2099) return false
+  if (digits.length === 4) return true
+  const month = Number(digits.slice(4, 6))
+  const day = Number(digits.slice(6, 8))
+  return digits.length === 8 && month >= 1 && month <= 12 && day >= 1 && day <= 31
+}
+
+/**
+ * A code near a verification keyword: 4 to 8 digits, or 6 to 8 letters and digits with at
+ * least one of each. URLs and addresses are dropped first, since their digits are never codes.
+ * The candidate closest to a keyword wins, digits on a tie.
+ */
+export function localCode(subject: string, body: string): string | undefined {
+  const text = `${subject}\n\n${body}`
+    .replace(/[​-‍⁠­]/g, '')
+    .replace(/\bhttps?:\/\/[^\s<>"']+/gi, ' ')
+    .replace(/[\w.+-]+@[\w-]+(\.[\w-]+)+/g, ' ')
+  const keywords = [...text.matchAll(CODE_KEYWORD)].map((match) => match.index)
+  if (keywords.length === 0) return undefined
+
+  let best: { code: string; distance: number } | undefined
+  for (const [pattern, digits] of [
+    [DIGIT_CODE, true],
+    [ALNUM_CODE, false],
+  ] as const) {
+    for (const match of text.matchAll(pattern)) {
+      const code = match[1]!.replace(/[ -]/g, '')
+      if (digits && isDate(code)) continue
+      const start = match.index
+      const end = start + match[0].length
+      const distance = Math.min(
+        ...keywords.map((at) => (at < start ? start - at : Math.max(0, at - end))),
+      )
+      if (distance <= NEAR && (!best || distance < best.distance)) best = { code, distance }
+    }
+  }
+  return best?.code
+}

package/src/core/files.ts

@@ -0,0 +1,40 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** The parsed file, or `undefined` when it does not exist. A damaged file throws. */
+export function readJson(file: string): unknown {
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    throw error
+  }
+  try {
+    return JSON.parse(text) as unknown
+  } catch (error) {
+    throw new Error(`${file} is not valid JSON`, { cause: error })
+  }
+}
+
+/**
+ * Written beside the target and renamed over it, so no reader ever sees half a file. The
+ * temp file gets its mode before any content, so a secret is never readable by others.
+ */
+export function writeAtomic(file: string, content: string, mode = 0o644): void {
+  mkdirSync(dirname(file), { recursive: true })
+  const temp = `${file}.${process.pid}.tmp`
+  try {
+    writeFileSync(temp, '', { mode })
+    chmodSync(temp, mode)
+    writeFileSync(temp, content)
+    renameSync(temp, file)
+  } catch (error) {
+    rmSync(temp, { force: true })
+    throw error
+  }
+}
+
+export function writeJson(file: string, value: unknown, mode?: number): void {
+  writeAtomic(file, `${JSON.stringify(value, null, 2)}\n`, mode)
+}

package/src/core/help.ts

@@ -0,0 +1,35 @@
+export const HELP = `buzon: tiered addresses on a self-hosted cloudflare_temp_email instance
+
+usage: buzon <command> [options]
+
+commands:
+  init      write the instance URL and mail domain, then check both
+            --url <https://mail.example.com>  --domain <example.com>
+  new       create an address: new <ste|mte|lte> | new custom <name>
+            [--site <site>] [--note "…"] [--domain <example.com>] [--show-token]
+  list      registry addresses: [--tier <ste|mte|lte|custom>] [--site <site>]
+  show      registry entry and inbox count: show <address>
+  note      set or clear the registry note: note <address> "<note>"
+  delete    delete on the instance and locally: delete <address> [--force]
+            (lte and custom addresses need --force)
+  reissue   fresh credentials from the admin API: reissue <address> | --all
+  adopt     add an address made elsewhere: adopt <address> [--note "…"]
+  read      print mail: read <address> [--latest | --id <n> | --all] [--raw]
+  wait      wait for new mail, print its code, link or whole text:
+            wait <address> [--code | --link] [--from <regex>] [--subject <regex>]
+            [--timeout 300] [--since now|<duration>|<date>]
+            (exits 1 on timeout; --since 10m also takes mail that came before)
+  delete-mail  delete one mail: delete-mail <address> <id>
+  deploy    build and deploy the pinned upstream release with the local wrangler.toml:
+            [--tag vX.Y.Z] [--dry-run]  (secrets stay as they are on the Worker)
+  upgrade   move to a newer release, asking before the backup, each db patch and the
+            deploy: upgrade --to vX.Y.Z
+  export-db dump the D1 database: [--out <dir>]  (keeps the last 12)
+
+tiers: ste is one-shot, mte lives for a process, lte is tied to a real account.
+An <address> without @ gets the configured domain.
+
+options:
+  --json     machine-readable output
+  --help     show this help
+  --version  show the version`

package/src/core/mail.ts

@@ -0,0 +1,80 @@
+import type { Api } from './api.ts'
+import { htmlToText } from './extract.ts'
+import { serverDate } from './time.ts'
+
+/** A row of `/api/parsed_mails`: the stored mail with its MIME parsed by the instance. */
+export type ParsedMail = {
+  id: number
+  /** Envelope sender. `sender` is the `From` header. */
+  source: string
+  address: string
+  created_at: string
+  metadata: string | null
+  sender: string
+  subject: string
+  text: string
+  html: string
+  attachments: { filename: string; mimeType: string; size: number }[]
+}
+
+export type Mail = {
+  id: number
+  from: string
+  to: string
+  subject: string
+  date: string
+  /** The text part, or the HTML part as text when there is none. */
+  text: string
+  html: string
+  attachments: ParsedMail['attachments']
+  metadata: string | null
+}
+
+export function toMail(row: ParsedMail): Mail {
+  return {
+    id: row.id,
+    from: row.sender || row.source,
+    to: row.address,
+    subject: row.subject,
+    date: serverDate(row.created_at) ?? row.created_at,
+    text: row.text.trim() || htmlToText(row.html),
+    html: row.html,
+    attachments: row.attachments,
+    metadata: row.metadata,
+  }
+}
+
+/** The largest page the instance serves. */
+const LIMIT = 100
+
+/** Newest first. */
+export async function listMails(api: Api, jwt: string, limit = LIMIT): Promise<Mail[]> {
+  const out: Mail[] = []
+  for (let offset = 0; ; offset += LIMIT) {
+    const page = Math.min(LIMIT, limit - out.length)
+    const { results } = await api.request<{ results: ParsedMail[] }>(
+      `/api/parsed_mails?limit=${page}&offset=${offset}`,
+      { jwt },
+    )
+    out.push(...results.map(toMail))
+    if (results.length < page || out.length >= limit) return out
+  }
+}
+
+export async function getMail(api: Api, jwt: string, id: number): Promise<Mail | undefined> {
+  const row = await api.request<ParsedMail | null>(`/api/parsed_mail/${id}`, { jwt })
+  return row ? toMail(row) : undefined
+}
+
+export async function getRawMail(api: Api, jwt: string, id: number): Promise<string | undefined> {
+  const row = await api.request<{ raw?: string } | null>(`/api/mail/${id}`, { jwt })
+  return row?.raw
+}
+
+export async function deleteMail(api: Api, jwt: string, id: number): Promise<boolean> {
+  const { success } = await api.request<{ success: boolean }>(`/api/mails/${id}`, {
+    method: 'DELETE',
+    jwt,
+  })
+  return success
+}

package/src/core/names.ts

@@ -0,0 +1,77 @@
+import { UsageError } from './args.ts'
+
+/** `ste` is one-shot, `mte` lives for a process, `lte` is tied to a real account. */
+export const TIERS = ['ste', 'mte', 'lte'] as const
+export type Tier = (typeof TIERS)[number]
+
+/** The instance's `ADDRESS_CHECK_REGEX`, and `MAX_ADDRESS_LEN`. */
+export const NAME_REGEX = /^(ste|mte|lte)-[0-9]{4}(-[a-z0-9]{1,12})?-[a-z0-9]{3}$/
+export const MAX_NAME_LENGTH = 30
+
+const SITE = /^[a-z0-9]{1,12}$/
+const CUSTOM = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/
+const ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789'
+
+export function parseTier(raw: string | undefined): Tier {
+  if (!TIERS.includes(raw as Tier)) throw new UsageError(`tier must be one of: ${TIERS.join(', ')}`)
+  return raw as Tier
+}
+
+export function parseSite(tier: Tier | 'custom', raw: string | undefined): string | undefined {
+  if (raw === undefined) return undefined
+  if (tier === 'ste') throw new UsageError('ste addresses are one-shot and take no --site')
+  const site = raw.toLowerCase()
+  if (!SITE.test(site)) throw new UsageError(`--site must be 1 to 12 of [a-z0-9], not "${raw}"`)
+  return site
+}
+
+/** Rejection sampling, so every character is equally likely. */
+export function randomChars(count: number): string {
+  let out = ''
+  while (out.length < count) {
+    for (const byte of crypto.getRandomValues(new Uint8Array(count))) {
+      if (byte < 252 && out.length < count) out += ALPHABET[byte % ALPHABET.length]
+    }
+  }
+  return out
+}
+
+/** `{tier}-{YYMM}[-{site}]-{rand3}`, with the UTC month. */
+export function generateName(
+  tier: Tier,
+  site: string | undefined,
+  now = new Date(),
+  random = randomChars,
+): string {
+  const yymm = now.toISOString().slice(2, 7).replace('-', '')
+  const name = [tier, yymm, site, random(3)].filter(Boolean).join('-')
+  if (!NAME_REGEX.test(name) || name.length > MAX_NAME_LENGTH) {
+    throw new Error(`generated "${name}", which the instance would reject`)
+  }
+  return name
+}
+
+/** Tier and site of a name that follows the scheme, or `undefined` for a custom one. */
+export function parseName(name: string): { tier: Tier; site?: string } | undefined {
+  const match = NAME_REGEX.exec(name)
+  if (!match) return undefined
+  const site = match[2]?.slice(1)
+  return site ? { tier: match[1] as Tier, site } : { tier: match[1] as Tier }
+}
+
+/**
+ * A name outside the scheme, checked here because the instance silently strips characters
+ * outside `ADDRESS_REGEX`. A tier prefix is refused: the cleanup matches on it.
+ */
+export function parseCustomName(raw: string): string {
+  const name = raw.trim().toLowerCase()
+  if (!CUSTOM.test(name) || name.length > MAX_NAME_LENGTH) {
+    throw new UsageError(
+      `a custom name is 1 to ${MAX_NAME_LENGTH} of [a-z0-9.-], starting and ending with a letter or digit, not "${raw}"`,
+    )
+  }
+  if (/^(ste|mte|lte)-/.test(name)) {
+    throw new UsageError(`"${raw}" starts with a tier prefix: use \`buzon new <tier>\` instead`)
+  }
+  return name
+}

package/src/core/paths.ts

@@ -0,0 +1,43 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+type Kind = 'config' | 'data' | 'state' | 'cache'
+
+const XDG: Record<Kind, [variable: string, fallback: string]> = {
+  config: ['XDG_CONFIG_HOME', '.config'],
+  data: ['XDG_DATA_HOME', join('.local', 'share')],
+  state: ['XDG_STATE_HOME', join('.local', 'state')],
+  cache: ['XDG_CACHE_HOME', '.cache'],
+}
+
+/** The XDG spec ignores a relative value, so a relative variable falls back like an unset one. */
+function dir(kind: Kind): string {
+  const [variable, fallback] = XDG[kind]
+  const value = process.env[variable]
+  const base = value?.startsWith('/') ? value : join(homedir(), fallback)
+  return join(base, 'buzon')
+}
+
+export const paths = {
+  get configDir() {
+    return dir('config')
+  },
+  get config() {
+    return join(dir('config'), 'config.toml')
+  },
+  get wrangler() {
+    return join(dir('config'), 'wrangler.toml')
+  },
+  get registry() {
+    return join(dir('data'), 'registry.json')
+  },
+  get backups() {
+    return join(dir('data'), 'backups')
+  },
+  get credentials() {
+    return join(dir('state'), 'credentials.json')
+  },
+  upstream(tag: string) {
+    return join(dir('cache'), 'upstream', tag)
+  },
+}

package/src/core/prompt.ts

@@ -0,0 +1,16 @@
+import { createInterface } from 'node:readline/promises'
+
+export type Ask = (question: string, fallback?: string) => Promise<string>
+
+/** One interface for every question: a second one would lose input the first had buffered. */
+export async function withPrompt<T>(use: (ask: Ask) => Promise<T>): Promise<T> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr })
+  try {
+    return await use(async (question, fallback) => {
+      const hint = fallback ? ` [${fallback}]` : ''
+      return (await rl.question(`${question}${hint}: `)).trim() || fallback || ''
+    })
+  } finally {
+    rl.close()
+  }
+}

package/src/core/registry.ts

@@ -0,0 +1,28 @@
+import { paths } from './paths.ts'
+import { readJson, writeJson } from './files.ts'
+import type { Tier } from './names.ts'
+
+/** `custom` is an address named outside the scheme and adopted later. It is kept like `lte`. */
+export type RegistryTier = Tier | 'custom'
+
+/** What an address is for. Kept in the user's dotfiles, so it never holds a secret. */
+export type RegistryEntry = {
+  tier: RegistryTier
+  site?: string
+  note?: string
+  createdAt: string
+  addressId: number
+}
+
+/** Keyed by full address. */
+export type Registry = {
+  addresses: Record<string, RegistryEntry>
+}
+
+export function readRegistry(file = paths.registry): Registry {
+  return (readJson(file) as Registry | undefined) ?? { addresses: {} }
+}
+
+export function writeRegistry(registry: Registry, file = paths.registry): void {
+  writeJson(file, registry)
+}

package/src/core/secrets.ts

@@ -0,0 +1,62 @@
+export type SecretKey = 'site-password' | 'admin-password'
+
+const ENV: Record<SecretKey, string> = {
+  'site-password': 'BUZON_SITE_PASSWORD',
+  'admin-password': 'BUZON_ADMIN_PASSWORD',
+}
+
+interface Keyring {
+  name: string
+  lookup: (key: SecretKey) => string[]
+  store: (key: SecretKey) => string
+}
+
+const KEYRINGS: Partial<Record<NodeJS.Platform, Keyring>> = {
+  linux: {
+    name: 'secret-tool',
+    lookup: (key) => ['secret-tool', 'lookup', 'service', 'buzon', 'key', key],
+    store: (key) => `secret-tool store --label="buzon ${key}" service buzon key ${key}`,
+  },
+  darwin: {
+    name: 'the macOS Keychain',
+    lookup: (key) => ['security', 'find-generic-password', '-s', 'buzon', '-a', key, '-w'],
+    store: (key) => `security add-generic-password -s buzon -a ${key} -w`,
+  },
+}
+
+export type Run = (argv: string[]) => { success: boolean; stdout: string }
+
+const run: Run = (argv) => {
+  const result = Bun.spawnSync(argv, { stdout: 'pipe', stderr: 'pipe' })
+  return { success: result.success, stdout: result.stdout?.toString() ?? '' }
+}
+
+/**
+ * The environment variable, else the platform keyring: the Secret Service through `secret-tool`
+ * on Linux, the Keychain through `security` on macOS. Other platforms use the variable only.
+ */
+export function secret(
+  key: SecretKey,
+  { env = process.env, platform = process.platform, spawn = run } = {},
+): string {
+  const fromEnv = env[ENV[key]]
+  if (fromEnv) return fromEnv
+
+  const keyring = KEYRINGS[platform]
+  if (!keyring) throw new Error(`no ${key}: set ${ENV[key]}`)
+
+  const store = keyring.store(key)
+  let result: ReturnType<Run>
+  try {
+    result = spawn(keyring.lookup(key))
+  } catch (error) {
+    throw new Error(`no ${key}: set ${ENV[key]}, or store it in ${keyring.name}: \`${store}\``, {
+      cause: error,
+    })
+  }
+  const value = result.stdout.replace(/\n$/, '')
+  if (!result.success || value === '') {
+    throw new Error(`no ${key} in ${keyring.name}: run \`${store}\`, or set ${ENV[key]}`)
+  }
+  return value
+}

package/src/core/time.ts

@@ -0,0 +1,16 @@
+import { UsageError } from './args.ts'
+
+/** D1 stores `YYYY-MM-DD HH:MM:SS` in UTC. */
+export function serverDate(raw: string): string | undefined {
+  const date = new Date(`${raw.replace(' ', 'T')}Z`)
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
+}
+
+const UNITS: Record<string, number> = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }
+
+/** `90`, `90s`, `5m`, `2h` or `1d`, in milliseconds. A bare number is seconds. */
+export function parseDuration(raw: string, flag: string): number {
+  const match = /^(\d+(?:\.\d+)?)([smhd]?)$/.exec(raw.trim())
+  if (!match) throw new UsageError(`--${flag} must be a duration such as 90s, 5m or 2h`)
+  return Number(match[1]) * UNITS[match[2] || 's']!
+}

package/src/core/upstream.ts

@@ -0,0 +1,96 @@
+import { copyFileSync, existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { paths } from './paths.ts'
+
+const REPO = 'https://github.com/dreamhunter2333/cloudflare_temp_email'
+
+/** Upstream builds with pnpm, and the checkout is a git clone. */
+export function requireTools(): void {
+  for (const tool of ['git', 'pnpm']) {
+    if (!Bun.which(tool)) throw new Error(`${tool} is not on PATH: buzon needs it to deploy`)
+  }
+}
+
+/** The child's stdout goes to stderr, so `--json` output stays alone on stdout. */
+export async function run(cmd: string[], cwd: string): Promise<void> {
+  const child = Bun.spawn(cmd, { cwd, stdin: 'inherit', stdout: 2 as never, stderr: 'inherit' })
+  const code = await child.exited
+  if (code !== 0) throw new Error(`\`${cmd.join(' ')}\` failed (exit ${code}) in ${cwd}`)
+}
+
+function capture(cmd: string[], cwd?: string): { code: number; out: string } {
+  const result = Bun.spawnSync(cmd, { cwd, stdout: 'pipe', stderr: 'inherit' })
+  return { code: result.exitCode, out: result.stdout.toString() }
+}
+
+/** A shallow clone of `tag`, made on first use. Local edits stop a deploy from shipping them. */
+export async function checkout(tag: string): Promise<string> {
+  const dir = paths.upstream(tag)
+  if (!existsSync(dir)) {
+    await run(['git', 'clone', '--quiet', '--depth', '1', '--branch', tag, REPO, dir], '/')
+    return dir
+  }
+  const status = capture(['git', 'status', '--porcelain'], dir)
+  if (status.code !== 0) throw new Error(`${dir} is not a git checkout: remove it and retry`)
+  if (status.out.trim()) throw new Error(`${dir} has local changes:\n${status.out.trimEnd()}`)
+  return dir
+}
+
+/** Dependencies installed and the user's `wrangler.toml` copied into the worker. */
+export async function prepare(tag: string): Promise<string> {
+  requireTools()
+  if (!existsSync(paths.wrangler)) throw new Error(`no wrangler config at ${paths.wrangler}`)
+  const dir = await checkout(tag)
+  for (const part of ['worker', 'frontend']) {
+    await run(['pnpm', 'install', '--frozen-lockfile'], join(dir, part))
+  }
+  copyFileSync(paths.wrangler, join(dir, 'worker', 'wrangler.toml'))
+  return dir
+}
+
+type WranglerToml = { d1_databases?: { database_name?: string }[] }
+
+export function databaseName(file = paths.wrangler): string {
+  const parsed = Bun.TOML.parse(readFileSync(file, 'utf8')) as WranglerToml
+  const name = parsed.d1_databases?.[0]?.database_name
+  if (!name) throw new Error(`${file} names no D1 database`)
+  return name
+}
+
+/** `wrangler`, from the checkout's own dependencies. */
+export function wrangler(dir: string, args: string[]): Promise<void> {
+  return run(['pnpm', 'wrangler', ...args], join(dir, 'worker'))
+}
+
+/** The `db/` files the newer checkout has and the older one lacks, oldest first. */
+export function addedDbFiles(older: string, newer: string): string[] {
+  const before = new Set(readdirSync(join(older, 'db')))
+  return readdirSync(join(newer, 'db'))
+    .filter((file) => file.endsWith('.sql') && !before.has(file))
+    .toSorted()
+}
+
+/** Changelog lines that name `file`. Some patches are never named there. */
+export function changelogMentions(dir: string, file: string): string[] {
+  const changelog = readFileSync(join(dir, 'CHANGELOG_EN.md'), 'utf8')
+  return changelog
+    .split('\n')
+    .filter((line) => line.includes(file))
+    .map((line) => line.trim())
+}
+
+/** A unified diff of the two `wrangler.toml.template` files, empty when they match. */
+export function templateDiff(older: string, newer: string): string {
+  const file = join('worker', 'wrangler.toml.template')
+  const { code, out } = capture([
+    'git',
+    'diff',
+    '--no-index',
+    '--no-color',
+    '--',
+    join(older, file),
+    join(newer, file),
+  ])
+  if (code > 1) throw new Error('could not diff the wrangler templates')
+  return out
+}