@supersuit/suggest-a-change 0.1.12 → 0.2.0

package/src/github/compose.ts

@@ -0,0 +1,354 @@
+// ONE PLAIN ISSUE, AND THE LIST OF WHAT GOES INTO IT (suggestions-as-github-issues design, sections 1 and 2).
+// `pieces` decides what a report carries; `whatGoes` says it in the sheet's words and `composeIssue` writes it into
+// the body, both from that one decision, so the sheet can never promise less than the issue carries. No model is
+// involved: the body is the person's own words and the facts the app stamped, laid out the same way every time.
+
+/** A piece the report carries. `ctx:<key>` is one context item; routes, taps and errors are the trail; contact is how to reach them. */
+export type Piece = 'words' | 'voice' | 'images' | 'video' | 'where' | 'app' | 'device' | 'time' | 'routes' | 'taps' | 'errors' | 'contact' | 'filer' | `ctx:${string}`
+export interface ContextItem { key: string; label: string; value: string; why: string }
+export interface DraftContext {
+  items?: ContextItem[]
+  routes?: { route: string; at: string }[]
+  taps?: { label: string; at: string }[]
+  errors?: { message: string; frame?: string; at: string }[]
+}
+export interface Contact { email?: string; phone?: string; handle?: string }
+/** One line of the sheet's list. `optional` rows can be left out; `on` is whether they go by default, `reason` why not. */
+export interface GoesItem { key: Piece; text: string; value?: string; why?: string; optional?: boolean; on?: boolean; reason?: string }
+export interface Destination {
+  /** owner/name of the repo the issue files on. */
+  repo: string
+  /** True for a public repo: the sheet says so in the danger colour. */
+  public: boolean
+  /** The GitHub login the issue is filed from. */
+  account: string
+  /** False when files cannot reach this repo yet (no App installed and the filer cannot push): they wait. */
+  attaches: boolean
+  /** False when nobody transcribes voice notes (an app's own server): the list does not promise a transcript. */
+  transcribes?: boolean
+  /** The largest file this destination takes; a larger one is named in the list as staying on the phone. */
+  maxInlineBytes?: number
+}
+/** What composeIssue and whatGoes read: a report in the contract's shape, plus two optional names for the list. */
+export interface Draft {
+  id?: string
+  kind?: string
+  words?: string
+  who?: { member?: string; role?: string; contact?: Contact }
+  /** Everything else shared so it can be fixed (the module's `collectContext`, and the app's own items). */
+  context?: DraftContext
+  voice?: { file: string; ms?: number }[]
+  media?: { file: string; type: string; bytes?: number; ms?: number }[]
+  where?: { screen?: string; route?: string }
+  diagnostics?: { appVersion?: string; at?: string; device?: string; screen?: string; [k: string]: unknown }
+  /** The sender's name as the issue will say it (the list's "your name, ..."). */
+  filerName?: string
+  /** The app's name, for the list's "Helm 2.14.0". */
+  appName?: string
+  [k: string]: unknown
+}
+export interface ComposeOptions {
+  appName?: string
+  /** The app label's host-given name (`app:<appLabel>`); null for none. Without it the label is made from appName. */
+  appLabel?: string | null
+  appVersion?: string
+  filerName?: string
+  filerRole?: string
+  /** file name -> its link, from an AttachmentHost. A file with no link yet is written as still being added. */
+  attachmentUrls?: Record<string, string>
+  /** The voice notes' transcript, made on the owner's Mac. */
+  transcript?: string
+  /** The first body, written before any file is saved: every attachment is "being added". */
+  pending?: boolean
+}
+export interface ComposedIssue { title: string; body: string; labels: string[]; carries: Piece[] }
+
+/** GitHub refuses a body of 65536 characters or more; this leaves room. */
+export const BODY_LIMIT = 65_000
+const LABEL: Record<string, string> = { change: 'enhancement', broken: 'bug', feedback: 'feedback' }
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g
+
+const isImage = (m: { type: string }) => String(m.type).startsWith('image/')
+const isVideo = (m: { type: string }) => String(m.type).startsWith('video/')
+const text = (v: unknown) => (typeof v === 'string' ? v : '')
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`
+const list = (parts: string[]) => (parts.length <= 1 ? parts.join('') : `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`)
+
+const contactOf = (d: Draft): Contact | null => {
+  const c = d.who?.contact
+  return c && (c.email || c.phone || c.handle) ? c : null
+}
+/** Whether a report carries context; with it, the context table stands in for the About line. */
+const hasContext = (d: Draft) => Boolean(d.context && ((d.context.items ?? []).length || (d.context.routes ?? []).length || (d.context.taps ?? []).length || (d.context.errors ?? []).length))
+
+/** Which pieces a report carries, in the order the issue and the list both use. */
+export function pieces(d: Draft): Piece[] {
+  const media = d.media ?? []
+  const g = d.diagnostics ?? {}
+  const out: Piece[] = []
+  if (text(d.words).trim()) out.push('words')
+  if ((d.voice ?? []).length) out.push('voice')
+  if (media.some(isImage)) out.push('images')
+  if (media.some(isVideo)) out.push('video')
+  if (text(d.where?.screen) || text(d.where?.route)) out.push('where')
+  if (text(g.appVersion)) out.push('app')
+  if (hasContext(d)) {
+    for (const i of d.context!.items ?? []) out.push(`ctx:${i.key}`)
+    if ((d.context!.routes ?? []).length) out.push('routes')
+    if ((d.context!.taps ?? []).length) out.push('taps')
+    if ((d.context!.errors ?? []).length) out.push('errors')
+  } else {
+    if (text(g.device) || text(g.screen)) out.push('device')
+    if (text(g.at)) out.push('time')
+  }
+  if (contactOf(d)) out.push('contact')
+  out.push('filer')
+  return out
+}
+
+export const TRAIL_WORDS = {
+  routes: { label: 'Pages you visited before this', heading: 'Pages visited before this', why: 'so the fixer can retrace how you got here' },
+  taps: { label: 'Your last taps', heading: 'Last taps', why: 'so the fixer can repeat what you did, by what the buttons are called; never what you typed' },
+  errors: { label: 'Errors the page hit', heading: 'Errors on the page', why: 'the error the app hit is often the fastest way to the cause' },
+}
+export const CONTACT_WHY = 'so whoever fixes it can thank you or ask a follow-up question'
+export const PUBLIC_CONTACT_REASON = 'this repo is public, so anyone could read it'
+const contactValue = (c: Contact) => [c.email, c.phone, c.handle].filter(Boolean).join(' · ')
+
+/** The sheet's list, in plain words, one item per piece the issue will carry, with the value and why for each piece
+ *  of context. Anything but what the person added, the app's version and their name can be left out (`optional`). */
+export function whatGoes(draft: Draft, destination: Destination): GoesItem[] {
+  const ctxItems = new Map((draft.context?.items ?? []).map((i) => [`ctx:${i.key}`, i]))
+  const contact = contactOf(draft)
+  const trailCount = (k: 'routes' | 'taps' | 'errors') => (draft.context?.[k] ?? []).length
+  const trailUnit = { routes: 'page', taps: 'tap', errors: 'error' } as const
+  return basicGoes(draft, destination).map((g) => {
+    const c = ctxItems.get(g.key)
+    if (c) return { key: g.key, text: c.label, value: c.value, why: c.why, optional: true, on: true }
+    if (g.key === 'routes' || g.key === 'taps' || g.key === 'errors') {
+      const w = TRAIL_WORDS[g.key]
+      return { key: g.key, text: w.label, value: plural(trailCount(g.key), trailUnit[g.key]), why: w.why, optional: true, on: true }
+    }
+    if (g.key === 'contact' && contact) {
+      return { key: g.key, text: 'How to reach you', value: contactValue(contact), why: CONTACT_WHY, optional: true, on: !destination.public, ...(destination.public ? { reason: PUBLIC_CONTACT_REASON } : {}) }
+    }
+    return g
+  })
+}
+
+function basicGoes(draft: Draft, destination: Destination): GoesItem[] {
+  const media = draft.media ?? []
+  const g = draft.diagnostics ?? {}
+  const kept = destination.attaches
+    ? `saved to the suggestion-attachments branch of ${destination.repo}`
+    : `added once ${destination.repo} can take attachments`
+  const voices = (draft.voice ?? []).length
+  // A file the destination cannot take is said so in advance, by name, before anything is sent.
+  const max = destination.maxInlineBytes
+  const mb = (n: number) => (n < 2 ** 20 ? `${Math.max(1, Math.round(n / 1024))} KB` : `${Math.round((n / 2 ** 20) * 10) / 10} MB`)
+  const tooBig = (files: { file: string; bytes?: number }[]) => {
+    const over = max ? files.filter((m) => (m.bytes ?? 0) > max) : []
+    return over.length ? `; ${list(over.map((m) => m.file))} ${over.length === 1 ? 'is' : 'are'} over the ${mb(max!)} ${destination.repo} can take, so ${over.length === 1 ? 'it does' : 'they do'} not reach the issue` : ''
+  }
+  const say: Record<string, () => string> = {
+    words: () => 'your words',
+    voice: () => destination.transcribes === false
+      ? (voices === 1 ? 'your voice note' : `your ${voices} voice notes`)
+      : (voices === 1 ? 'your voice note and its transcript' : `your ${voices} voice notes and their transcripts`),
+    images: () => `${plural(media.filter(isImage).length, 'screenshot')}, ${kept}${tooBig(media.filter(isImage))}`,
+    video: () => `${plural(media.filter(isVideo).length, 'video')}, ${kept}${tooBig(media.filter(isVideo))}`,
+    where: () => `this screen (${[text(draft.where?.screen), text(draft.where?.route)].filter(Boolean).join(', ')})`,
+    app: () => `${draft.appName || 'the app'} ${text(g.appVersion)}`,
+    device: () => [text(g.device), text(g.screen)].filter(Boolean).join(', '),
+    time: () => 'the time',
+    filer: () => (draft.filerName ? `your name, ${draft.filerName}` : 'that it came from you'),
+  }
+  return pieces(draft).map((key) => ({ key, text: say[key]?.() ?? key }))
+}
+
+/** The lines around the list: where it files, who can read it there, and whose account files it. */
+export function destinationWords(d: Destination): { headline: string; privacy: string; danger: boolean; account: string } {
+  return {
+    headline: `Sending this files an issue on ${d.repo}`,
+    privacy: d.public ? 'public: anyone on the internet can read this' : `private: people with access to ${d.repo}'s code can read it`,
+    danger: Boolean(d.public),
+    account: `Filed from ${d.account}'s GitHub account.`,
+  }
+}
+
+/** "2026-10-26T17:04:12Z" -> "2026-10-26 17:04 UTC"; anything unreadable as it is. */
+function when(at: string): string {
+  const t = Date.parse(at)
+  if (!Number.isFinite(t)) return inline(at) // not a time: shown, escaped, as any other line
+  const iso = new Date(t).toISOString()
+  return `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`
+}
+function firstSentence(s: string): string {
+  const line = s.trim().split('\n')[0].trim()
+  const m = /^.*?[.!?](?=\s|$)/.exec(line)
+  return (m ? m[0] : line).trim()
+}
+function clip(s: string, max: number): string {
+  if (s.length <= max) return s
+  let cut = s.slice(0, max - 1)
+  const space = cut.lastIndexOf(' ')
+  if (space > max / 2) cut = cut.slice(0, space)
+  return `${cut.trimEnd()}…`
+}
+/** Text that cannot become markup in the issue. */
+const html = (s: string) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+/** A table cell: no markup, no pipe that ends the cell, on one line. */
+const cell = (s: string) => inline(s).replace(/\|/g, '\\|')
+/** One line of report-borne text, made inert: no HTML, no emphasis, code, link or image syntax, no @mention, no #123
+ *  reference, on one line. Every string a report brings that is not inside a fence goes through this. */
+const inline = (s: string) => html(String(s)).replace(/[\\`*_[\]~!]/g, '\\$&').replace(/@(?=[\w-])/g, '@\u200d').replace(/#(?=\d)/g, '#\u200d').replace(/\r?\n/g, ' ')
+/** Text a person wrote, shown as they wrote it inside a fence longer than any backtick run in it, so nothing in it renders. */
+const fence = (s: string) => {
+  const run = Math.max(0, ...[...s.matchAll(/`+/g)].map((m) => m[0].length))
+  const f = '`'.repeat(Math.max(3, run + 1))
+  return `${f}\n${s}\n${f}`
+}
+/** Link text with no markdown of its own (an email address keeps its @: it is not a mention inside link text). */
+const linkText = (s: string) => html(String(s)).replace(/[\\`*_[\]~!]/g, '\\$&').replace(/\r?\n/g, ' ')
+/** Only an https link with nothing that could end or break the link may become one; anything else is not linked. */
+const safeUrl = (u: unknown): string | null => (typeof u === 'string' && /^https:\/\/[^\s()<>"'`]+$/.test(u) ? u : null)
+/** THE LAST LINE OF EVERY ISSUE, written and recognized by these two and nothing else: a relay accepts an attachment for
+ *  a report only on an issue that ends with this line for it, so the writer and the reader must never drift apart. */
+export const FILED_BY = '## Filed by'
+export function filedByLine(filer: string, role: string, appName: string | undefined, reportId: string): string {
+  return `${inline(filer)} (${inline(role)}), through Suggest a change in ${appName ? `the ${inline(appName)}` : 'an app'}. Report ${inline(reportId)}.`
+}
+/** Whether an issue's body ends with the composer's own Filed by line for this report, in either of its forms. */
+export function endsWithFiledBy(body: string, reportId: string): boolean {
+  if (!/^r-\d{14}-[a-z0-9]{6}$/.test(reportId)) return false
+  const lines = String(body).replace(/\s+$/, '').split('\n')
+  const last = lines[lines.length - 1] ?? ''
+  return lines[lines.length - 2]?.trim() === FILED_BY && new RegExp(`^\\S.* \\(.+\\), through Suggest a change in (the .+|an app)\\. Report ${reportId}\\.$`).test(last)
+}
+/** "2026-10-26T17:04:05Z" -> "17:04:05 UTC"; anything else as it is. */
+const clock = (at: string) => { const t = Date.parse(at); return Number.isFinite(t) ? `${new Date(t).toISOString().slice(11, 19)} UTC` : inline(String(at)) }
+const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+
+export function composeIssue(report: Draft, opts: ComposeOptions = {}): ComposedIssue {
+  // Never the sender's account key or an email, whatever the words say: the privacy catch should have held them, and this is the floor.
+  const key = text(report.who?.member)
+  const scrub = (s: string) => {
+    let out = s.replace(EMAIL, '[removed]')
+    if (key.length >= 12) out = out.split(key).join('[removed]')
+    return out
+  }
+  const words = scrub(text(report.words).trim())
+  const transcript = scrub(text(opts.transcript).trim())
+  // Only links the host produced, and only plain https ones, become images or links; anything else is still "being added".
+  const urls: Record<string, string> = opts.pending ? {} : Object.fromEntries(Object.entries(opts.attachmentUrls ?? {}).flatMap(([k, u]) => (safeUrl(u) ? [[k, u]] : [])))
+  const media = report.media ?? []
+  const voice = report.voice ?? []
+  const g = report.diagnostics ?? {}
+  const appName = opts.appName ?? report.appName
+  const has = new Set(pieces(report))
+  const carries = pieces(report)
+
+  // Everything not yet linked, counted, so the issue never claims to be complete before it is.
+  const missing = [...media, ...voice].filter((f) => !urls[f.file])
+  const waitImages = media.filter((m) => isImage(m) && !urls[m.file]).length
+  const waitVideos = media.filter((m) => isVideo(m) && !urls[m.file]).length
+  const waitVoice = voice.filter((v) => !urls[v.file]).length
+  const coming = missing.length
+    ? `${list([waitImages ? plural(waitImages, 'screenshot') : '', waitVideos ? plural(waitVideos, 'video') : '', waitVoice ? plural(waitVoice, 'voice recording') : ''].filter(Boolean))} ${missing.length === 1 ? 'is' : 'are'} being added.`
+    : ''
+
+  type TrailCut = { routes: number; taps: number; errors: number }
+  const full = { routes: report.context?.routes ?? [], taps: report.context?.taps ?? [], errors: report.context?.errors ?? [] }
+  const contact = contactOf(report)
+  // The trail is kept newest-last; a cut keeps the newest.
+  const shown = (k: keyof TrailCut, cut: TrailCut) => full[k].slice(cut[k])
+  const build = (said: string, heard: string, cut: TrailCut = { routes: 0, taps: 0, errors: 0 }): string => {
+    const out: string[] = []
+    if (has.has('words')) out.push('## What they said', fence(said), '')
+    if (has.has('voice')) {
+      out.push(transcript ? "## Voice note (transcribed on the owner's Mac)" : '## Voice note', heard ? fence(heard) : 'Not transcribed.')
+      const links = voice.filter((v) => urls[v.file]).map((v) => `[${inline(v.file)}](${urls[v.file]})`)
+      if (links.length) out.push('', ...links)
+      if (coming && !has.has('images') && !has.has('video')) out.push('', coming)
+      out.push('')
+    }
+    if (has.has('images') || has.has('video')) {
+      out.push('## Screenshots')
+      for (const m of media) {
+        const u = urls[m.file]
+        if (!u) continue
+        out.push(isImage(m) ? `![${inline(m.file)}](${u})` : `[${inline(m.file)}](${u})`)
+      }
+      if (coming) out.push(coming)
+      out.push('')
+    }
+    if (has.has('where')) {
+      out.push('## Where', [text(report.where?.screen) && `Screen: ${inline(text(report.where?.screen))}`, text(report.where?.route) && `Route: ${inline(text(report.where?.route))}`].filter(Boolean).join(' · '), '')
+    }
+    if (hasContext(report)) {
+      out.push('## Context (shared so this can be fixed)', '', '| What | Value | Why |', '| --- | --- | --- |')
+      if (has.has('app')) out.push(`| App | ${cell(`${appName ? `${appName} ` : ''}${text(g.appVersion)}`)} | so the fixer works on the same version you have |`)
+      for (const i of report.context!.items ?? []) out.push(`| ${cell(i.label)} | ${cell(i.value)} | ${cell(i.why)} |`)
+      out.push('')
+      const block = (k: keyof TrailCut, line: (x: never) => string) => {
+        if (!has.has(k)) return
+        const rows = shown(k, cut)
+        out.push(`<details><summary>${TRAIL_WORDS[k].heading} (${full[k].length})</summary>`, '')
+        if (cut[k]) out.push(`(The ${cut[k]} oldest were cut to fit GitHub's limit.)`, '')
+        out.push(...rows.map((x) => line(x as never)), '', '</details>', '')
+      }
+      block('routes', (r: { route: string; at: string }) => `- ${clock(r.at)} ${inline(r.route)}`)
+      block('taps', (t: { label: string; at: string }) => `- ${clock(t.at)} ${inline(t.label)}`)
+      block('errors', (e: { message: string; frame?: string; at: string }) => `- ${clock(e.at)} ${inline(e.message)}${e.frame ? `\n  ${inline(e.frame)}` : ''}`)
+    } else if (has.has('app') || has.has('device') || has.has('time')) {
+      const about = [
+        has.has('app') ? `App: ${inline(`${appName ? `${appName} ` : ''}${text(g.appVersion)}`)}` : '',
+        text(g.device) ? `Device: ${inline(text(g.device))}` : '',
+        text(g.screen) ? `Screen ${inline(text(g.screen))}` : '',
+        has.has('time') ? `Sent ${when(text(g.at))}` : '',
+      ].filter(Boolean)
+      out.push('## About', about.join(' · '), '')
+    }
+    if (has.has('contact') && contact) {
+      const ways = [
+        contact.email ? `[${linkText(contact.email)}](mailto:${encodeURIComponent(contact.email).replace(/%40/g, '@')})` : '',
+        contact.phone ? `[${linkText(contact.phone)}](tel:${contact.phone.replace(/[^\d+]/g, '')})` : '',
+        contact.handle ? inline(contact.handle) : '',
+      ].filter(Boolean)
+      out.push('## Reach them', 'To thank them or ask a follow-up question:', '', ...ways.map((w) => `- ${w}`), '')
+    }
+    const role = opts.filerRole ?? text(report.who?.role) ?? 'member'
+    // "Report <id>" is exact on purpose: the attachment relay reads the issue and requires this line before it saves a file.
+    out.push(FILED_BY, filedByLine(opts.filerName ?? report.filerName ?? 'A member', role || 'member', appName, text(report.id)))
+    return out.join('\n')
+  }
+
+  let said = words
+  let heard = transcript
+  const cut: TrailCut = { routes: 0, taps: 0, errors: 0 }
+  let body = build(said, heard, cut)
+  // Too long for GitHub: the trail gives way first (taps, then pages, then errors, oldest first), then the transcript,
+  // then the words, each with a note saying it was cut to fit.
+  for (const k of ['taps', 'routes', 'errors'] as const) {
+    while (body.length > BODY_LIMIT && cut[k] < full[k].length) {
+      cut[k] += Math.max(1, Math.ceil((full[k].length - cut[k]) / 2))
+      body = build(said, heard, cut)
+    }
+  }
+  if (body.length > BODY_LIMIT && heard) {
+    const keep = Math.max(0, heard.length - (body.length - BODY_LIMIT) - 200)
+    heard = `${heard.slice(0, keep)}\n\n(The transcript was cut here at ${keep} characters to fit GitHub's limit; the recording itself is attached.)`
+    body = build(said, heard, cut)
+  }
+  if (body.length > BODY_LIMIT && said) {
+    const keep = Math.max(0, said.length - (body.length - BODY_LIMIT) - 200)
+    said = `${said.slice(0, keep)}\n\n(Their words were cut here at ${keep} characters to fit GitHub's limit.)`
+    body = build(said, heard, cut)
+  }
+
+  // A title is plain text on GitHub; it still never pings anyone or links an issue.
+  const title = clip(firstSentence(words) || firstSentence(transcript) || `Suggestion from ${appName || 'an app'}`, 70).replace(/@(?=[\w-])/g, '@‍').replace(/#(?=\d)/g, '#‍')
+  const appLabel = opts.appLabel === null ? '' : opts.appLabel !== undefined ? slug(opts.appLabel) : appName ? slug(appName) : ''
+  const labels = [LABEL[text(report.kind)] ?? 'feedback', ...(appLabel ? [`app:${appLabel}`] : [])]
+  return { title, body, labels, carries }
+}

package/src/github/filer.ts

@@ -0,0 +1,96 @@
+// THE FILER'S SIDE OF A SUGGESTION RELAY. `relayFiler` talks to any relay running `createSuggestionRelay`, at whatever
+// URL it is mounted on and with whatever header it checks. `canFileDirectly` says whether a filer's own token can see
+// the repo (and so open an issue there); `fileSuggestion` uses it to choose between filing directly and the relay.
+import { github, GitHubError, type Fetch } from './api.ts'
+import { toBase64 } from './hosts.ts'
+
+export interface RelayFile { name: string; type: string; bytes: Uint8Array | ArrayBuffer | string }
+export interface RelayFiling {
+  repo: string
+  /** Which of the relay's apps this came from, by its id in the relay's own table (the relay names it and labels it). */
+  app?: string
+  /** The report, in the contract's shape. The relay never writes the account id into the issue. */
+  report: Record<string, unknown>
+  /** The name the issue says it was filed by. */
+  filerName?: string
+  appName?: string
+  appVersion?: string
+  transcript?: string
+  files?: RelayFile[]
+  /** True once the filer chose to file without what the privacy catch flagged (they replaced it themselves). */
+  redacted?: boolean
+}
+export interface RelayFiler {
+  /** Answers the issue; a repeat of the same report answers the same issue. A held report throws status 409 with `{ held, hits }`. */
+  file(input: RelayFiling): Promise<{ number: number; url: string }>
+  followUp(input: { repo: string; number: number; reportId: string; words?: string; transcript?: string; files?: RelayFile[]; redacted?: boolean }): Promise<{ id: number; url: string }>
+  status(items: { repo: string; number: number }[]): Promise<{ repo: string; number: number; status: string; reason?: string }[]>
+  /** What the relay can take (asked once, then kept). */
+  capabilities(): Promise<RelayCapabilities>
+}
+
+const files64 = (files: RelayFile[] = []) => files.map((f) => ({ name: f.name, type: f.type, bytes: typeof f.bytes === 'string' ? f.bytes : toBase64(f.bytes) }))
+/** Files larger than this go to the relay staged (one signed PUT each) rather than inside the request. */
+export const STAGE_OVER_BYTES = 2 * 2 ** 20
+const sizeOf = (b: RelayFile['bytes']) => (typeof b === 'string' ? Math.floor((b.length * 3) / 4) : b instanceof Uint8Array ? b.length : b.byteLength)
+const raw = (b: RelayFile['bytes']): Uint8Array => {
+  if (b instanceof Uint8Array) return b
+  if (b instanceof ArrayBuffer) return new Uint8Array(b)
+  const bin = atob(b); const out = new Uint8Array(bin.length); for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i); return out
+}
+export interface RelayCapabilities { actions: string[]; staging: boolean; inlineBytes: number; maxBytes?: Record<string, number> }
+
+/** `url` is where the relay is mounted; each action is posted to `<url>/<action>`. */
+export function relayFiler({ url, headers = {}, fetch }: { url: string; headers?: Record<string, string>; fetch?: Fetch }): RelayFiler {
+  if (!/^https?:\/\//.test(url)) throw new Error(`${JSON.stringify(url)} is not a relay URL`)
+  const base = url.replace(/\/+$/, '')
+  const f = fetch ?? globalThis.fetch
+  const call = async (action: string, body: unknown) => {
+    const res = await f(`${base}/${action}`, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify(body) })
+    const text = await res.text()
+    let parsed: any = null
+    try { parsed = text ? JSON.parse(text) : null } catch { parsed = text }
+    if (!res.ok) throw new GitHubError(`the suggestion relay answered ${res.status} to ${action}`, res.status, parsed)
+    return parsed
+  }
+  let caps: Promise<RelayCapabilities> | null = null
+  const capabilities = () => (caps ??= (async () => {
+    const res = await f(`${base}/capabilities`, { method: 'GET', headers })
+    if (!res.ok) throw new GitHubError(`the suggestion relay answered ${res.status} to capabilities`, res.status, null)
+    return (await res.json()) as RelayCapabilities
+  })().catch((e) => { caps = null; throw e }))
+  /** Each file inline, or, past STAGE_OVER_BYTES, put to a link from upload-url first and named as staged. A file the
+   *  relay cannot take at all is refused here, in words, before anything is filed. */
+  async function prepare(repo: string, reportId: string, files: RelayFile[] = []) {
+    if (!files.some((x) => sizeOf(x.bytes) > STAGE_OVER_BYTES)) return files64(files)
+    const c = await capabilities()
+    const out: Record<string, unknown>[] = []
+    for (const x of files) {
+      const size = sizeOf(x.bytes)
+      if (size <= Math.min(STAGE_OVER_BYTES, c.inlineBytes)) { out.push(...files64([x])); continue }
+      if (!c.staging) throw new Error(`${x.name} is larger than this relay takes in one request (${Math.round(c.inlineBytes / 2 ** 20)} MB), and it has no staging for larger files`)
+      const link = (await call('upload-url', { repo, reportId, name: x.name, type: x.type, bytes: size })) as { url: string; headers?: Record<string, string> }
+      const put = await f(link.url, { method: 'PUT', headers: link.headers ?? {}, body: raw(x.bytes) as BodyInit })
+      if (!put.ok) throw new GitHubError(`the staging upload of ${x.name} answered ${put.status}`, put.status, null)
+      out.push({ name: x.name, type: x.type, staged: x.name })
+    }
+    return out
+  }
+  return {
+    capabilities,
+    async file(input) { return call('file', { ...input, files: await prepare(input.repo, String(input.report.id), input.files) }) },
+    async followUp(input) { return call('follow-up', { ...input, files: await prepare(input.repo, input.reportId, input.files) }) },
+    async status(items) { return (await call('status', { items })).items },
+  }
+}
+
+/** True when this token can see the repo, so it can open an issue there itself; false on 401, 403 or 404 (or issues off). */
+export async function canFileDirectly({ repo, token, fetch, api }: { repo: string; token: string; fetch?: Fetch; api?: string }): Promise<boolean> {
+  try {
+    const got = await github({ token, fetch, api }, 'GET', `/repos/${repo}`)
+    return got.body?.has_issues !== false
+  } catch (e) {
+    if (e instanceof GitHubError && [401, 403, 404].includes(e.status)) return false
+    throw e
+  }
+}

