@kubohiroya/turbowarp-plus-editor-git 0.17.0 → 0.19.0

package/src/branch-button.tsx

@@ -0,0 +1,289 @@
+import React, {useEffect, useLayoutEffect, useRef, useState} from 'react';
+import {createPortal} from 'react-dom';
+import {CloseButton} from './close-button.js';
+import type {HistoryActionResult} from './history-graph-view.js';
+import {labelsFor} from './messages.js';
+import type {BranchRefs} from './repository.js';
+
+/** What the branch button shows: the branches of the chosen repository as the Git panel last read them. */
+export interface BranchButtonState extends BranchRefs {
+    /** Whether a repository has been chosen. */
+    repository: boolean;
+    /** Whether the host lets the panel switch and create branches. */
+    writable: boolean;
+    /** Whether the panel is running an operation. */
+    busy: boolean;
+    /** Whether a project folder is selected in the panel, so a switch can offer to reload it. */
+    project: boolean;
+}
+/** What the branch button asks the Git panel to do. Branch operations resolve as the panel's own buttons do. */
+export interface BranchButtonActions {
+    open(): void;
+    choose(): void;
+    /** The panel's Reload Project, which asks before replacing unsaved edits. */
+    reload(): void;
+    switchBranch(name: string): Promise<HistoryActionResult>;
+    /** Creates a branch at HEAD. */
+    createBranch(name: string, checkout: boolean): Promise<HistoryActionResult>;
+    /** Creates a local branch from `origin/<name>` and switches to it. */
+    createFromRemote(name: string): Promise<HistoryActionResult>;
+}
+export interface BranchButtonProps extends BranchButtonActions {
+    state: BranchButtonState;
+    locale?: string;
+}
+interface Item {id: string; label: string; checked?: boolean; disabled?: boolean; separatorBefore?: boolean; run(): void}
+
+const menuItems = '[role="menuitem"], [role="menuitemradio"]';
+/** How long a snackbar stays when it is neither hovered nor focused. */
+export const snackbarDuration = 6000;
+interface Snack {id: number; text: string; alert: boolean; action?: {label: string; run(): void}}
+
+/**
+ * A short result at the bottom of the window, with the project folder's status look. It stays while hovered or
+ * focused, Escape or the close button dismisses it, and focus is never moved into it.
+ */
+function Snackbar({snack, closeLabel, onClose}: {snack: Snack; closeLabel: string; onClose(focus: boolean): void}) {
+    // Kept outside React state, so a pointer or focus arriving just before the timeout stops it at once.
+    const held = useRef({hover: false, focus: false});
+    const timer = useRef<ReturnType<typeof setTimeout>>();
+    const hold = (change: Partial<typeof held.current>) => {
+        held.current = {...held.current, ...change};
+        clearTimeout(timer.current);
+        if (!held.current.hover && !held.current.focus) timer.current = setTimeout(() => onClose(false), snackbarDuration);
+    };
+    useEffect(() => {
+        hold({});
+        return () => clearTimeout(timer.current);
+    }, []);
+    return createPortal(<div className="twgit-snackbar" data-git-snackbar=""
+        onMouseEnter={() => hold({hover: true})} onMouseLeave={() => hold({hover: false})}
+        onFocus={() => hold({focus: true})}
+        onBlur={event => {
+            if (!event.currentTarget.contains(event.relatedTarget as Node | null)) hold({focus: false});
+        }}
+        onKeyDown={event => {
+            if (event.key !== 'Escape') return;
+            event.preventDefault();
+            event.stopPropagation();
+            onClose(true);
+        }}>
+        <span role={snack.alert ? 'alert' : 'status'}>{snack.text}</span>
+        {snack.action && <button type="button" onClick={() => {onClose(true); snack.action!.run();}}>{snack.action.label}</button>}
+        <CloseButton label={closeLabel} onClick={() => onClose(true)}/>
+    </div>, document.body);
+}
+
+/**
+ * The results of branch operations in a snackbar, as the branch button and the history view tell them: a switch with
+ * Reload Project while a project folder is selected, a new branch, or the reason for a refusal with Open Local Git.
+ * A declined confirmation tells nothing. `restoreFocus` takes the focus back when the snackbar closes from inside.
+ */
+export function useBranchSnackbar(locale: string, project: boolean, actions: Pick<BranchButtonActions, 'open' | 'reload'>,
+    restoreFocus?: () => void) {
+    const labels = labelsFor(locale);
+    const [snack, setSnack] = useState<Snack | null>(null);
+    const snacks = useRef(0);
+    const mounted = useRef(true);
+    useEffect(() => () => {mounted.current = false;}, []);
+    const show = (text: string, alert: boolean, action?: Snack['action']) => {
+        if (mounted.current) setSnack({id: ++snacks.current, text, alert, action});
+    };
+    const report = (result: HistoryActionResult, switched: boolean) => {
+        if (result.done) {
+            if (!switched) show(labels.branchCreated, false);
+            // The switch rewrote the files; the open project shows them after Reload Project.
+            else show(labels.switchedShort, false, project ? {label: labels.reload, run: actions.reload} : undefined);
+        } else if (result.error) show(result.error, true, {label: labels.openPanel, run: actions.open});
+    };
+    const element = snack && <Snackbar key={snack.id} snack={snack} closeLabel={labels.close} onClose={focus => {
+        setSnack(previous => previous?.id === snack.id ? null : previous);
+        // Focus inside the snackbar would be lost with it.
+        if (focus) restoreFocus?.();
+    }}/>;
+    return {report, element};
+}
+
+/** Git's branch glyph, drawn in the text color. */
+function BranchIcon() {
+    return <svg className="twgit-branch-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false">
+        <g fill="none" stroke="currentColor" strokeWidth="1.5">
+            <circle cx="4.5" cy="3.5" r="1.75"/><circle cx="4.5" cy="12.5" r="1.75"/><circle cx="11.5" cy="5.5" r="1.75"/>
+            <path d="M4.5 5.25v5.5M11.5 7.25c0 2.5-2.5 2.75-6 3.75"/>
+        </g>
+    </svg>;
+}
+
+/**
+ * The current branch as a menu button for the host's menu bar, with the menu of branches. Before a repository is
+ * chosen it reads "Git" and offers to choose one. A detached HEAD shows its short commit ID. The menu moves with the
+ * arrow keys, Home and End; Escape closes it and returns to the button. Without `writable` it lists the branches only.
+ */
+export function BranchButton({state, locale = 'en', ...actions}: BranchButtonProps) {
+    const labels = labelsFor(locale);
+    const [mode, setMode] = useState<'closed' | 'menu' | 'create'>('closed');
+    const [initial, setInitial] = useState<'checked' | 'first' | 'last'>('checked');
+    const [name, setName] = useState('');
+    const [checkout, setCheckout] = useState(true);
+    const [creating, setCreating] = useState(false);
+    const [createError, setCreateError] = useState('');
+    const root = useRef<HTMLDivElement>(null);
+    const trigger = useRef<HTMLButtonElement>(null);
+    const popup = useRef<HTMLDivElement>(null);
+    const mounted = useRef(true);
+    useEffect(() => () => {mounted.current = false;}, []);
+    useLayoutEffect(() => {
+        const element = popup.current;
+        if (!element) return;
+        if (mode === 'create') {
+            element.querySelector('input')?.focus();
+            return;
+        }
+        const items = [...element.querySelectorAll<HTMLElement>(menuItems)];
+        const checked = items.find(item => item.getAttribute('aria-checked') === 'true');
+        (initial === 'last' ? items[items.length - 1] : initial === 'checked' && checked || items[0])?.focus();
+    }, [mode]);
+    // A click elsewhere closes the menu, also where nothing takes the focus.
+    useEffect(() => {
+        if (mode === 'closed') return;
+        const node = root.current!;
+        const dismiss = (event: Event) => {
+            if (!node.contains(event.target as Node) && !creating) setMode('closed');
+        };
+        node.ownerDocument.addEventListener('pointerdown', dismiss, true);
+        return () => node.ownerDocument.removeEventListener('pointerdown', dismiss, true);
+    }, [mode, creating]);
+    // After a refused create, the name is selected for correcting.
+    useEffect(() => {
+        if (!createError || creating) return;
+        const input = popup.current?.querySelector('input:not([type])') as HTMLInputElement | null;
+        input?.focus();
+        input?.select();
+    }, [createError, creating]);
+
+    const {branch, head} = state;
+    const unborn = state.repository && !head;
+    const text = !state.repository ? 'Git' : branch ?? (head ? head.slice(0, 7) : labels.unborn);
+    const accessibleName = !state.repository ? labels.title :
+        `${branch ? labels.branch : labels.detached}: ${text}${unborn && branch ? ` (${labels.unborn})` : ''}`;
+    const close = (focus = true) => {
+        setMode('closed');
+        if (focus) trigger.current?.focus({preventScroll: true});
+    };
+    const openMenu = (from: 'checked' | 'first' | 'last') => {
+        setInitial(from);
+        setMode('menu');
+    };
+    const {report, element: snackbar} = useBranchSnackbar(locale, state.project, actions,
+        () => trigger.current?.focus({preventScroll: true}));
+    const change = async (operation: () => Promise<HistoryActionResult>) => report(await operation(), true);
+    const items: Item[] = [];
+    if (!state.repository) {
+        items.push({id: 'choose', label: labels.choose, run: () => {close(); actions.choose();}});
+    } else {
+        const switching = state.writable && !state.busy;
+        for (const local of state.branches) {
+            items.push({id: 'branch:' + local, label: local, checked: local === branch, disabled: !state.writable || state.busy && local !== branch,
+                run: () => {
+                    close();
+                    if (local !== branch && switching) void change(() => actions.switchBranch(local));
+                }});
+        }
+        if (state.writable) {
+            state.remoteBranches.forEach((remote, index) => items.push({id: 'remote:' + remote,
+                label: labels.historyCreateFromRemote.replace('{name}', remote), disabled: state.busy, separatorBefore: index === 0,
+                run: () => {
+                    close();
+                    if (!state.busy) void change(() => actions.createFromRemote(remote));
+                }}));
+            if (head) items.push({id: 'create', label: labels.newBranchItem, disabled: state.busy, separatorBefore: true, run: () => {
+                if (state.busy) return;
+                setName('');
+                setCheckout(true);
+                setCreateError('');
+                setMode('create');
+            }});
+        }
+    }
+    // "Open Local Git" goes with "New Branch…" and stands apart from the branches.
+    items.push({id: 'open', label: labels.openPanel, separatorBefore: items.length > 0 && items[items.length - 1].id !== 'create',
+        run: () => {close(); actions.open();}});
+
+    const onMenuKey = (event: React.KeyboardEvent<HTMLElement>) => {
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            event.stopPropagation();
+            if (!creating) close();
+            return;
+        }
+        if (mode !== 'menu') return;
+        if (event.key === 'Tab') {close(false); return;}
+        const elements = [...event.currentTarget.querySelectorAll<HTMLElement>(menuItems)];
+        const index = elements.indexOf(event.target as HTMLElement);
+        const target = {ArrowDown: index + 1, ArrowUp: index - 1, Home: 0, End: elements.length - 1}[event.key];
+        if (target === undefined || !elements.length) return;
+        event.preventDefault();
+        elements[(target + elements.length) % elements.length].focus();
+    };
+    const submit = async (event: React.FormEvent) => {
+        event.preventDefault();
+        const branchName = name.trim();
+        if (!branchName || creating) return;
+        setCreating(true);
+        setCreateError('');
+        let result: HistoryActionResult;
+        try {
+            result = await actions.createBranch(branchName, checkout);
+        } catch (error) {
+            result = {done: false, error: error instanceof Error && error.message ? error.message : labels.failed};
+        }
+        if (!mounted.current) return;
+        setCreating(false);
+        if (result.done) {
+            close();
+            report(result, checkout);
+        } else setCreateError(result.error ?? '');
+    };
+    return <div className="twgit-branch-entry" ref={root} onBlur={event => {
+        const next = event.relatedTarget as Node | null;
+        if (next && !event.currentTarget.contains(next) && !creating) setMode('closed');
+    }}>
+        <button type="button" className="twgit-branch-button" ref={trigger} aria-label={accessibleName} title={accessibleName}
+            aria-haspopup="menu" aria-expanded={mode === 'menu'} data-git-branch={state.repository ? branch ?? head ?? '' : undefined}
+            onClick={() => mode === 'closed' ? openMenu('checked') : close(false)}
+            onKeyDown={event => {
+                if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+                event.preventDefault();
+                openMenu(event.key === 'ArrowUp' ? 'last' : 'checked');
+            }}>
+            <BranchIcon/>
+            <span className="twgit-branch-name">{text}</span>
+            {unborn && branch && <small className="twgit-branch-unborn">{labels.unborn}</small>}
+            <span className="twgit-branch-caret" aria-hidden="true">▾</span>
+        </button>
+        {mode === 'menu' && <div ref={popup} className="twgit-branch-popup" role="menu" aria-label={labels.branchMenu} onKeyDown={onMenuKey}>
+            {items.map(item => <button key={item.id} type="button" tabIndex={-1} data-action={item.id}
+                role={item.checked === undefined ? 'menuitem' : 'menuitemradio'} aria-checked={item.checked}
+                aria-disabled={item.disabled || undefined} data-separator-before={item.separatorBefore || undefined}
+                onClick={() => {if (!item.disabled || item.checked) item.run();}}>
+                {item.checked !== undefined && <span className="twgit-branch-check" aria-hidden="true">{item.checked ? '✓' : ''}</span>}
+                {item.label}
+            </button>)}
+        </div>}
+        {mode === 'create' && <div ref={popup} className="twgit-branch-popup" role="dialog" aria-label={labels.newBranchTitle}
+            onKeyDown={onMenuKey}>
+            <form onSubmit={event => void submit(event)}>
+                <label>{labels.newBranch} <input value={name} required disabled={creating} aria-invalid={createError ? true : undefined}
+                    onChange={event => setName(event.currentTarget.value)}/></label>
+                <label><input type="checkbox" checked={checkout} disabled={creating}
+                    onChange={event => setCheckout(event.currentTarget.checked)}/> {labels.switchAfterCreate}</label>
+                {createError && <p className="twgit-graph-form-error" role="alert">{createError}</p>}
+                <span className="twgit-graph-form-actions">
+                    <button type="submit" disabled={creating || state.busy || !name.trim()}>{labels.createBranch}</button>
+                    <button type="button" disabled={creating} onClick={() => close()}>{labels.cancel}</button>
+                </span>
+            </form>
+        </div>}
+        {snackbar}
+    </div>;
+}

