ultra11y 2.32.0 → 3.0.0

package/src/mcp/tools.ts

@@ -89,6 +89,28 @@ export const TOOLS: ToolDecl[] = [
       required: ["cwd"],
     },
   },
+  {
+    name: "ultra11y_tickets",
+    title: "Preview the tracker tickets an audit would file",
+    description:
+      "Show the GitHub/GitLab/Jira tickets this audit would open, at a granularity you choose: one per criterion (default), per page, per page+criterion, per " +
+      "file, or one consolidated. Returns the plan ONLY — it never creates anything; filing stays a deliberate `ultra11y tickets` run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cwd: cwdProp,
+        globs: globsProp,
+        standard: standardProp,
+        lang: langProp,
+        grain: {
+          type: "string",
+          enum: ["criterion", "page", "page-criterion", "single", "file"],
+          description: "What ONE ticket is. Default 'criterion'.",
+        },
+      },
+      required: ["cwd"],
+    },
+  },
   {
     name: "ultra11y_criteria",
     title: "The offline standards reference",
@@ -302,6 +324,11 @@ export const TOOL_META: Record<string, { write?: boolean; destructive?: boolean;
   ultra11y_audit: { openWorld: false },
   ultra11y_report: { openWorld: false },
   ultra11y_prd: { openWorld: false },
+  // READ-ONLY and closed-world by construction: it returns the ticket PLAN and never files
+  // anything, so it neither touches the project nor reaches a tracker. Filing stays a
+  // deliberate `ultra11y tickets` run — an agent must not be able to open issues in
+  // somebody's tracker off the back of a prompt injection.
+  ultra11y_tickets: { openWorld: false },
   ultra11y_criteria: { openWorld: false },
   ultra11y_check: { openWorld: false },
   ultra11y_verify: { openWorld: false },

package/src/pages.ts

@@ -225,6 +225,19 @@ const L = {
   },
 } as const;
 
+/** Honesty rule 2, as one sentence: a page with no snapshot cannot earn conformity by
+ *  silence. Exported so the grid, the per-page report AND the page-grain ticket all say the
+ *  SAME thing — one string, several readers, no drift. Undefined for a snapshot page, which
+ *  needs no caveat. */
+export function pageBasisWarning(basis: PageScope["basis"], lang: Lang): string | undefined {
+  return basis === "snapshot" ? undefined : L[lang].basisNote;
+}
+
+/** Honesty rule 1, as one sentence: findings no page could claim are reported, never spread. */
+export function unattributedNote(n: number, lang: Lang): string {
+  return L[lang].unattributed(n);
+}
+
 interface Row {
   id: string;
   label: string;

package/src/pr-comment.ts

@@ -0,0 +1,78 @@
+// THE STICKY PULL-REQUEST COMMENT — a REPORT surface, not a ticket.
+//
+// A CI run that appends a new comment every push turns a busy PR into a wall of stale
+// audits. This posts ONE comment and EDITS it on every subsequent run, keyed by an invisible
+// marker. The marker is per-standard, so a WCAG run and an RGAA run coexist instead of
+// overwriting one another (the same reason SARIF runs carry distinct automationDetails ids).
+//
+// It deliberately lives outside src/tickets/: it has no title, no de-dupe key, no labels and
+// no grain, so folding it into `TicketProvider` would force GitLab and Jira to stub a
+// `comment()` method they have no business implementing. It serves `report --format github`.
+import type { StandardId } from "./standards/index.js";
+import { ghExec, ghErrorReason } from "./gh-cli.js";
+
+/** The hidden key identifying this tool's comment for a given standard. */
+export function COMMENT_MARKER(standard: StandardId): string {
+  return `<!-- ultra11y:report standard="${standard}" -->`;
+}
+
+export function stickyBody(markdown: string, standard: StandardId): string {
+  return `${COMMENT_MARKER(standard)}\n${markdown}`;
+}
+
+/** The pull request to comment on: an explicit override, else the number GitHub Actions puts
+ *  in GITHUB_REF on a pull_request event. Undefined off a PR — the caller then skips, rather
+ *  than commenting on some unrelated issue. */
+export function prNumberFromEnv(env: Record<string, string | undefined> = process.env): number | undefined {
+  const explicit = Number.parseInt(env.ULTRA11Y_PR ?? "", 10);
+  if (Number.isFinite(explicit) && explicit > 0) return explicit;
+  const m = /^refs\/pull\/(\d+)\//.exec(env.GITHUB_REF ?? "");
+  const n = m ? Number.parseInt(m[1] as string, 10) : Number.NaN;
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+export interface IssueComment {
+  id: number;
+  body?: string;
+}
+
+/** This tool's own previous comment for this standard, if any. Never adopts a human's comment
+ *  nor another standard's — an edit is destructive, so the match must be exact. */
+export function pickExistingComment(comments: IssueComment[], marker: string): IssueComment | undefined {
+  return comments.find((c) => typeof c.body === "string" && c.body.includes(marker));
+}
+
+export interface CommentResult {
+  ok: boolean;
+  action: "created" | "updated" | "skipped";
+  reason?: string;
+}
+
+/** Post (or update) the audit summary on the current pull request. Best-effort: with no `gh`,
+ *  no auth or no PR, it reports `skipped` and the caller carries on — a comment is never
+ *  worth failing a build over. */
+export function pushPrComment(markdown: string, standard: StandardId = "wcag"): CommentResult {
+  const pr = prNumberFromEnv();
+  if (pr === undefined) return { ok: true, action: "skipped", reason: "not a pull-request run" };
+  const marker = COMMENT_MARKER(standard);
+  const body = stickyBody(markdown, standard);
+  try {
+    const repo = ghExec(["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"]).trim();
+    let existing: IssueComment | undefined;
+    try {
+      const raw = ghExec(["api", `repos/${repo}/issues/${pr}/comments`, "--paginate"]);
+      existing = pickExistingComment(JSON.parse(raw) as IssueComment[], marker);
+    } catch {
+      // Listing failed (permissions, rate limit) — fall through and CREATE. A duplicate
+      // comment is a far smaller harm than dropping the report entirely.
+    }
+    if (existing) {
+      ghExec(["api", "--method", "PATCH", `repos/${repo}/issues/comments/${existing.id}`, "-f", `body=${body}`]);
+      return { ok: true, action: "updated" };
+    }
+    ghExec(["api", "--method", "POST", `repos/${repo}/issues/${pr}/comments`, "-f", `body=${body}`]);
+    return { ok: true, action: "created" };
+  } catch (e) {
+    return { ok: false, action: "skipped", reason: ghErrorReason(e) };
+  }
+}

package/src/tickets/grain.ts

@@ -0,0 +1,218 @@
+// THE GRAIN — one PURE function from an audit to a list of tickets.
+//
+// No fs, no network, no console, no process.exit, no Date.now. Everything it needs is on the
+// AuditResult. That is what makes the ticket engine testable without a tracker, and what
+// makes "decoupled" mean something: the providers below it never see a Finding, and this
+// file never sees an HTTP request.
+//
+// It takes an AuditResult and NOT a PrdUnit[] on purpose: the page and file grains need
+// `scope.pages`, `packFindings` and `pageView`, all of which `prdUnits()` has already
+// discarded by the time it returns.
+import type { AuditResult, Finding, Lang, PageResult, Severity } from "../types.js";
+import { resolveMessage } from "../messages.js";
+import { repoRelative } from "../util.js";
+import { type PrdUnit, prdUnits } from "../prd.js";
+import { renderAuditorBacklog } from "../auditor.js";
+import { attributePages, derivePages, pageBasisWarning, pageView, pagesOf, unattributedFindings, unattributedNote } from "../pages.js";
+import { type GrainOptions, type Ticket, type TicketOccurrence, type TicketPlan, UNATTRIBUTED_ID } from "./types.js";
+import {
+  clampBody,
+  criterionTitle,
+  fileTitle,
+  filePreamble,
+  labelsFor,
+  pageCriterionTitle,
+  pagePreamble,
+  pageTitle,
+  renderCriterionBody,
+  singleTitle,
+  standardTag,
+  unattributedTitle,
+} from "./render.js";
+
+const SEV_RANK: Record<Severity, number> = { bloquant: 0, majeur: 1, mineur: 2 };
+
+/** The most severe severity in a set — the ticket's own. Empty ⇒ `mineur`, the least
+ *  alarming default, so an empty group can never masquerade as blocking. */
+function worstOf(items: { severity: Severity }[]): Severity {
+  return items.reduce<Severity>((worst, x) => (SEV_RANK[x.severity] < SEV_RANK[worst] ? x.severity : worst), "mineur");
+}
+
+/** A view of the audit restricted to one FILE. Deliberately does NOT touch `criteria`: a file
+ *  is not a page and earns no conformance verdict. Kept private so nobody is tempted to
+ *  compute a per-file rate from it. */
+function fileView(result: AuditResult, file: string, baseDir: string): AuditResult {
+  const owns = (f: Finding): boolean => sourceOf(f, baseDir) === file;
+  return {
+    ...result,
+    findings: result.findings.filter(owns),
+    ...(result.packFindings ? { packFindings: result.packFindings.filter(owns) } : {}),
+  };
+}
+
+/** The occurrences a ticket carries, so a consumer never has to parse them back out of the
+ *  rendered body. Advisory findings ride along: they are part of the unit, just never NC. */
+function occurrencesOf(units: PrdUnit[], lang: Lang): TicketOccurrence[] {
+  return units.flatMap((u) => u.findings.map((f) => ({ file: f.file, line: f.line, selector: f.selectorHint, message: resolveMessage(f, lang) })));
+}
+
+/** The file a finding belongs to, REPO-RELATIVE. A finding raised on a RENDERED capture is
+ *  credited to the source component that produced it, not to the capture file nobody edits.
+ *  The path is relativised because it lands in the ticket TITLE, which is the de-dupe key: an
+ *  absolute path would make that key machine-specific and re-file everything from CI. */
+function sourceOf(f: Finding, baseDir: string): string {
+  return repoRelative(f.origin?.sourceFile ?? f.file, baseDir);
+}
+
+export function buildTickets(result: AuditResult, opts: GrainOptions): TicketPlan {
+  const { grain, standard, lang } = opts;
+  const { label, tag } = standardTag(standard);
+  const limit = opts.bodyLimit ?? Number.POSITIVE_INFINITY;
+  const bodyOpts = {
+    ...(opts.format !== undefined ? { format: opts.format } : {}),
+    ...(opts.technical !== undefined ? { technical: opts.technical } : {}),
+  };
+  const backlogOpts = opts.technical !== undefined ? { technical: opts.technical } : {};
+  const baseDir = opts.baseDir ?? "";
+  const clamp = (body: string): string => clampBody(body, limit, lang);
+
+  const ticketFromUnit = (unit: PrdUnit, title: string, scope: Ticket["scope"]): Ticket => ({
+    title,
+    body: clamp(renderCriterionBody(unit, standard, lang, bodyOpts)),
+    labels: labelsFor(unit.severity, unit.advisory === true, tag),
+    severity: unit.severity,
+    advisory: unit.advisory === true,
+    scope,
+    occurrences: occurrencesOf([unit], lang),
+  });
+
+  if (grain === "criterion") {
+    const tickets = prdUnits(result, standard, lang).map((u) => ticketFromUnit(u, criterionTitle(u, label), { grain: "criterion", criteriaId: u.criteriaId }));
+    return { tickets, unattributed: 0 };
+  }
+
+  if (grain === "single") {
+    const units = prdUnits(result, standard, lang);
+    if (!units.length) return { tickets: [], unattributed: 0 };
+    return {
+      tickets: [
+        {
+          title: singleTitle(label),
+          // renderAuditorBacklog — not a second template. It also fixes a real inconsistency
+          // in the pre-v3 consolidated body, which sectioned advisory units AMONG the
+          // severity groups instead of isolating them in their own trailing section.
+          body: clamp(renderAuditorBacklog(result, lang, standard, backlogOpts)),
+          labels: labelsFor(
+            worstOf(units),
+            units.every((u) => u.advisory === true),
+            tag,
+          ),
+          severity: worstOf(units),
+          advisory: units.every((u) => u.advisory === true),
+          scope: { grain: "single" },
+          occurrences: occurrencesOf(units, lang),
+        },
+      ],
+      unattributed: 0,
+    };
+  }
+
+  if (grain === "file") {
+    const files = [...new Set(result.findings.map((f) => sourceOf(f, baseDir)))].sort();
+    const tickets: Ticket[] = [];
+    for (const file of files) {
+      const view = fileView(result, file, baseDir);
+      const units = prdUnits(view, standard, lang);
+      if (!units.length) continue;
+      const advisory = units.every((u) => u.advisory === true);
+      tickets.push({
+        title: fileTitle(file, label),
+        body: clamp([...filePreamble(file, lang), renderAuditorBacklog(view, lang, standard, backlogOpts)].join("\n")),
+        labels: labelsFor(worstOf(units), advisory, tag),
+        severity: worstOf(units),
+        advisory,
+        scope: { grain: "file", file },
+        occurrences: occurrencesOf(units, lang),
+      });
+    }
+    return { tickets, unattributed: 0 };
+  }
+
+  // ---- the page grains -------------------------------------------------------------------
+  // Same ordering cmdPages uses: pagesOf → guard → attributePages (which MUTATES `result` by
+  // stamping `f.page`) → derivePages. Nothing here re-decides a status.
+  const scope = pagesOf(result);
+  if (!scope.length) return { tickets: [], unattributed: 0, error: "no-pages" };
+  attributePages(result, scope);
+  const derived = derivePages(result, scope);
+  const orphans = unattributedFindings(result);
+  const tickets: Ticket[] = [];
+
+  for (const page of derived) {
+    const view = pageView(result, page);
+    const units = prdUnits(view, standard, lang);
+    if (!units.length) continue;
+    const warning = pageBasisWarning(page.basis, lang);
+    const preamble = pagePreamble(page, lang, warning);
+
+    if (grain === "page") {
+      const advisory = units.every((u) => u.advisory === true);
+      tickets.push({
+        title: pageTitle(page.id, label),
+        body: clamp([...preamble, renderAuditorBacklog(view, lang, standard, backlogOpts)].join("\n")),
+        labels: labelsFor(worstOf(units), advisory, tag),
+        severity: worstOf(units),
+        advisory,
+        scope: pageScopeOf(page),
+        occurrences: occurrencesOf(units, lang),
+      });
+      continue;
+    }
+
+    for (const u of units) {
+      const t = ticketFromUnit(u, pageCriterionTitle(page.id, u, label), {
+        grain: "page-criterion",
+        pageId: page.id,
+        pageName: page.name,
+        url: page.url,
+        ...(page.auth !== undefined ? { auth: page.auth } : {}),
+        basis: page.basis,
+        criteriaId: u.criteriaId,
+      });
+      tickets.push({ ...t, body: clamp([...preamble, t.body].join("\n")) });
+    }
+  }
+
+  // Honesty rule 1: findings no page could claim get their OWN ticket. Dropping them would
+  // hide non-conformities; spreading them across pages would invent them. Both grains emit
+  // it, so the orphan backlog is never a casualty of the chosen granularity.
+  if (orphans.length) {
+    const view: AuditResult = { ...result, findings: orphans, ...(result.packFindings ? { packFindings: result.packFindings.filter((f) => !f.page) } : {}) };
+    const units = prdUnits(view, standard, lang);
+    if (units.length) {
+      const advisory = units.every((u) => u.advisory === true);
+      tickets.push({
+        title: unattributedTitle(label),
+        body: clamp([`> ${unattributedNote(orphans.length, lang)}`, "", renderAuditorBacklog(view, lang, standard, backlogOpts)].join("\n")),
+        labels: labelsFor(worstOf(units), advisory, tag),
+        severity: worstOf(units),
+        advisory,
+        scope: { grain: "page", pageId: UNATTRIBUTED_ID, pageName: UNATTRIBUTED_ID, url: "", basis: "none" },
+        occurrences: occurrencesOf(units, lang),
+      });
+    }
+  }
+
+  return { tickets, unattributed: orphans.length };
+}
+
+function pageScopeOf(page: PageResult): Ticket["scope"] {
+  return {
+    grain: "page",
+    pageId: page.id,
+    pageName: page.name,
+    url: page.url,
+    ...(page.auth !== undefined ? { auth: page.auth } : {}),
+    basis: page.basis,
+  };
+}

package/src/tickets/http.ts

@@ -0,0 +1,107 @@
+// THE REST TRANSPORT — global `fetch`, no SDK, no npm dependency.
+//
+// It exists because the CLI transports cannot cover CI: `gh` ships on GitHub-HOSTED runners
+// only, so self-hosted runners, container jobs and every other CI (GitLab CI, Jenkins) have
+// no binary to shell out to — and Jira has no CLI at all. A token in the environment is the
+// one thing all of them do have.
+//
+// Two rules govern this file:
+//   • A token NEVER appears in anything it returns or throws. Errors name the header, never
+//     its value: an error message ends up in a log, and a log ends up somewhere public.
+//   • It never sleeps in tests. The delay function is injected, exactly as src/llm.ts does.
+import { VERSION } from "../types.js";
+
+export const USER_AGENT = `ultra11y/${VERSION}`;
+
+/** Header names whose values must never be echoed back. */
+const SECRET_HEADERS = ["authorization", "private-token", "x-atlassian-token"];
+
+export class HttpError extends Error {
+  constructor(
+    readonly status: number,
+    /** Already scrubbed and truncated — safe to print. */
+    readonly detail: string,
+    readonly url: string,
+  ) {
+    super(`HTTP ${status}: ${detail}`);
+    this.name = "HttpError";
+  }
+}
+
+export interface HttpOptions {
+  method?: "GET" | "POST" | "PUT" | "PATCH";
+  headers?: Record<string, string>;
+  body?: unknown;
+  /** Injected for tests; defaults to the global. */
+  fetchImpl?: typeof fetch;
+  /** Injected for tests so a rate-limit retry never actually sleeps. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Retries on 429/503 before giving up. */
+  retries?: number;
+}
+
+const defaultSleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** Strip anything that looks like a credential out of a response body before it becomes an
+ *  error message. Trackers echo request context in their errors more often than you'd like. */
+function scrub(text: string, headers: Record<string, string>): string {
+  let out = text;
+  for (const [k, v] of Object.entries(headers)) {
+    if (v && SECRET_HEADERS.includes(k.toLowerCase())) out = out.split(v).join("<redacted>");
+  }
+  return out;
+}
+
+/** The one-line reason a caller surfaces. Prefers the tracker's own message field over a
+ *  wall of JSON: GitHub uses `message`, GitLab `message`/`error`, Jira `errorMessages[]`. */
+export function reasonFrom(detail: string): string {
+  try {
+    const j = JSON.parse(detail) as { message?: unknown; error?: unknown; errorMessages?: unknown; errors?: unknown };
+    if (Array.isArray(j.errorMessages) && typeof j.errorMessages[0] === "string") return j.errorMessages[0];
+    if (j.errors && typeof j.errors === "object" && !Array.isArray(j.errors)) {
+      const first = Object.entries(j.errors as Record<string, unknown>)[0];
+      if (first) return `${first[0]}: ${String(first[1])}`;
+    }
+    if (typeof j.message === "string") return j.message;
+    if (typeof j.error === "string") return j.error;
+  } catch {
+    /* not JSON — fall through to the raw text */
+  }
+  return detail.split("\n")[0]?.slice(0, 300) ?? detail.slice(0, 300);
+}
+
+export interface HttpResponse<T> {
+  data: T;
+  headers: Headers;
+}
+
+/** One JSON request. Throws HttpError on a non-2xx, after retrying a rate limit. */
+export async function requestJson<T>(url: string, opts: HttpOptions = {}): Promise<HttpResponse<T>> {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const sleep = opts.sleep ?? defaultSleep;
+  const retries = opts.retries ?? 2;
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    "User-Agent": USER_AGENT, // GitHub REJECTS a request without one.
+    ...(opts.body !== undefined ? { "Content-Type": "application/json" } : {}),
+    ...opts.headers,
+  };
+
+  for (let attempt = 0; ; attempt++) {
+    const res = await doFetch(url, {
+      method: opts.method ?? "GET",
+      headers,
+      ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+    });
+    if (res.ok) {
+      const text = await res.text();
+      return { data: (text ? JSON.parse(text) : {}) as T, headers: res.headers };
+    }
+    const detail = scrub(await res.text().catch(() => ""), headers);
+    const retryable = res.status === 429 || res.status === 503;
+    if (!retryable || attempt >= retries) throw new HttpError(res.status, detail, url);
+    // Honour the tracker's own backoff hint, capped so a bad header cannot hang a CI job.
+    const after = Number.parseInt(res.headers.get("retry-after") ?? "", 10);
+    await sleep(Math.min(Number.isFinite(after) ? after * 1000 : 1000 * 2 ** attempt, 30_000));
+  }
+}

package/src/tickets/providers/github.ts

@@ -0,0 +1,155 @@
+// GitHub — two transports behind one TicketProvider.
+//
+// CLI (`gh`) is preferred by `auto` because it carries the user's own auth and ultra11y
+// never touches a token. REST is the CI path: `gh` ships on GitHub-HOSTED runners only, so a
+// container job, a self-hosted runner or any non-GitHub CI has a GITHUB_TOKEN and no binary.
+// GHES works through GITHUB_API_URL, which Actions sets for you.
+import { ghAvailable, ghErrorReason, ghExec } from "../../gh-cli.js";
+import { HttpError, reasonFrom, requestJson } from "../http.js";
+import type { CreateOutcome, ExistingTicket, ProviderCapabilities, Ticket, TicketProvider, TransportMode } from "../types.js";
+import { gitRemoteSlug } from "./remote.js";
+
+// GitHub caps an issue body at 65536 characters and 422s past it.
+const CAPABILITIES: ProviderCapabilities = { bodyLimit: 65536, labels: true };
+
+export interface GithubOptions {
+  transport?: TransportMode;
+  env?: Record<string, string | undefined>;
+  fetchImpl?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  /** Injected for tests, so the probe never shells out. */
+  cliAvailable?: () => boolean;
+}
+
+interface Resolved {
+  transport: "cli" | "rest";
+  repo?: string;
+  token?: string;
+  api: string;
+  reason?: string;
+}
+
+function resolve(opts: GithubOptions): Resolved {
+  const env = opts.env ?? process.env;
+  const mode = opts.transport ?? "auto";
+  const api = (env.GITHUB_API_URL || "https://api.github.com").replace(/\/+$/, "");
+  const token = env.GH_TOKEN || env.GITHUB_TOKEN;
+  const cliOk = (opts.cliAvailable ?? ghAvailable)();
+
+  if (mode === "cli") {
+    return cliOk ? { transport: "cli", api } : { transport: "cli", api, reason: "`gh` is not installed or not authenticated (run `gh auth login`)" };
+  }
+  // Only REST needs the repo slug, and only REST should pay for a `git` subprocess to find
+  // it — the CLI transport already knows which checkout it is standing in.
+  const repo = env.ULTRA11Y_GITHUB_REPO || env.GITHUB_REPOSITORY || (mode === "rest" || !cliOk ? gitRemoteSlug("github.com") : undefined);
+  if (mode === "rest") {
+    if (!token) return { transport: "rest", api, reason: "no GitHub token — set GH_TOKEN or GITHUB_TOKEN" };
+    if (!repo) return { transport: "rest", api, token, reason: "no repository — set GITHUB_REPOSITORY (owner/name) or ULTRA11Y_GITHUB_REPO" };
+    return { transport: "rest", api, token, repo };
+  }
+  // auto: the CLI first (it owns its auth), then REST, then say what BOTH were missing.
+  if (cliOk) return { transport: "cli", api };
+  if (token && repo) return { transport: "rest", api, token, repo };
+  const missing = [!token ? "a token (GH_TOKEN/GITHUB_TOKEN)" : "", !repo ? "a repository (GITHUB_REPOSITORY)" : ""].filter(Boolean);
+  return {
+    transport: "rest",
+    api,
+    ...(token ? { token } : {}),
+    ...(repo ? { repo } : {}),
+    reason: `\`gh\` is unavailable and REST is missing ${missing.join(" and ")}`,
+  };
+}
+
+export function createGithubProvider(opts: GithubOptions = {}): TicketProvider {
+  const r = resolve(opts);
+  const auth = { Authorization: `Bearer ${r.token ?? ""}`, Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" };
+  const http = {
+    ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+    ...(opts.sleep ? { sleep: opts.sleep } : {}),
+  };
+
+  async function listRest(): Promise<ExistingTicket[]> {
+    const out: ExistingTicket[] = [];
+    // 10 pages of 100 mirrors the CLI transport's `--limit 1000`.
+    for (let page = 1; page <= 10; page++) {
+      const url = `${r.api}/repos/${r.repo}/issues?state=all&per_page=100&page=${page}`;
+      const { data } = await requestJson<Array<{ title?: string; number?: number; html_url?: string; pull_request?: unknown }>>(url, {
+        headers: auth,
+        ...http,
+      });
+      if (!Array.isArray(data) || data.length === 0) break;
+      // The issues endpoint returns PULL REQUESTS too. A PR whose title happened to match
+      // would silently suppress a real ticket, so they are filtered, not merely tolerated.
+      for (const i of data) {
+        if (i.pull_request) continue;
+        if (i.title) out.push({ title: i.title, ...(i.number !== undefined ? { id: String(i.number) } : {}), ...(i.html_url ? { url: i.html_url } : {}) });
+      }
+      if (data.length < 100) break;
+    }
+    return out;
+  }
+
+  function listCli(): ExistingTicket[] {
+    const raw = ghExec(["issue", "list", "--state", "all", "--limit", "1000", "--json", "title"]);
+    return (JSON.parse(raw) as Array<{ title?: string }>).filter((i) => i.title).map((i) => ({ title: i.title as string }));
+  }
+
+  async function createRest(t: Ticket): Promise<CreateOutcome> {
+    const url = `${r.api}/repos/${r.repo}/issues`;
+    const post = async (labels?: string[]) =>
+      requestJson<{ number?: number; html_url?: string }>(url, {
+        method: "POST",
+        headers: auth,
+        body: { title: t.title, body: t.body, ...(labels ? { labels } : {}) },
+        ...http,
+      });
+    try {
+      const { data } = await post(t.labels);
+      return { ok: true, ...(data.number !== undefined ? { id: String(data.number) } : {}), ...(data.html_url ? { url: data.html_url } : {}) };
+    } catch (e) {
+      // A repo whose labels do not exist 422s. Retry unlabelled rather than lose the ticket
+      // — the same fallback the CLI transport has always had.
+      if (e instanceof HttpError && e.status === 422) {
+        try {
+          const { data } = await post();
+          return { ok: true, ...(data.number !== undefined ? { id: String(data.number) } : {}), ...(data.html_url ? { url: data.html_url } : {}) };
+        } catch (retryErr) {
+          return { ok: false, reason: retryErr instanceof HttpError ? reasonFrom(retryErr.detail) : String(retryErr) };
+        }
+      }
+      return { ok: false, reason: e instanceof HttpError ? reasonFrom(e.detail) : e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  /** argv byte-identical to the pre-v3 `createIssue`, including the unlabelled retry. */
+  function createCli(t: Ticket): CreateOutcome {
+    const base = ["issue", "create", "--title", t.title, "--body-file", "-"];
+    try {
+      ghExec([...base, "--label", t.labels.join(",")], t.body);
+      return { ok: true };
+    } catch (labelledErr) {
+      try {
+        ghExec(base, t.body);
+        return { ok: true };
+      } catch (err) {
+        return { ok: false, reason: ghErrorReason(err) ?? ghErrorReason(labelledErr) };
+      }
+    }
+  }
+
+  return {
+    id: "github",
+    transport: r.transport,
+    capabilities: CAPABILITIES,
+    available: () => r.reason === undefined,
+    unavailableReason: () => r.reason,
+    list: async () => {
+      try {
+        return r.transport === "cli" ? listCli() : await listRest();
+      } catch {
+        return []; // degrade to "create": a duplicate beats dropping the backlog
+      }
+    },
+    create: async (t) => (r.transport === "cli" ? createCli(t) : createRest(t)),
+  };
+}