package/src/github/hosts.ts

@@ -0,0 +1,117 @@
+// WHERE A SCREENSHOT OR RECORDING GOES (design: "Attachment parity for every filer"). GitHub has no API for attaching a
+// file to an issue, so each file is committed to the repo's own `suggestion-attachments` branch and linked: it shows to
+// exactly the people who can read the repo, and to nobody else. Two hosts ship: one for a filer that can push, one
+// through the repo owner's own GitHub App, by way of a suggestion relay, for everyone who cannot.
+import { isRepoName } from '../contract.mjs'
+import { github, GitHubError, type Fetch } from './api.ts'
+
+/** Which issue a file belongs to. The relay reads that issue and requires it to carry `Report <reportId>`. */
+export interface AttachmentTarget { repo: string; issue: number; reportId: string }
+export interface AttachmentFile { name: string; type: string; bytes: Uint8Array | ArrayBuffer }
+export interface AttachmentHost { put(target: AttachmentTarget, file: AttachmentFile): Promise<{ url: string }> }
+
+export const ATTACHMENTS_BRANCH = 'suggestion-attachments'
+/** Up to this size a file goes through the contents API; past it, through the git data API (blob, tree, commit). */
+export const CONTENTS_API_BYTES = 1_000_000
+const REPORT_ID = /^r-\d{14}-[a-z0-9]{6}$/
+const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+/** Base64 with no dependency and no reliance on btoa's string rules. */
+export function toBase64(bytes: Uint8Array | ArrayBuffer): string {
+  const b = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+  let out = ''
+  for (let i = 0; i < b.length; i += 3) {
+    const n = (b[i] << 16) | ((b[i + 1] ?? 0) << 8) | (b[i + 2] ?? 0)
+    out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63] + (i + 1 < b.length ? B64[(n >> 6) & 63] : '=') + (i + 2 < b.length ? B64[n & 63] : '=')
+  }
+  return out
+}
+
+/** Refuses anything that would write outside attachments/<report id>/<file>. */
+function pathFor(t: AttachmentTarget, name: string): string {
+  if (!isRepoName(t.repo)) throw new Error(`${JSON.stringify(t.repo)} is not owner/name`)
+  if (!REPORT_ID.test(String(t.reportId))) throw new Error(`${JSON.stringify(t.reportId)} is not a report id`)
+  if (!FILE.test(name)) throw new Error(`${JSON.stringify(name)} is not a plain file name`)
+  return `attachments/${t.reportId}/${name}`
+}
+/** The link form that renders inline in a private issue, for the people who can read the repo. */
+export const attachmentUrl = (repo: string, branch: string, path: string) => `https://github.com/${repo}/blob/${branch}/${path}?raw=true`
+
+/** Commits each file through the contents API with a token that can push (a maintainer's Mac, an app server's own key).
+ *  The branch is made the first time, as an orphan that shares no history with the code. A path already written is its link. */
+export function branchHost({ repo, token, branch = ATTACHMENTS_BRANCH, fetch, refuseExisting = false }: { repo: string; token: string; branch?: string; fetch?: Fetch; /** Throw (409) instead of answering the link when the path is already written. */ refuseExisting?: boolean }): AttachmentHost {
+  const cfg = { token, fetch }
+  let ready: Promise<void> | null = null
+  const ensure = () => (ready ??= (async () => {
+    try { await github(cfg, 'GET', `/repos/${repo}/git/ref/heads/${branch}`); return } catch (e) { if (!(e instanceof GitHubError) || e.status !== 404) throw e }
+    const tree = await github(cfg, 'POST', `/repos/${repo}/git/trees`, { tree: [{ path: 'README.md', mode: '100644', type: 'blob', content: 'Screenshots and recordings attached to suggestions filed as issues on this repo, one folder per report. Nothing here is code.\n' }] })
+    const commit = await github(cfg, 'POST', `/repos/${repo}/git/commits`, { message: 'Start the suggestion attachments branch', tree: tree.body.sha, parents: [] })
+    try { await github(cfg, 'POST', `/repos/${repo}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.body.sha }) } catch (e) { if (!(e instanceof GitHubError) || e.status !== 422) throw e }
+  })().catch((e) => { ready = null; throw e }))
+  /** A file past the contents API's comfortable size, through the git data API: a blob, a tree on top of the branch's
+   *  own, a commit, and the branch moved to it (once more if another write moved it first). Up to GitHub's 100 MB. */
+  async function putLarge(path: string, file: AttachmentFile, reportId: string) {
+    try {
+      await github(cfg, 'GET', `/repos/${repo}/contents/${path}?ref=${branch}`)
+      if (refuseExisting) throw new GitHubError(`${path} is already written`, 409, null)
+      return // written once: its link stands
+    } catch (e) { if (!(e instanceof GitHubError) || e.status !== 404) throw e }
+    const blob = (await github(cfg, 'POST', `/repos/${repo}/git/blobs`, { content: toBase64(file.bytes), encoding: 'base64' })).body.sha as string
+    for (let attempt = 0; ; attempt++) {
+      const head = (await github(cfg, 'GET', `/repos/${repo}/git/ref/heads/${branch}`)).body.object.sha as string
+      const base = (await github(cfg, 'GET', `/repos/${repo}/git/commits/${head}`)).body.tree.sha as string
+      const tree = (await github(cfg, 'POST', `/repos/${repo}/git/trees`, { base_tree: base, tree: [{ path, mode: '100644', type: 'blob', sha: blob }] })).body.sha as string
+      const commit = (await github(cfg, 'POST', `/repos/${repo}/git/commits`, { message: `Attach ${file.name} to ${reportId}`, tree, parents: [head] })).body.sha as string
+      try { await github(cfg, 'PATCH', `/repos/${repo}/git/refs/heads/${branch}`, { sha: commit }); return }
+      catch (e) { if (!(e instanceof GitHubError) || e.status !== 422 || attempt >= 2) throw e } // someone else moved the branch: build on theirs
+    }
+  }
+  return {
+    async put(target, file) {
+      if (target.repo !== repo) throw new Error(`this host writes to ${repo}, not ${target.repo}`)
+      const path = pathFor(target, file.name)
+      await ensure()
+      const size = file.bytes instanceof Uint8Array ? file.bytes.length : file.bytes.byteLength
+      if (size > CONTENTS_API_BYTES) {
+        await putLarge(path, file, target.reportId)
+        return { url: attachmentUrl(repo, branch, path) }
+      }
+      try {
+        await github(cfg, 'PUT', `/repos/${repo}/contents/${path}`, { message: `Attach ${file.name} to ${target.reportId}`, content: toBase64(file.bytes), branch })
+      } catch (e) {
+        if (!(e instanceof GitHubError) || e.status !== 422) throw e
+        // A 422 means "already there" only if it is there: look, and pass any other refusal on as it came.
+        let there = false
+        try { await github(cfg, 'GET', `/repos/${repo}/contents/${path}?ref=${branch}`); there = true } catch (g) { if (!(g instanceof GitHubError) || g.status !== 404) throw g }
+        if (!there) throw e
+        if (refuseExisting) throw new GitHubError(`${path} is already written`, 409, e.body)
+      }
+      return { url: attachmentUrl(repo, branch, path) }
+    },
+  }
+}
+
+/** For a filer who cannot push: the file goes to an attachment relay (any URL running `createAttachRelay`, with whatever
+ *  header proves who is asking), which checks the named issue carries this report, saves the file through its own
+ *  GitHub App, and answers the link. */
+export function relayHost({ url, headers = {}, fetch }: { url: string; headers?: Record<string, string>; fetch?: Fetch }): AttachmentHost {
+  const f = fetch ?? globalThis.fetch
+  if (!/^https?:\/\//.test(url)) throw new Error(`${JSON.stringify(url)} is not a relay URL`)
+  return {
+    async put(target, file) {
+      pathFor(target, file.name)
+      const res = await f(url, {
+        method: 'POST',
+        headers: { ...headers, 'content-type': 'application/json' },
+        body: JSON.stringify({ repo: target.repo, issue: target.issue, reportId: target.reportId, name: file.name, type: file.type, bytes: toBase64(file.bytes) }),
+      })
+      const text = await res.text()
+      let body: any = null
+      try { body = text ? JSON.parse(text) : null } catch { body = text }
+      if (!res.ok) throw new GitHubError(`the attachment relay answered ${res.status}`, res.status, body)
+      if (typeof body?.url !== 'string' || !body.url.startsWith(`https://github.com/${target.repo}/`)) throw new Error('the attachment relay did not answer a github.com link in this repo')
+      return { url: body.url }
+    },
+  }
+}

package/src/github/index.ts

@@ -0,0 +1,15 @@
+// "@supersuit/suggest-a-change/github": a suggestion becomes one ordinary GitHub issue. Zero runtime dependencies,
+// web-standard fetch (injectable). Used straight from an app's server (createReportHandlers' `github` option) or by the
+// owner's Mac with `gh`'s token.
+export { privacyCatch, redact, mayFileAsIs, normalize } from './privacy.ts'
+export type { Hit, HitKind, Person, CatchOptions } from './privacy.ts'
+export { composeIssue, whatGoes, destinationWords, pieces, BODY_LIMIT, filedByLine, endsWithFiledBy, FILED_BY } from './compose.ts'
+export type { Piece, Destination, Draft, ComposeOptions, ComposedIssue } from './compose.ts'
+export { fileIssue, updateIssue, addFollowUp, issueStates, issueStatus, fileSuggestion, attachPending, github, GitHubError } from './api.ts'
+export type { GitHubConfig, FilingConfig, IssueState, FileSuggestionInput, FiledSuggestion, Fetch } from './api.ts'
+export { branchHost, relayHost, toBase64, attachmentUrl, ATTACHMENTS_BRANCH, CONTENTS_API_BYTES } from './hosts.ts'
+export type { AttachmentHost, AttachmentTarget, AttachmentFile } from './hosts.ts'
+export { createSuggestionRelay, createAttachRelay, memoryUsage, RELAY_LIMITS, RELAY_VOICE_BYTES, FILING_LEASE_MS } from './relay.ts'
+export type { SuggestionRelayOptions, AttachRelayOptions, RelayLimits, RelayUsage, RelayIdentity, Reservation, FiledRecord, StagingAdapter } from './relay.ts'
+export { relayFiler, canFileDirectly, STAGE_OVER_BYTES } from './filer.ts'
+export type { RelayFiler, RelayFiling, RelayFile, RelayCapabilities } from './filer.ts'