package/src/change-marks.ts

@@ -0,0 +1,22 @@
+import type {FileChange} from './repository.js';
+
+/** How a file stands in Git, as a folder explorer marks it. */
+export type ChangeMark = 'added' | 'modified' | 'deleted' | 'untracked';
+
+/**
+ * The marks of the working tree's changes under `folder` (a path inside the repository, '' for its root), by path
+ * relative to `folder`. A file with both staged and unstaged changes is marked as its working tree stands.
+ */
+export function changeMarks(changes: readonly FileChange[], folder: string): Map<string, ChangeMark> {
+    const prefix = folder.replace(/^\/+|\/+$/gu, '');
+    const marks = new Map<string, ChangeMark>();
+    for (const group of ['staged', 'unstaged', 'untracked'] as const) {
+        for (const change of changes) {
+            if (change.group !== group) continue;
+            if (prefix && !change.path.startsWith(prefix + '/')) continue;
+            const path = prefix ? change.path.slice(prefix.length + 1) : change.path;
+            marks.set(path, group === 'untracked' ? 'untracked' : !change.after ? 'deleted' : !change.before ? 'added' : 'modified');
+        }
+    }
+    return marks;
+}

package/src/connection-settings.tsx

@@ -1,6 +1,7 @@
 import React, {useEffect, useRef, useState} from 'react';
 import type {GitAuthState, GitConnectionMode as Mode} from '@kubohiroya/turbowarp-plus-editor-auth';
 import type {GetRemoteSession, RemoteOperation} from './remote-operations.js';
