@supersuit/suggest-a-change 0.1.12 → 0.2.0

package/dist/github/api.js

@@ -0,0 +1,164 @@
+// THE GITHUB CALLS. Web-standard fetch only, injectable so tests and any runtime can pass their own. The token is the
+// filer's (`gh auth token` on a Mac) or an app server's own; it is sent to api.github.com and nowhere else.
+import { isRepoName } from '../contract.mjs';
+import { composeIssue } from './compose.js';
+/** An issue carries at most this many labels (the composer writes two). */
+const MAX_LABELS = 10;
+import { canFileDirectly } from './filer.js';
+export class GitHubError extends Error {
+    status;
+    body;
+    constructor(message, status, body) { super(message); this.name = 'GitHubError'; this.status = status; this.body = body; }
+}
+const API = 'https://api.github.com';
+function repoOf(repo) {
+    if (!isRepoName(repo))
+        throw new Error(`${JSON.stringify(repo)} is not owner/name`);
+    return repo;
+}
+/** One REST call. Answers the parsed body, or throws a GitHubError carrying GitHub's status. */
+export async function github(cfg, method, path, body) {
+    const f = cfg.fetch ?? globalThis.fetch;
+    const res = await f(`${cfg.api ?? API}${path}`, {
+        method,
+        headers: {
+            accept: 'application/vnd.github+json',
+            authorization: `Bearer ${cfg.token}`,
+            'x-github-api-version': '2022-11-28',
+            ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    const textBody = await res.text();
+    let parsed = null;
+    try {
+        parsed = textBody ? JSON.parse(textBody) : null;
+    }
+    catch {
+        parsed = textBody;
+    }
+    if (!res.ok)
+        throw new GitHubError(`GitHub answered ${res.status} to ${method} ${path}`, res.status, parsed);
+    return { status: res.status, body: parsed };
+}
+const COLORS = { bug: 'd73a4a', enhancement: 'a2eeef', feedback: 'c5def5' };
+/** Opens one issue. Missing labels are created first; one that exists (422) or that this account may not create
+ *  (403/404: a read-only filer) is skipped, and GitHub then keeps only the labels the filer may set. */
+export async function fileIssue(cfg, issue) {
+    const repo = repoOf(cfg.repo);
+    const labels = issue.labels.filter((l) => typeof l === 'string' && l.length && l.length <= 50).slice(0, MAX_LABELS);
+    for (const name of labels) {
+        try {
+            await github(cfg, 'POST', `/repos/${repo}/labels`, { name, color: COLORS[name] ?? 'ededed' });
+        }
+        catch (e) {
+            if (!(e instanceof GitHubError) || ![403, 404, 422].includes(e.status))
+                throw e;
+        }
+    }
+    const got = await github(cfg, 'POST', `/repos/${repo}/issues`, { title: issue.title, body: issue.body, labels });
+    return { number: got.body.number, url: got.body.html_url };
+}
+/** Replaces an issue's body (the filer's own issue: read access is enough to edit what you opened). */
+export async function updateIssue(cfg, number, change) {
+    await github(cfg, 'PATCH', `/repos/${repoOf(cfg.repo)}/issues/${number}`, { body: change.body });
+}
+/** A follow-up the person added later, as a comment on the same issue. */
+export async function addFollowUp(cfg, number, body) {
+    const got = await github(cfg, 'POST', `/repos/${repoOf(cfg.repo)}/issues/${number}/comments`, { body });
+    return { id: got.body.id, url: got.body.html_url };
+}
+/** The state of many issues in one GraphQL call (in chunks of 50). Repo names travel as variables, never in the query. */
+export async function issueStates(cfg, issues) {
+    const out = [];
+    for (let start = 0; start < issues.length; start += 50) {
+        const chunk = issues.slice(start, start + 50);
+        const vars = {};
+        const decl = [];
+        const parts = [];
+        chunk.forEach((it, i) => {
+            const [owner, name] = repoOf(it.repo).split('/');
+            if (!Number.isInteger(it.number) || it.number < 1)
+                throw new Error(`${it.number} is not an issue number`);
+            vars[`o${i}`] = owner;
+            vars[`n${i}`] = name;
+            vars[`k${i}`] = it.number;
+            decl.push(`$o${i}: String!, $n${i}: String!, $k${i}: Int!`);
+            parts.push(`i${i}: repository(owner: $o${i}, name: $n${i}) { issue(number: $k${i}) { state stateReason comments(last: 1) { nodes { body } } } }`);
+        });
+        const query = `query(${decl.join(', ')}) { ${parts.join(' ')} }`;
+        const got = await github(cfg, 'POST', '/graphql', { query, variables: vars });
+        const data = got.body?.data;
+        if (!data)
+            throw new GitHubError('GitHub answered no data to the issue state query', got.status, got.body);
+        chunk.forEach((it, i) => {
+            const issue = data[`i${i}`]?.issue;
+            if (!issue) {
+                out.push({ repo: it.repo, number: it.number, state: null, stateReason: null, missing: true });
+                return;
+            }
+            const row = { repo: it.repo, number: it.number, state: issue.state, stateReason: issue.stateReason ?? null };
+            const last = issue.comments?.nodes?.at(-1)?.body;
+            const line = typeof last === 'string' ? last.trim().split('\n')[0].trim() : '';
+            if (String(issue.state).toUpperCase() === 'CLOSED' && line)
+                row.reason = line;
+            out.push(row);
+        });
+    }
+    return out;
+}
+/** GitHub's state onto the person's three: open, done (closed as completed), not planned (as not planned, or a duplicate). */
+export function issueStatus({ state, stateReason }) {
+    if (String(state).toUpperCase() !== 'CLOSED')
+        return 'open';
+    return ['NOT_PLANNED', 'DUPLICATE'].includes(String(stateReason).toUpperCase()) ? 'not-planned' : 'done';
+}
+const reportFiles = (r) => [...(r.media ?? []), ...(r.voice ?? [])].map((f) => f.file);
+/** Saves the files the issue is still waiting for, then edits their links into the body. Call again later with the
+ *  same `attached` to finish what failed: the issue keeps saying a file is coming until it is there. */
+export async function attachPending(cfg, input) {
+    const attached = { ...(input.attached ?? {}) };
+    const wanted = new Set(reportFiles(input.report));
+    let added = 0;
+    if (input.attachments) {
+        for (const f of input.files) {
+            if (!wanted.has(f.name) || attached[f.name])
+                continue;
+            try {
+                attached[f.name] = (await input.attachments.put({ repo: cfg.repo, issue: input.number, reportId: String(input.report.id), }, f)).url;
+                added++;
+            }
+            catch { /* left pending: the issue still says it is coming, and a later call retries it */ }
+        }
+    }
+    if (added)
+        await updateIssue(cfg, input.number, { body: composeIssue(input.report, { ...input.compose, attachmentUrls: attached }).body });
+    return { attached, pending: [...wanted].filter((n) => !attached[n]) };
+}
+/** The whole filing. With a token that can see the repo it files directly, in the order that never shows an incomplete
+ *  issue as complete: open the issue saying what is being added (opening it is the proof the filer can file there),
+ *  save each file against that issue, then edit the links in. With no token, or one that cannot see the repo, and a
+ *  `relay`, the relay files it (the files, then the issue, as its App) for someone with no access at all. */
+export async function fileSuggestion(cfg, input) {
+    const direct = cfg.token ? (!cfg.relay || await canFileDirectly({ repo: cfg.repo, token: cfg.token, fetch: cfg.fetch, api: cfg.api })) : false;
+    if (!direct) {
+        if (!cfg.relay)
+            throw new Error('fileSuggestion needs a token that can file on the repo, or a relay');
+        const made = await cfg.relay.file({
+            repo: cfg.repo, ...(cfg.app ? { app: cfg.app } : {}), report: input.report, files: input.files,
+            ...(input.compose?.filerName ? { filerName: input.compose.filerName } : {}),
+            ...(input.compose?.appName ? { appName: input.compose.appName } : {}),
+            ...(input.compose?.appVersion ? { appVersion: input.compose.appVersion } : {}),
+            ...(input.compose?.transcript ? { transcript: input.compose.transcript } : {}),
+        });
+        return { ...made, attached: {}, pending: [], via: 'relay' };
+    }
+    const own = { ...cfg, token: cfg.token };
+    const hasFiles = reportFiles(input.report).length > 0;
+    const first = composeIssue(input.report, { ...input.compose, pending: hasFiles });
+    const issue = await fileIssue(own, first);
+    if (!hasFiles)
+        return { ...issue, attached: {}, pending: [], via: 'direct' };
+    const rest = await attachPending(own, { ...input, number: issue.number });
+    return { ...issue, ...rest, via: 'direct' };
+}

package/dist/github/compose.d.ts

@@ -0,0 +1,152 @@
+/** 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 declare const BODY_LIMIT = 65000;
+/** Which pieces a report carries, in the order the issue and the list both use. */
+export declare function pieces(d: Draft): Piece[];
+export declare const TRAIL_WORDS: {
+    routes: {
+        label: string;
+        heading: string;
+        why: string;
+    };
+    taps: {
+        label: string;
+        heading: string;
+        why: string;
+    };
+    errors: {
+        label: string;
+        heading: string;
+        why: string;
+    };
+};
+export declare const CONTACT_WHY = "so whoever fixes it can thank you or ask a follow-up question";
+export declare const PUBLIC_CONTACT_REASON = "this repo is public, so anyone could read it";
+/** 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 declare function whatGoes(draft: Draft, destination: Destination): GoesItem[];
+/** The lines around the list: where it files, who can read it there, and whose account files it. */
+export declare function destinationWords(d: Destination): {
+    headline: string;
+    privacy: string;
+    danger: boolean;
+    account: string;
+};
+/** 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 declare const FILED_BY = "## Filed by";
+export declare function filedByLine(filer: string, role: string, appName: string | undefined, reportId: string): string;
+/** Whether an issue's body ends with the composer's own Filed by line for this report, in either of its forms. */
+export declare function endsWithFiledBy(body: string, reportId: string): boolean;
+export declare function composeIssue(report: Draft, opts?: ComposeOptions): ComposedIssue;

package/dist/github/compose.js

@@ -0,0 +1,309 @@
+// 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.
+/** GitHub refuses a body of 65536 characters or more; this leaves room. */
+export const BODY_LIMIT = 65_000;
+const LABEL = { change: 'enhancement', broken: 'bug', feedback: 'feedback' };
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+const isImage = (m) => String(m.type).startsWith('image/');
+const isVideo = (m) => String(m.type).startsWith('video/');
+const text = (v) => (typeof v === 'string' ? v : '');
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const list = (parts) => (parts.length <= 1 ? parts.join('') : `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`);
+const contactOf = (d) => {
+    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) => 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) {
+    const media = d.media ?? [];
+    const g = d.diagnostics ?? {};
+    const out = [];
+    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) => [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, destination) {
+    const ctxItems = new Map((draft.context?.items ?? []).map((i) => [`ctx:${i.key}`, i]));
+    const contact = contactOf(draft);
+    const trailCount = (k) => (draft.context?.[k] ?? []).length;
+    const trailUnit = { routes: 'page', taps: 'tap', errors: 'error' };
+    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, destination) {
+    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) => (n < 2 ** 20 ? `${Math.max(1, Math.round(n / 1024))} KB` : `${Math.round((n / 2 ** 20) * 10) / 10} MB`);
+    const tooBig = (files) => {
+        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 = {
+        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) {
+    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) {
+    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) {
+    const line = s.trim().split('\n')[0].trim();
+    const m = /^.*?[.!?](?=\s|$)/.exec(line);
+    return (m ? m[0] : line).trim();
+}
+function clip(s, max) {
+    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(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) => 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) => 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) => {
+    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) => 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) => (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, role, appName, reportId) {
+    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, reportId) {
+    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) => { const t = Date.parse(at); return Number.isFinite(t) ? `${new Date(t).toISOString().slice(11, 19)} UTC` : inline(String(at)); };
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+export function composeIssue(report, opts = {}) {
+    // 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) => {
+        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 = 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.`
+        : '';
+    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, cut) => full[k].slice(cut[k]);
+    const build = (said, heard, cut = { routes: 0, taps: 0, errors: 0 }) => {
+        const out = [];
+        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, line) => {
+                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)), '', '</details>', '');
+            };
+            block('routes', (r) => `- ${clock(r.at)} ${inline(r.route)}`);
+            block('taps', (t) => `- ${clock(t.at)} ${inline(t.label)}`);
+            block('errors', (e) => `- ${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 = { 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']) {
+        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 };
+}