@osdlc/typed-gh 0.5.0 → 0.7.0

package/dist/verbs.js

@@ -7,12 +7,66 @@
  * asynchronous fan-out drive the same definitions without either duplicating
  * the other's parsing.
  *
- * `checked` marks a verb whose failure is thrown with stderr: every mutation,
- * and `prDiff`, which is a read. Other queries are unchecked and fold failure
- * into an absence value.
+ * `checked` marks a verb the runner throws for on a non-zero exit, with
+ * stderr: every mutation, and `prDiff`, which is a read. Other queries are run
+ * unchecked and `parse` folds a failure into `null`, which is the verb's
+ * *soft* reading. The clients' plain door reads them through `settle` (see
+ * `doors.ts`) instead: a failure throws, except where the verb declares
+ * `absent` or is a `probe`.
  */
 import { stderrOrError } from '@osdlc/command-seam';
-import { parseLabels, parsePullRequest } from "./parse.js";
+import { parseLabels, parsePrSearchHit, parsePullRequest, parseRepository } from "./parse.js";
+import { isAbsent } from "./failure.js";
+import { isRepoSlug, parsePrUrl } from "./repo.js";
+/** Whether a failed run says GitHub has no such `thing`: read from the same text the classifier reads. */
+function noSuch(thing) {
+    return (r) => isAbsent(thing, `${r.stderr}\n${r.stdout}`);
+}
+const HOSTNAME = /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?(?::\d+)?$/;
+/**
+ * Throw `RangeError` unless `target.repo` is `owner/name` and
+ * `target.hostname` is a bare host. Run by every verb that uses a target, so
+ * no text can reach gh as a flag or change the endpoint a call hits.
+ */
+export function checkTarget(target) {
+    if (target?.repo !== undefined && !isRepoSlug(target.repo)) {
+        throw new RangeError(`repo must be owner/name, got ${JSON.stringify(target.repo)}`);
+    }
+    if (target?.hostname !== undefined && !HOSTNAME.test(target.hostname)) {
+        throw new RangeError(`hostname must be a bare host, got ${JSON.stringify(target.hostname)}`);
+    }
+}
+/** `--repo [host/]owner/name` for `pr`, `issue` and `label` verbs; `repo` overrides the target's. */
+function repoArgs(target, repo) {
+    checkTarget(target);
+    const slug = repo ?? target?.repo;
+    if (slug === undefined)
+        return [];
+    if (repo !== undefined)
+        checkTarget({ repo });
+    return ['--repo', target?.hostname === undefined ? slug : `${target.hostname}/${slug}`];
+}
+/** `--hostname <host>` for `api` and `auth` verbs. */
+function hostArgs(target) {
+    checkTarget(target);
+    return target?.hostname === undefined ? [] : ['--hostname', target.hostname];
+}
+/** `GH_HOST` for the verbs gh gives no host flag. */
+function hostEnv(target) {
+    checkTarget(target);
+    return target?.hostname === undefined ? undefined : { GH_HOST: target.hostname };
+}
+/**
+ * `endpoint` with `{owner}` and `{repo}` filled from the target. With no
+ * target repo they are left for gh to fill from the clone.
+ */
+function fillRepo(endpoint, target) {
+    checkTarget(target);
+    if (target?.repo === undefined)
+        return endpoint;
+    const [owner, name] = target.repo.split('/');
+    return endpoint.replaceAll('{owner}', owner).replaceAll('{repo}', name);
+}
 /**
  * The cheapest useful set: enough to identify a PR and nothing more.
  *
@@ -94,6 +148,18 @@ function manyOrNull(r) {
     }
     return rows;
 }
+/** Throw `RangeError` unless `limit` is a positive integer. */
+function checkLimit(limit) {
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+        throw new RangeError(`limit must be a positive integer, got ${limit}`);
+    }
+}
+/** `rows` cut to `limit`, with whether there were more. Null stays null. */
+function limited(rows, limit) {
+    if (rows === null)
+        return null;
+    return { rows: rows.slice(0, limit), truncated: rows.length > limit };
+}
 /** A mutation's result carries no value. */
 function nothing() { }
 /**
@@ -172,43 +238,89 @@ function manyIssuesOrNull(r) {
     }
     return rows;
 }
-/** `gh pr list …` — open PRs by default. */
-export function prList(opts = {}) {
-    const argv = ['pr', 'list', '--state', opts.state ?? 'open'];
-    if (opts.repo !== undefined)
-        argv.push('--repo', opts.repo);
+/** `gh pr list …` — open PRs by default. `opts.repo` overrides the target's repo. */
+export function prList(opts = {}, target) {
+    const limit = opts.limit ?? 100;
+    checkLimit(limit);
+    const argv = ['pr', 'list', '--state', opts.state ?? 'open', ...repoArgs(target, opts.repo)];
     if (opts.base !== undefined)
         argv.push('--base', opts.base);
     if (opts.head !== undefined)
-        argv.push('--search', `head:${opts.head}`);
+        argv.push('--head', opts.head);
     if (opts.search !== undefined)
         argv.push('--search', opts.search);
     if (opts.author !== undefined)
         argv.push('--author', opts.author);
-    argv.push('--json', (opts.fields ?? PR_LIST_FIELDS).join(','));
-    argv.push('--limit', String(opts.limit ?? 100));
-    return { argv, checked: false, parse: manyOrNull };
+    // The exact-head filter below reads `headRefName`, so ask for it.
+    const fields = opts.fields ?? PR_LIST_FIELDS;
+    const asked = opts.head === undefined ? fields : withFields(fields, ['headRefName']);
+    argv.push('--json', asked.join(','));
+    argv.push('--limit', String(limit + 1));
+    const head = opts.head;
+    return {
+        argv,
+        checked: false,
+        readOnly: true,
+        parse(r) {
+            const result = limited(manyOrNull(r), limit);
+            if (result === null || head === undefined)
+                return result;
+            return { ...result, rows: result.rows.filter((pr) => pr.headRefName === head) };
+        },
+    };
+}
+/** `fields` with each of `required` added once, ahead of the rest. */
+function withFields(fields, required) {
+    return [...new Set([...required.filter((f) => !fields.includes(f)), ...fields])];
 }
-/** `gh pr view <n> --json …` — one PR, with the heavy fields by default. */
-export function prView(number, fields = PR_VIEW_FIELDS) {
+/**
+ * Throw `RangeError` when a string bound for gh's argv as a positional
+ * argument would read as a flag.
+ */
+function notAFlag(what, value) {
+    if (value.startsWith('-')) {
+        throw new RangeError(`${what} must not start with "-", got ${JSON.stringify(value)}`);
+    }
+}
+/**
+ * `gh pr view <number|branch|url> --json …` — one PR, with the heavy fields
+ * by default.
+ *
+ * A branch is the PR whose head is that branch, as gh picks it. A URL names
+ * its own repository and host, so the target is not passed with one. A
+ * string that starts with `-` throws `RangeError`.
+ */
+export function prView(ref, fields = PR_VIEW_FIELDS, target) {
+    if (typeof ref === 'string')
+        notAFlag('prView ref', ref);
     // `parsePullRequest` yields null without a `number`, so a field subset that
     // omits it would read as "no such PR". Always ask for it, and each field once.
-    const asked = [...new Set(fields.includes('number') ? fields : ['number', ...fields])];
+    const asked = withFields(fields, ['number']);
+    const isUrl = typeof ref === 'string' && parsePrUrl(ref) !== null;
     return {
-        argv: ['pr', 'view', String(number), '--json', asked.join(',')],
+        argv: [
+            'pr',
+            'view',
+            String(ref),
+            ...(isUrl ? [] : repoArgs(target)),
+            '--json',
+            asked.join(','),
+        ],
         checked: false,
+        readOnly: true,
+        absent: noSuch('pr'),
         parse: oneOrNull,
     };
 }
 /**
- * Open PRs whose head *starts with* `branch` — gh's own search semantics.
+ * Open PRs whose head is exactly `branch`.
  *
  * The common shape behind "which PR is this branch?", bundling the cheap
- * field set with a small limit. Pair it with {@link pickPrForBranch}, which
- * is what turns the prefix match into an exact one.
+ * field set with a small limit. More than one row comes back only when forks
+ * share the branch name.
  */
-export function openPrsForBranch(branch, limit = 5) {
-    return prList({ head: branch, limit, fields: PR_REF_FIELDS });
+export function openPrsForBranch(branch, limit = 5, target) {
+    return prList({ head: branch, limit, fields: PR_REF_FIELDS }, target);
 }
 /**
  * `gh pr view <n> --json body -q .body` — just the PR body. Null when gh
@@ -216,29 +328,159 @@ export function openPrsForBranch(branch, limit = 5) {
  * so every trailing `\r` and `\n` is trimmed (including any that were part of
  * the body, such as the `\r\n` of a body saved with CRLF line endings).
  */
-export function prBody(number) {
+export function prBody(number, target) {
     return {
-        argv: ['pr', 'view', String(number), '--json', 'body', '-q', '.body'],
+        argv: ['pr', 'view', String(number), ...repoArgs(target), '--json', 'body', '-q', '.body'],
         checked: false,
+        readOnly: true,
         parse: (r) => (r.exitCode === 0 ? r.stdout.replace(/[\r\n]+$/, '') : null),
     };
 }
 /**
  * `gh api [-i] [-H If-None-Match: …] <endpoint>` — a GET against the REST API. `{owner}` and
- * `{repo}` placeholders in the endpoint are filled by gh from the cwd's repo.
+ * `{repo}` placeholders in the endpoint are filled from the target's repo, or by gh from the
+ * cwd's repo when the target names none.
  * Unchecked: failure is a value (`ok: false`), so a caller can tell a 304
  * from an outage.
  */
-export function api(endpoint, opts = {}) {
+export function api(endpoint, opts = {}, target) {
+    notAFlag('api endpoint', endpoint);
     const conditional = opts.etag !== undefined && opts.etag !== null && opts.etag !== '';
     const withHeaders = conditional || opts.includeHeaders === true;
-    const argv = ['api'];
+    const paginate = opts.paginate === true;
+    if (paginate && withHeaders) {
+        throw new RangeError('api: paginate cannot be combined with etag or includeHeaders');
+    }
+    const argv = ['api', ...hostArgs(target)];
     if (withHeaders)
         argv.push('-i');
     if (conditional)
         argv.push('-H', `If-None-Match: ${opts.etag}`);
-    argv.push(endpoint);
-    return { argv, checked: false, parse: (r) => parseApi(r, withHeaders) };
+    if (paginate)
+        argv.push('--paginate', '--slurp');
+    argv.push(fillRepo(endpoint, target));
+    return {
+        argv,
+        checked: false,
+        readOnly: true,
+        probe: true,
+        parse(r) {
+            const response = parseApi(r, withHeaders);
+            return paginate ? { ...response, body: flattenPages(response.body) } : response;
+        },
+    };
+}
+/** `--slurp` pages joined into one array when every page is an array. */
+function flattenPages(body) {
+    if (!Array.isArray(body) || !body.every(Array.isArray))
+        return body;
+    return body.flat();
+}
+/**
+ * `gh api graphql -f query=… [--paginate --slurp]` — a GraphQL query.
+ *
+ * Returns each page's `data`, one entry per page (one without `paginate`),
+ * or null when the call failed, the output did not parse, or any page
+ * carries `errors` or lacks `data`: a partial answer is no answer. Read one
+ * connection across the pages with {@link nodesAt}.
+ *
+ * A string variable of exactly `{owner}` or `{repo}` is filled from the
+ * target's repo, or by gh from the clone. A mutation document throws
+ * `RangeError`: this is a read, and changes go through `raw`.
+ *
+ * @experimental
+ */
+export function graphql(query, variables = {}, opts = {}, target) {
+    checkTarget(target);
+    const body = query.replace(/^(?:\s|#[^\n]*\n?)*/, '');
+    if (/^mutation\b/.test(body) || /^subscription\b/.test(body)) {
+        throw new RangeError('graphql: only queries are allowed; send a mutation through raw');
+    }
+    const paginate = opts.paginate === true;
+    if (paginate && !query.includes('$endCursor')) {
+        throw new RangeError('graphql: paginate needs a query that takes $endCursor');
+    }
+    const argv = ['api', 'graphql', ...hostArgs(target)];
+    if (paginate)
+        argv.push('--paginate', '--slurp');
+    const [owner, name] = target?.repo?.split('/') ?? [];
+    for (const [key, value] of Object.entries(variables)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            throw new RangeError(`graphql: bad variable name ${JSON.stringify(key)}`);
+        }
+        if (typeof value === 'string') {
+            const filled = value === '{owner}' ? owner : value === '{repo}' ? name : undefined;
+            if (filled !== undefined)
+                argv.push('-f', `${key}=${filled}`);
+            else if (value === '{owner}' || value === '{repo}')
+                argv.push('-F', `${key}=${value}`);
+            else
+                argv.push('-f', `${key}=${value}`);
+        }
+        else {
+            argv.push('-F', `${key}=${value === null ? 'null' : String(value)}`);
+        }
+    }
+    argv.push('-f', `query=${query}`);
+    return {
+        argv,
+        checked: false,
+        readOnly: true,
+        parse(r) {
+            if (r.exitCode !== 0)
+                return null;
+            let data;
+            try {
+                data = JSON.parse(r.stdout);
+            }
+            catch {
+                return null;
+            }
+            const pages = paginate ? data : [data];
+            if (!Array.isArray(pages))
+                return null;
+            const out = [];
+            for (const page of pages) {
+                if (page === null || typeof page !== 'object')
+                    return null;
+                const rec = page;
+                if (Array.isArray(rec['errors']) && rec['errors'].length > 0)
+                    return null;
+                if (rec['data'] === null || typeof rec['data'] !== 'object')
+                    return null;
+                out.push(rec['data']);
+            }
+            return out;
+        },
+    };
+}
+/**
+ * The `nodes` of one connection, joined across {@link graphql} pages: walk
+ * `path` into each page and take its `nodes` array. Null when `pages` is
+ * null, or any page lacks the path or a `nodes` array, so a page that came
+ * back short is never read as fewer rows.
+ *
+ * @experimental
+ */
+export function nodesAt(pages, path) {
+    if (pages === null)
+        return null;
+    const out = [];
+    for (const page of pages) {
+        let at = page;
+        for (const key of path) {
+            if (at === null || typeof at !== 'object')
+                return null;
+            at = at[key];
+        }
+        if (at === null || typeof at !== 'object')
+            return null;
+        const nodes = at['nodes'];
+        if (!Array.isArray(nodes))
+            return null;
+        out.push(...nodes);
+    }
+    return out;
 }
 /** One header block off the front of `text`: the block, and what follows its blank line. */
 function takeHeaderBlock(text) {
@@ -295,64 +537,208 @@ function parseApi(r, withHeaders) {
 }
 /** `gh --version` — the install probe. True when `gh` runs. */
 export function installed() {
-    return { argv: ['--version'], checked: false, parse: (r) => r.exitCode === 0 };
+    return {
+        argv: ['--version'],
+        checked: false,
+        readOnly: true,
+        probe: true,
+        parse: (r) => r.exitCode === 0,
+    };
 }
-/** `gh auth status` — the credential probe. */
-export function authStatus() {
+/** `gh auth status [--hostname <host>]` — the credential probe, for one host when the target names it. */
+export function authStatus(target) {
     return {
-        argv: ['auth', 'status'],
+        argv: ['auth', 'status', ...hostArgs(target)],
         checked: false,
+        readOnly: true,
+        probe: true,
         parse: (r) => ({ ok: r.exitCode === 0, detail: stderrOrError(r) || r.stdout.trim() }),
     };
 }
 /**
- * `gh label list --json name,color,description` — every label on the repo.
- * `limit` defaults to 1000. `gh`'s own default is 30, which would cut off a
- * repository with more labels than that without saying so.
+ * `gh label list --json name,color,description` — every label on the repo,
+ * up to `limit` (default 1000; `gh`'s own default is 30).
  */
-export function labelList(opts = {}) {
+export function labelList(opts = {}, target) {
+    const limit = opts.limit ?? 1000;
+    checkLimit(limit);
     return {
         argv: [
             'label',
             'list',
+            ...repoArgs(target),
             '--json',
             'name,color,description',
             '--limit',
-            String(opts.limit ?? 1000),
+            String(limit + 1),
         ],
         checked: false,
-        parse: manyLabelsOrNull,
+        readOnly: true,
+        parse: (r) => limited(manyLabelsOrNull(r), limit),
     };
 }
 /** `gh issue list --json …` — open issues by default, optionally by label. */
-export function issueList(opts = {}) {
-    const argv = ['issue', 'list'];
+export function issueList(opts = {}, target) {
+    const limit = opts.limit ?? 200;
+    checkLimit(limit);
+    const argv = ['issue', 'list', ...repoArgs(target)];
     if (opts.label !== undefined)
         argv.push('--label', opts.label);
-    argv.push('--json', ISSUE_FIELDS, '--limit', String(opts.limit ?? 200));
-    return { argv, checked: false, parse: manyIssuesOrNull };
+    argv.push('--json', ISSUE_FIELDS, '--limit', String(limit + 1));
+    return { argv, checked: false, readOnly: true, parse: (r) => limited(manyIssuesOrNull(r), limit) };
 }
 /** `gh issue view <n> --json …` — one issue, same field set as {@link issueList}. */
-export function issueView(number) {
+export function issueView(number, target) {
     return {
-        argv: ['issue', 'view', String(number), '--json', ISSUE_FIELDS],
+        argv: ['issue', 'view', String(number), ...repoArgs(target), '--json', ISSUE_FIELDS],
         checked: false,
+        readOnly: true,
+        absent: noSuch('issue'),
         parse: oneIssueOrNull,
     };
 }
+/** The `gh repo list`/`view --json` fields a {@link Repository} reads. */
+export const REPO_FIELDS = [
+    'nameWithOwner',
+    'description',
+    'defaultBranchRef',
+    'visibility',
+    'isArchived',
+    'url',
+];
+/** The `gh search prs --json` fields a {@link PrSearchHit} reads. */
+export const SEARCH_PR_FIELDS = [
+    'number',
+    'title',
+    'state',
+    'url',
+    'isDraft',
+    'repository',
+    'author',
+    'labels',
+    'createdAt',
+    'updatedAt',
+    'closedAt',
+];
+/** Parse a `--json` array payload with `parse`, dropping rows it rejects. Null on failure. */
+function rowsOrNull(r, parse) {
+    if (r.exitCode !== 0)
+        return null;
+    let data;
+    try {
+        data = JSON.parse(r.stdout || '[]');
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(data))
+        return null;
+    return data.map(parse).filter((row) => row !== null);
+}
+/**
+ * `gh repo list <owner> --json …` — an owner's repositories. The host comes
+ * from the target (`GH_HOST`); the target's repo is not used.
+ */
+export function repoList(owner, opts = {}, target) {
+    notAFlag('repoList owner', owner);
+    const limit = opts.limit ?? 100;
+    checkLimit(limit);
+    const argv = ['repo', 'list', owner];
+    if (opts.archived === true)
+        argv.push('--archived');
+    if (opts.archived === false)
+        argv.push('--no-archived');
+    if (opts.visibility !== undefined)
+        argv.push('--visibility', opts.visibility);
+    argv.push('--json', withFields(opts.fields ?? REPO_FIELDS, ['nameWithOwner']).join(','));
+    argv.push('--limit', String(limit + 1));
+    return {
+        argv,
+        checked: false,
+        readOnly: true,
+        env: hostEnv(target),
+        parse: (r) => limited(rowsOrNull(r, parseRepository), limit),
+    };
+}
+/**
+ * `gh repo view [<[host/]owner/name>] --json …` — one repository: `repo`,
+ * else the target's repo, else the clone at the client's cwd.
+ */
+export function repoView(repo, fields = REPO_FIELDS, target) {
+    checkTarget(target);
+    if (repo !== undefined)
+        checkTarget({ repo });
+    const slug = repo ?? target?.repo;
+    const argv = ['repo', 'view'];
+    if (slug !== undefined) {
+        argv.push(target?.hostname === undefined ? slug : `${target.hostname}/${slug}`);
+    }
+    argv.push('--json', withFields(fields, ['nameWithOwner']).join(','));
+    return {
+        argv,
+        checked: false,
+        readOnly: true,
+        absent: noSuch('repo'),
+        parse(r) {
+            if (r.exitCode !== 0)
+                return null;
+            try {
+                return parseRepository(JSON.parse(r.stdout));
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+/**
+ * `gh search prs [flags] -- <query>` — pull requests across repositories,
+ * with GitHub's search syntax in `query` (it may start with `-`, as in
+ * `-label:bug`). The host comes from the target (`GH_HOST`); the target's
+ * repo is not used, so pass `opts.repo` or `opts.owner` to narrow.
+ */
+export function searchPrs(query, opts = {}, target) {
+    const limit = opts.limit ?? 100;
+    checkLimit(limit);
+    const argv = ['search', 'prs'];
+    if (opts.owner !== undefined) {
+        notAFlag('searchPrs owner', opts.owner);
+        argv.push('--owner', opts.owner);
+    }
+    if (opts.repo !== undefined) {
+        checkTarget({ repo: opts.repo });
+        argv.push('--repo', opts.repo);
+    }
+    if (opts.state === 'merged')
+        argv.push('--merged');
+    else if (opts.state !== undefined)
+        argv.push('--state', opts.state);
+    argv.push('--json', withFields(opts.fields ?? SEARCH_PR_FIELDS, ['number']).join(','));
+    argv.push('--limit', String(limit + 1));
+    if (query !== '')
+        argv.push('--', query);
+    return {
+        argv,
+        checked: false,
+        readOnly: true,
+        env: hostEnv(target),
+        parse: (r) => limited(rowsOrNull(r, parsePrSearchHit), limit),
+    };
+}
 /**
  * `gh pr create …`, returning the new PR's URL: the last line gh printed that
  * starts with `http://` or `https://`. `''` when it printed none, as
  * {@link prComment} does. A line after the URL, such as a tip, is skipped.
  */
-export function createPr(opts) {
-    const argv = ['pr', 'create', '--head', opts.head, '--base', opts.base];
+export function createPr(opts, target) {
+    const argv = ['pr', 'create', ...repoArgs(target), '--head', opts.head, '--base', opts.base];
     if (opts.draft)
         argv.push('--draft');
     argv.push('--title', opts.title, '--body', opts.body);
     return {
         argv,
         checked: true,
+        readOnly: false,
         parse(r) {
             const urls = r.stdout
                 .split('\n')
@@ -363,31 +749,31 @@ export function createPr(opts) {
     };
 }
 /** `gh pr edit <n>` — retitle or rewrite the body. */
-export function editPr(number, opts) {
-    const argv = ['pr', 'edit', String(number)];
+export function editPr(number, opts, target) {
+    const argv = ['pr', 'edit', String(number), ...repoArgs(target)];
     if (opts.title !== undefined)
         argv.push('--title', opts.title);
     if (opts.body !== undefined)
         argv.push('--body', opts.body);
-    return { argv, checked: true, parse: nothing };
+    return { argv, checked: true, readOnly: false, parse: nothing };
 }
 /** `gh pr edit <n> --body` — rewrite just the body. */
-export function editPrBody(number, body) {
-    return editPr(number, { body });
+export function editPrBody(number, body, target) {
+    return editPr(number, { body }, target);
 }
 /** `gh pr update-branch <n> [--rebase]` — bring the head up to date with its base. */
-export function prUpdateBranch(number, style = 'merge') {
-    const argv = ['pr', 'update-branch', String(number)];
+export function prUpdateBranch(number, style = 'merge', target) {
+    const argv = ['pr', 'update-branch', String(number), ...repoArgs(target)];
     if (style === 'rebase')
         argv.push('--rebase');
-    return { argv, checked: true, parse: nothing };
+    return { argv, checked: true, readOnly: false, parse: nothing };
 }
 /** `gh pr ready <n> [--undo]` — mark a draft PR ready for review, or (with `draft`) convert it back to a draft. */
-export function prSetDraft(number, draft) {
-    const argv = ['pr', 'ready', String(number)];
+export function prSetDraft(number, draft, target) {
+    const argv = ['pr', 'ready', String(number), ...repoArgs(target)];
     if (draft)
         argv.push('--undo');
-    return { argv, checked: true, parse: nothing };
+    return { argv, checked: true, readOnly: false, parse: nothing };
 }
 /**
  * `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<id> -f body=…` — rewrite one
@@ -403,20 +789,22 @@ export function prSetDraft(number, draft) {
  *
  * @experimental
  */
-export function issueCommentEdit(commentId, body) {
+export function issueCommentEdit(commentId, body, target) {
     if (!/^[0-9]+$/.test(commentId)) {
         throw new RangeError(`issueCommentEdit: commentId must be a numeric REST id, got ${JSON.stringify(commentId)}`);
     }
     return {
         argv: [
             'api',
+            ...hostArgs(target),
             '-X',
             'PATCH',
-            `repos/{owner}/{repo}/issues/comments/${commentId}`,
+            fillRepo(`repos/{owner}/{repo}/issues/comments/${commentId}`, target),
             '-f',
             `body=${body}`,
         ],
         checked: true,
+        readOnly: false,
         parse: nothing,
     };
 }
@@ -427,16 +815,17 @@ export function issueCommentEdit(commentId, body) {
  * merge can never ride in unreviewed. The branch is left alone (no
  * `--delete-branch`); deleting it is the caller's job.
  */
-export function prMerge(number, opts) {
+export function prMerge(number, opts, target) {
     const argv = [
         'pr',
         'merge',
         String(number),
+        ...repoArgs(target),
         `--${opts.method}`,
         '--match-head-commit',
         opts.headSha,
     ];
-    return { argv, checked: true, parse: nothing };
+    return { argv, checked: true, readOnly: false, parse: nothing };
 }
 const REVIEW_THREADS_QUERY = 'query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){reviewThreads(first:100){pageInfo{hasNextPage} nodes{isResolved isOutdated comments(last:1){nodes{author{login}}}}}}}}';
 /**
@@ -446,21 +835,26 @@ const REVIEW_THREADS_QUERY = 'query($owner:String!,$name:String!,$number:Int!){r
  * PR is clear to merge must read "could not tell" differently from "no
  * threads".
  */
-export function prReviewThreads(number) {
+export function prReviewThreads(number, target) {
+    checkTarget(target);
+    // `-F` lets gh fill the placeholders from the clone; real values go as plain strings.
+    const [owner, name] = target?.repo?.split('/') ?? [];
+    const repo = owner === undefined || name === undefined
+        ? ['-F', 'owner={owner}', '-F', 'name={repo}']
+        : ['-f', `owner=${owner}`, '-f', `name=${name}`];
     return {
         argv: [
             'api',
             'graphql',
-            '-F',
-            'owner={owner}',
-            '-F',
-            'name={repo}',
+            ...hostArgs(target),
+            ...repo,
             '-F',
             `number=${number}`,
             '-f',
             `query=${REVIEW_THREADS_QUERY}`,
         ],
         checked: false,
+        readOnly: true,
         parse(r) {
             if (r.exitCode !== 0)
                 return null;
@@ -492,27 +886,28 @@ export function prReviewThreads(number) {
  * `--force` makes it safe to repeat: when the label already exists, its color
  * and description are set to these instead of failing.
  */
-export function createLabel(opts) {
+export function createLabel(opts, target) {
     const argv = [
         'label',
         'create',
         opts.name,
+        ...repoArgs(target),
         '--color',
         opts.color,
         '--description',
         opts.description,
         '--force',
     ];
-    return { argv, checked: true, parse: nothing };
+    return { argv, checked: true, readOnly: false, parse: nothing };
 }
 /** `gh label edit <name>` — recolor or redescribe; omits a flag not given. */
-export function editLabel(name, opts) {
-    const argv = ['label', 'edit', name];
+export function editLabel(name, opts, target) {
+    const argv = ['label', 'edit', name, ...repoArgs(target)];
     if (opts.color !== undefined)
         argv.push('--color', opts.color);
     if (opts.description !== undefined)
         argv.push('--description', opts.description);
-    return { argv, checked: true, parse: nothing };
+    return { argv, checked: true, readOnly: false, parse: nothing };
 }
 /**
  * `gh issue edit <n> [--remove-label <current>] --add-label <new>` — swap
@@ -531,22 +926,28 @@ export function editLabel(name, opts) {
  * issue carries no prior label to remove — the `--remove-label` flag is then
  * omitted rather than passed empty.
  */
-export function setIssueLabel(number, currentLabel, newLabel) {
-    const argv = ['issue', 'edit', String(number)];
+export function setIssueLabel(number, currentLabel, newLabel, target) {
+    const argv = ['issue', 'edit', String(number), ...repoArgs(target)];
     if (currentLabel !== null)
         argv.push('--remove-label', currentLabel);
     argv.push('--add-label', newLabel);
-    return { argv, checked: true, parse: nothing };
+    return { argv, checked: true, readOnly: false, parse: nothing };
 }
 /** `gh pr diff <n>` — the PR's unified diff, as text. Checked: an empty diff is a value, a failed call is not. */
-export function prDiff(number) {
-    return { argv: ['pr', 'diff', String(number)], checked: true, parse: (r) => r.stdout };
+export function prDiff(number, target) {
+    return {
+        argv: ['pr', 'diff', String(number), ...repoArgs(target)],
+        checked: true,
+        readOnly: true,
+        parse: (r) => r.stdout,
+    };
 }
 /** `gh pr comment <n> --body <body>` — post a conversation comment, returning the URL gh prints ('' if none). */
-export function prComment(number, body) {
+export function prComment(number, body, target) {
     return {
-        argv: ['pr', 'comment', String(number), '--body', body],
+        argv: ['pr', 'comment', String(number), ...repoArgs(target), '--body', body],
         checked: true,
+        readOnly: false,
         parse(r) {
             const lines = r.stdout
                 .split('\n')
@@ -562,12 +963,12 @@ export function prComment(number, body) {
  * when GitHub's reply carried none). The event is always `COMMENT`: this
  * library does not offer a way to approve or request changes. Goes through
  * `gh api` with the payload on stdin, because `gh pr review` cannot attach
- * line-anchored comments; `{owner}`/`{repo}` are filled in by `gh` from the
- * client's working directory.
+ * line-anchored comments; `{owner}`/`{repo}` come from the target's repo, or
+ * are filled in by `gh` from the client's working directory.
  *
  * @experimental
  */
-export function createReview(number, opts) {
+export function createReview(number, opts, target) {
     const payload = {
         commit_id: opts.commitId,
         body: opts.body,
@@ -582,13 +983,15 @@ export function createReview(number, opts) {
     return {
         argv: [
             'api',
+            ...hostArgs(target),
             '--method',
             'POST',
-            `repos/{owner}/{repo}/pulls/${number}/reviews`,
+            fillRepo(`repos/{owner}/{repo}/pulls/${number}/reviews`, target),
             '--input',
             '-',
         ],
         checked: true,
+        readOnly: false,
         input: JSON.stringify(payload),
         parse(r) {
             try {
@@ -603,16 +1006,31 @@ export function createReview(number, opts) {
 }
 // ── helpers over the parsed rows ────────────────────────────────────────────
 /**
- * The row whose `headRefName` exactly equals `branch`, or null.
+ * The first row whose `headRefName` exactly equals `branch`, or null.
  *
- * gh's `head:` search is a prefix match, so `task/foo` also returns
- * `task/foo-2`. Every caller that means one branch needs this filter.
+ * `prList({ head })` already filters exactly. This is for rows from anywhere
+ * else, such as a `search` query with gh's `head:` qualifier, which matches
+ * `task/foo-2` for `task/foo`.
  */
 export function pickPrForBranch(rows, branch) {
     if (rows === null)
         return null;
     return rows.find((r) => r.headRefName === branch) ?? null;
 }
+/**
+ * The PR a branch names, from `prList({ head, state: 'all' })` rows: the open
+ * one, or else the first row (gh lists newest first). Null when there are no
+ * rows or the call failed.
+ */
+export function branchPr(result) {
+    if (result === null)
+        return null;
+    return result.rows.find((r) => r.state === 'OPEN') ?? result.rows[0] ?? null;
+}
+/** The field set {@link branchPr} needs, ahead of `fields`. */
+export function branchPrFields(fields) {
+    return withFields(fields, ['number', 'state', 'headRefName']);
+}
 /**
  * True when GitHub has not finished computing this PR's mergeability.
  *