+import {reviewLabelsFor} from './messages.js';
 
 export interface GitConnectionSettings {
     modes: readonly Mode[];
@@ -9,10 +10,12 @@ export interface GitConnectionSettings {
         state: GitAuthState;
         proxyOrigin?: string;
         write?: boolean;
+        /** Whether the connection was made with the grant to send pull request reviews. */
+        review?: boolean;
         authorization?: {url: string; userCode?: string};
     };
     select(mode: Mode): Promise<void>;
-    connect(remote: string, write?: boolean): Promise<void>;
+    connect(remote: string, write?: boolean, review?: boolean): Promise<void>;
     refresh(): Promise<void>;
     disconnect(): Promise<void>;
     getSession?: GetRemoteSession;
@@ -49,6 +52,7 @@ export function ConnectionSettings({settings, locale, readOrigin, runOperation}:
     const [, update] = useState(0);
     const [busy, setBusy] = useState(false);
     const [allowPush, setAllowPush] = useState(false);
+    const [allowReview, setAllowReview] = useState(false);
     const [error, setError] = useState<'error' | 'invalid' | null>(null);
     const active = useRef(true);
     useEffect(() => {active.current = true; return () => {active.current = false;};}, []);
@@ -66,7 +70,7 @@ export function ConnectionSettings({settings, locale, readOrigin, runOperation}:
     const connect = () => run(async () => {
         const remote = await readOrigin?.();
         if (!remote) throw new Error('INVALID_REMOTE');
-        await settings.connect(remote, allowPush);
+        await (allowReview ? settings.connect(remote, allowPush, true) : settings.connect(remote, allowPush));
     });
     const connected = !!mode && state.status === 'connected';
     // Sync sits beside the GitHub status; the settings open over the list instead of pushing it down.
@@ -92,6 +96,9 @@ export function ConnectionSettings({settings, locale, readOrigin, runOperation}:
                 {runOperation && <label><input type="checkbox" checked={allowPush}
                     disabled={busy || state.status === 'connecting' || state.status === 'connected'}
                     onChange={event => setAllowPush(event.currentTarget.checked)}/> {labels.allowPush}</label>}
+                <label><input type="checkbox" data-git-allow-review="" checked={allowReview}
+                    disabled={busy || state.status === 'connecting' || state.status === 'connected'}
+                    onChange={event => setAllowReview(event.currentTarget.checked)}/> {reviewLabelsFor(locale).allowReview}</label>
                 <button disabled={busy || !readOrigin || state.status === 'connecting' || state.status === 'connected'}
                     onClick={connect}>{labels.connect}</button>
                 {authorization && <p>{authorization.userCode && <code>{authorization.userCode} </code>}

package/src/github-review-api.ts

@@ -0,0 +1,298 @@
+import type {GitProxySession} from '@kubohiroya/turbowarp-plus-editor-auth';
+import {checkConnection, remoteUrl} from './smart-http.js';
+
+/**
+ * The pull request review routes of the GitHub connection's proxy, under `/v1/github/<owner>/<repo>/`. The proxy keeps
+ * the GitHub token and the GitHub node IDs; this client sends only a pull request number, the compared commit, a
+ * Review-Submit-Id and the review's words, and reads back the few fields the proxy returns.
+ */
+
+export type ReviewEvent = 'COMMENT' | 'APPROVE' | 'REQUEST_CHANGES';
+export const reviewEvents: readonly ReviewEvent[] = ['COMMENT', 'APPROVE', 'REQUEST_CHANGES'];
+
+const proxyCodes = {
+    400: ['BAD_REQUEST'],
+    401: ['SESSION_REQUIRED', 'SESSION_EXPIRED', 'REAUTH_REQUIRED'],
+    403: ['FORBIDDEN'],
+    // A proxy without the route group answers 404 too, so an unnamed 404 means the route is unavailable.
+    404: ['GITHUB_API_UNAVAILABLE', 'PULL_REQUEST_NOT_FOUND'],
+    409: ['REVIEW_STEP_CONFLICT', 'REVIEW_DUPLICATE', 'PENDING_REVIEW_EXISTS', 'REDIRECT_REJECTED'],
+    411: ['LENGTH_REQUIRED'],
+    413: ['PAYLOAD_TOO_LARGE'],
+    422: ['REVIEW_REJECTED', 'REVIEW_THREAD_REJECTED'],
+    429: ['RATE_LIMITED'],
+    500: ['GITHUB_API_MISCONFIGURED'],
+    502: ['UPSTREAM_FAILURE'],
+    504: ['UPSTREAM_TIMEOUT']
+} as const;
+
+type ProxyCode = (typeof proxyCodes)[keyof typeof proxyCodes][number];
+export type GitHubReviewErrorCode = ProxyCode | 'INVALID_REMOTE' | 'INVALID_CONNECTION' | 'INVALID_SESSION' |
+    'SESSION_UNAVAILABLE' | 'NETWORK_ERROR' | 'INVALID_RESPONSE' | 'ABORTED';
+
+// Codes after which a mutation may or may not have reached GitHub.
+const unknownCodes: readonly GitHubReviewErrorCode[] = ['REVIEW_DUPLICATE', 'UPSTREAM_FAILURE', 'UPSTREAM_TIMEOUT',
+    'NETWORK_ERROR', 'INVALID_RESPONSE'];
+
+export class GitHubReviewError extends Error {
+    constructor(readonly code: GitHubReviewErrorCode, readonly options: {
+        status?: number; requestId?: string; retryAfter?: number;
+        /** A mutation was sent and GitHub may have applied it. */
+        unknown?: boolean;
+    } = {}) {
+        super(code);
+        this.name = 'GitHubReviewError';
+    }
+    get unknown() {return this.options.unknown === true;}
+    get retryAfter() {return this.options.retryAfter;}
+}
+
+const isSha = (value: unknown): value is string => typeof value === 'string' && /^[0-9a-f]{40}$/u.test(value);
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isCount = (value: unknown, max: number): value is number => Number.isSafeInteger(value) && Number(value) >= 0 && Number(value) <= max;
+const optionalString = (value: unknown) => value === null || typeof value === 'string';
+const submitIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const requestIdPattern = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu;
+
+/** A thread path the proxy accepts: a relative path whose last element is exactly project.source.json. */
+export function isReviewThreadPath(path: string) {
+    const parts = path.split('/');
+    return parts[parts.length - 1] === 'project.source.json' && new TextEncoder().encode(path).byteLength <= 1024 &&
+        parts.every(part => part && part !== '.' && part !== '..') && !/[\\\u0000-\u001f\u007f]/u.test(path);
+}
+
+export function newReviewSubmitId() {
+    const id = crypto.randomUUID();
+    if (!submitIdPattern.test(id)) throw new GitHubReviewError('INVALID_RESPONSE');
+    return id;
+}
+
+export interface ReviewContext {
+    headRefOid: string;
+    viewer: string;
+    pendingReview: {ours: boolean; commitOid: string | null; createdAt: string} | null;
+    reviews: {state: string; commitOid: string | null; submittedAt: string | null; ours: boolean}[];
+    /** The proxy's record of the submission, when the request named one. */
+    submit?: {state: string; threads: number};
+}
+
+export interface SubmittedReview {state: string; commitOid: string; submittedAt: string; url: string}
+export interface RestReview {id: number; login: string | null; commitId: string | null; state: string; body: string}
+
+function readContext(value: unknown, withSubmit: boolean): ReviewContext {
+    if (!isRecord(value) || !isSha(value.headRefOid) || typeof value.viewer !== 'string' || !Array.isArray(value.reviews))
+        throw new GitHubReviewError('INVALID_RESPONSE');
+    let pendingReview: ReviewContext['pendingReview'] = null;
+    if (value.pendingReview !== null) {
+        const pending = value.pendingReview;
+        if (!isRecord(pending) || typeof pending.ours !== 'boolean' || !(pending.commitOid === null || isSha(pending.commitOid)) ||
+            typeof pending.createdAt !== 'string') throw new GitHubReviewError('INVALID_RESPONSE');
+        pendingReview = {ours: pending.ours, commitOid: pending.commitOid, createdAt: pending.createdAt};
+    }
+    const reviews = value.reviews.map(review => {
+        if (!isRecord(review) || typeof review.state !== 'string' || !(review.commitOid === null || isSha(review.commitOid)) ||
+            !optionalString(review.submittedAt) || typeof review.ours !== 'boolean') throw new GitHubReviewError('INVALID_RESPONSE');
+        return {state: review.state, commitOid: review.commitOid as string | null, submittedAt: review.submittedAt as string | null,
+            ours: review.ours};
+    });
+    const context: ReviewContext = {headRefOid: value.headRefOid, viewer: value.viewer, pendingReview, reviews};
+    if (withSubmit) {
+        const submit = value.submit;
+        if (!isRecord(submit) || typeof submit.state !== 'string' || !isCount(submit.threads, 50))
+            throw new GitHubReviewError('INVALID_RESPONSE');
+        context.submit = {state: submit.state, threads: submit.threads};
+    }
+    return context;
+}
+
+async function readBounded(response: Response, limit: number) {
+    if (!response.body) return '';
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder('utf-8', {fatal: true});
+    let text = '', size = 0;
+    try {
+        for (;;) {
+            const {done, value} = await reader.read();
+            if (done) return text + decoder.decode();
+            size += value.byteLength;
+            if (size > limit) throw new GitHubReviewError('INVALID_RESPONSE');
+            text += decoder.decode(value, {stream: true});
+        }
+    } finally {
+        void reader.cancel().catch(() => {});
+    }
+}
+
+export interface GitHubReviewApiOptions {
+    /** The repository's GitHub HTTPS remote, as the connection was made for it. */
+    readonly remote: string;
+    /** The connection's session for `remote`; review calls ask for the review grant. */
+    readonly getSession: (remote: string, write: boolean, review?: boolean) => Promise<GitProxySession | null>;
+    readonly fetch?: typeof fetch;
+}
+
+export function createGitHubReviewApi({remote, getSession, fetch: send = (...args) => fetch(...args)}: GitHubReviewApiOptions) {
+    let path: string;
+    try {
+        path = '/v1/github' + remoteUrl(remote).slice('https://github.com'.length).replace(/\.git$/u, '');
+    } catch {
+        throw new GitHubReviewError('INVALID_REMOTE');
+    }
+    /** What the proxy answered about each route group: `false` after `404 GITHUB_API_UNAVAILABLE`. */
+    const available: {threads?: boolean; body?: boolean} = {};
+    let account: string | null = null;
+
+    async function session(review: boolean) {
+        let value: GitProxySession | null;
+        try {
+            value = await getSession(remote, false, review);
+        } catch {
+            throw new GitHubReviewError('SESSION_UNAVAILABLE');
+        }
+        if (!value) throw new GitHubReviewError('SESSION_REQUIRED');
+        if (!Number.isFinite(value.expiresAt) || value.expiresAt <= Date.now()) throw new GitHubReviewError('SESSION_EXPIRED');
+        try {
+            checkConnection(value.connection);
+        } catch {
+            throw new GitHubReviewError('INVALID_CONNECTION');
+        }
+        if (typeof value.bearer !== 'string' || !/^[A-Za-z0-9._~+\/-]+=*$/u.test(value.bearer))
+            throw new GitHubReviewError('INVALID_SESSION');
+        account = typeof value.account?.login === 'string' ? value.account.login : null;
+        return value;
+    }
+
+    async function call(route: string, {method = 'GET', body, submitId, review = false, mutation = false, limit = 256 * 1024,
+        group, signal}: {
+        method?: 'GET' | 'POST'; body?: unknown; submitId?: string; review?: boolean; mutation?: boolean; limit?: number;
+        group: 'threads' | 'body' | 'read'; signal?: AbortSignal;
+    }): Promise<unknown> {
+        if (signal?.aborted) throw new GitHubReviewError('ABORTED');
+        const current = await session(review);
+        const headers: Record<string, string> = {Authorization: 'Bearer ' + current.bearer, Accept: 'application/json'};
+        if (body !== undefined) headers['Content-Type'] = 'application/json';
+        if (submitId !== undefined) {
+            if (!submitIdPattern.test(submitId)) throw new GitHubReviewError('BAD_REQUEST');
+            headers['Review-Submit-Id'] = submitId;
+        }
+        let response: Response;
+        try {
+            response = await send(current.connection.proxyOrigin + path + route, {
+                method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal,
+                credentials: 'omit', redirect: 'error', cache: 'no-store', referrerPolicy: 'no-referrer'
+            });
+        } catch {
+            if (!mutation && signal?.aborted) throw new GitHubReviewError('ABORTED');
+            throw new GitHubReviewError('NETWORK_ERROR', {unknown: mutation});
+        }
+        const json = response.headers.get('content-type')?.split(';')[0].trim() === 'application/json';
+        if (response.status !== 200) {
+            const allowed: readonly ProxyCode[] | undefined = proxyCodes[response.status as keyof typeof proxyCodes];
+            let code: GitHubReviewErrorCode = allowed?.[0] ?? 'INVALID_RESPONSE';
+            let requestId: string | undefined, retryAfter: number | undefined;
+            try {
+                const parsed: unknown = json ? JSON.parse(await readBounded(response, 4096)) : null;
+                if (isRecord(parsed)) {
+                    if (allowed?.includes(parsed.code as ProxyCode)) code = parsed.code as ProxyCode;
+                    if (typeof parsed.requestId === 'string' && requestIdPattern.test(parsed.requestId)) requestId = parsed.requestId;
+                    if (Number.isSafeInteger(parsed.retryAfter) && Number(parsed.retryAfter) >= 0) retryAfter = Number(parsed.retryAfter);
+                }
+            } catch {
+                // An untrusted error body never becomes part of a client error.
+            }
+            if (code === 'GITHUB_API_UNAVAILABLE' && group !== 'read') available[group] = false;
+            if (code === 'GITHUB_API_UNAVAILABLE' && group === 'read') available.threads = false;
+            const unknown = mutation && (unknownCodes.includes(code) || !allowed);
+            throw new GitHubReviewError(unknown && !allowed ? 'UPSTREAM_FAILURE' : code,
+                {status: response.status, requestId, retryAfter, unknown});
+        }
+        if (group !== 'read') available[group] = true;
+        try {
+            if (!json) throw new Error();
+            return JSON.parse(await readBounded(response, limit));
+        } catch {
+            throw new GitHubReviewError('INVALID_RESPONSE', {unknown: mutation});
+        }
+    }
+
+    const checkNumber = (number: number) => {
+        if (!Number.isSafeInteger(number) || number < 1 || number > 2147483647) throw new GitHubReviewError('BAD_REQUEST');
+    };
+    const graphql = (operation: string, number: number, variables: Record<string, unknown>, submitId: string | undefined,
+        signal: AbortSignal | undefined, mutation = true) => {
+        checkNumber(number);
+        return call('/graphql/' + operation, {method: 'POST', body: {number, ...variables}, submitId, review: mutation, mutation,
+            group: mutation ? 'threads' : 'read', signal});
+    };
+    const shape = <T>(check: boolean, value: T, mutation = true): T => {
+        if (!check) throw new GitHubReviewError('INVALID_RESPONSE', {unknown: mutation});
+        return value;
+    };
+
+    return {
+        available,
+        /** The GitHub login of the last session this client used. */
+        account: () => account,
+        /** Reads the viewer's pending and recent reviews; with `submitId`, resolves that submission's unknown outcome. */
+        async context(number: number, submitId?: string, signal?: AbortSignal) {
+            const value = await graphql('pullRequestReviewContext', number, {}, submitId, signal, false);
+            const context = readContext(value, submitId !== undefined);
+            available.threads = true;
+            return context;
+        },
+        /** Step 1: a pending review on `commitOid`. */
+        async start(number: number, submitId: string, commitOid: string, signal?: AbortSignal) {
+            if (!isSha(commitOid)) throw new GitHubReviewError('BAD_REQUEST');
+            const value = await graphql('addPullRequestReview', number, {commitOid}, submitId, signal);
+            shape(isRecord(value) && value.state === 'PENDING' && value.commitOid === commitOid, value);
+        },
+        /** Step 2: one file-level thread on a project.source.json; resolves the number of threads the proxy has accepted. */
+        async thread(number: number, submitId: string, threadIndex: number, threadPath: string, body: string, signal?: AbortSignal) {
+            if (!isCount(threadIndex, 49) || !isReviewThreadPath(threadPath) || !body || body.length > 65536)
+                throw new GitHubReviewError('BAD_REQUEST');
+            const value = await graphql('addPullRequestReviewThread', number, {threadIndex, path: threadPath, body}, submitId, signal);
+            return shape(isRecord(value) && value.threads === threadIndex + 1, threadIndex + 1);
+        },
+        /** Step 3: publishes the pending review. */
+        async submit(number: number, submitId: string, threadCount: number, event: ReviewEvent, body: string, signal?: AbortSignal) {
+            if (!isCount(threadCount, 50) || !reviewEvents.includes(event) || body.length > 65536)
+                throw new GitHubReviewError('BAD_REQUEST');
+            const value = await graphql('submitPullRequestReview', number, {threadCount, event, body}, submitId, signal);
+            const review = (isRecord(value) ? value : {}) as Partial<Record<keyof SubmittedReview, unknown>>;
+            return shape(typeof review.state === 'string' && review.state !== 'PENDING' && isSha(review.commitOid) &&
+                typeof review.submittedAt === 'string' && typeof review.url === 'string', review as SubmittedReview);
+        },
+        /** Removes the pending review of the submission. */
+        async discard(number: number, submitId: string, signal?: AbortSignal) {
+            const value = await graphql('deletePullRequestReview', number, {}, submitId, signal);
+            shape(isRecord(value) && value.deleted === true, value);
+        },
+        /** The review-body route: one page of the pull request's reviews, oldest first. */
+        async reviews(number: number, page: number, signal?: AbortSignal): Promise<RestReview[]> {
+            checkNumber(number);
+            if (!Number.isSafeInteger(page) || page < 1 || page > 10) throw new GitHubReviewError('BAD_REQUEST');
+            const value = await call(`/pulls/${number}/reviews?page=${page}`, {group: 'body', limit: 4 * 1024 * 1024, signal});
+            if (!Array.isArray(value)) throw new GitHubReviewError('INVALID_RESPONSE');
+            return value.map(review => {
+                if (!isRecord(review) || !Number.isSafeInteger(review.id) || typeof review.state !== 'string' ||
+                    !(review.commit_id === null || isSha(review.commit_id)) || !optionalString(review.body))
+                    throw new GitHubReviewError('INVALID_RESPONSE');
+                const login = isRecord(review.user) && typeof review.user.login === 'string' ? review.user.login : null;
+                return {id: Number(review.id), login, commitId: review.commit_id as string | null, state: review.state,
+                    body: typeof review.body === 'string' ? review.body : ''};
+            });
+        },
+        /** The review-body route: creates and publishes a review with a body only. */
+        async create(number: number, submitId: string, commitOid: string, event: ReviewEvent, body: string, signal?: AbortSignal) {
+            checkNumber(number);
+            if (!isSha(commitOid) || !reviewEvents.includes(event) || body.length > 65536 || (!body && event !== 'APPROVE'))
+                throw new GitHubReviewError('BAD_REQUEST');
+            const value = await call(`/pulls/${number}/reviews`, {method: 'POST', body: {commit_id: commitOid, event, body},
+                submitId, review: true, mutation: true, group: 'body', limit: 1024 * 1024, signal});
+            return shape(isRecord(value) && typeof value.state === 'string' && typeof value.html_url === 'string',
+                {url: (value as {html_url: string}).html_url});
+        }
+    };
+}
+
+export type GitHubReviewApi = ReturnType<typeof createGitHubReviewApi>;