@osdlc/typed-gh 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- d558059: Reach a repository without a clone, find a pull request from what a person typed, read every page of a list, and list repositories and search pull requests. Some changes break callers of 0.5. They are marked `Breaking:`.
+  
+  - `Gh` and `AsyncGh` take optional `repo` (`owner/name`) and `hostname` options, and `withRepo(repo)` returns the same client aimed at another repository. The target goes into each call's argv: `--repo host/owner/name` on `pr`, `issue` and `label` calls, `--hostname` and a filled `{owner}/{repo}` on `api` calls, and `--hostname` on `authStatus`. Every verb builder takes an optional `GhTarget` as its last argument. An invalid `repo` or `hostname` throws `RangeError`.
+  - `hostname` is any GitHub host: `github.com`, GitHub Enterprise Server, or a `<tenant>.ghe.com` host.
+  - Breaking: `parsePrUrl` accepts any GitHub host and returns `hostname` in its `PullRequestRef`. Before, it returned null for a host other than `github.com`.
+  - `prView` takes a number, a branch or a URL. A URL is passed without the client's target. A string that starts with `-` throws `RangeError`.
+  - `prFind(input)` returns the one PR that `input` names, and `parsePrRef(input)` reads it without running `gh`: `42`, `#42`, `owner/name#42`, a URL, or a branch name. Bare digits are a number first and then a branch. A branch gives its open PR, else its newest closed or merged one.
+  - Breaking: `prList({ head })` matches the head branch exactly, through `gh pr list --head`. Before, it passed `--search head:<branch>`, which matched by prefix.
+  - Breaking: `prList`, `issueList` and `labelList` return `{ rows, truncated } | null` instead of an array or null. Each asks `gh` for one row more than `limit`, and `truncated` is true when it came back. A `limit` that is not a positive integer throws `RangeError`. `openPrsForBranch` returns the same shape. The new `ListResult` type names it.
+  - `api` takes `paginate: true` to fetch every page; pages of arrays are joined into one `body`. With `etag` or `includeHeaders` it throws `RangeError`. An endpoint that starts with `-` throws `RangeError`.
+  - `graphql(query, variables, { paginate })` runs a GraphQL query and returns each page's `data`, or null when the call failed or any page has `errors` or no `data`. It refuses a mutation. `nodesAt(pages, path)` joins one connection's nodes across pages. Both are experimental, with `GraphqlOptions` and `GraphqlVariable`.
+  - Every `GhVerb` carries `readOnly`: true for every query and `prDiff`, false for every mutation. `GhVerb` also has an optional `env`.
+  - `repoList(owner)` and `repoView(repo?)` return the new `Repository` type. `searchPrs(query)` returns `PrSearchHit` rows, since `gh search prs` has its own field set. `REPO_FIELDS` and `SEARCH_PR_FIELDS` name their fields. `gh repo list` and `gh search` take no host flag, so the host reaches them as `GH_HOST`.
+  - New types: `GhTarget`, `GhOptions`, `AsyncGhOptions`, `ListResult`, `PrRef`, `Repository`, `RepositoryVisibility`, `PrSearchHit`, `RepoListOptions` and `SearchPrsOptions`.
+
+### Patch Changes
+
+- Updated dependencies [4d13bd9]
+  - @osdlc/typed-git@0.5.3
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -25,7 +25,7 @@ import { Gh, type PrListOptions, type PullRequest } from '@osdlc/typed-gh'
 const gh = new Gh(process.cwd())
 
 const filter: PrListOptions = { state: 'open', base: 'main' }
-const prs: PullRequest[] = gh.prList(filter) ?? []
+const prs: PullRequest[] = gh.prList(filter)?.rows ?? []
 ```
 
 The `examples` folder in the repository runs the same calls as tests.
@@ -36,8 +36,8 @@ The `examples` folder in the repository runs the same calls as tests.
   Octokit.
 - **You sign in with a token, a GitHub App or OAuth.** This package reads no token.
 - **You make many calls or poll in a loop.** Each call starts a `gh` process.
-- **You need the whole API typed.** This package covers the calls listed below. `api()` is a GET.
-  Anything else goes through `raw`.
+- **You need the whole API typed.** This package covers the calls listed below. `api()` is a GET
+  and `graphql()` is a query. Anything else goes through `raw`.
 
 ## How it compares
 
@@ -96,9 +96,79 @@ that decides whether to merge can then match every member.
 | **mutations** | throw `CommandFailed`, carrying argv and the full result. |
 | **`raw(argv)`** | hand back the raw `CommandResult`; you decide. |
 
-A query returns `null`, never `[]` on failure. `prList()` returning `[]` means
-*this repository has no open PRs*. `null` means *we could not ask*. If the two
-were the same, an expired credential would read as "nothing to do".
+A query returns `null`, never an empty list on failure. `prList()` returning
+`{ rows: [], truncated: false }` means *this repository has no open PRs*.
+`null` means *we could not ask*. If the two were the same, an expired
+credential would read as "nothing to do".
+
+## A list says when its limit cut it short
+
+`gh --limit` cuts a list without saying so. Every list query here asks for
+one row more than `limit` and returns `{ rows, truncated }`: at most `limit`
+rows, and `truncated: true` when there were more.
+
+```ts
+const page: ListResult<PullRequest> | null = gh.prList({ limit: 50 })
+
+if (page?.truncated) console.warn('more than 50 open PRs; raise the limit')
+```
+
+`prList`, `issueList`, `labelList`, `repoList` and `searchPrs` all work this
+way. A `limit` that is not a positive integer throws `RangeError`.
+
+## A repository without a clone
+
+By default a client talks to the repository of the clone at its directory.
+Name a repository, a host, or both, and every call targets them instead, so
+no clone is needed:
+
+```ts
+const acme = new Gh(process.cwd(), { repo: 'acme/widgets', hostname: 'github.acme.com' })
+
+acme.prView(42)
+acme.withRepo('acme/gadgets').prList()
+acme.api('repos/{owner}/{repo}/branches')
+```
+
+The target goes into the argv, so a `CommandFailed` shows which repository a
+call hit: `pr`, `issue` and `label` calls get `--repo github.acme.com/acme/widgets`,
+`api` calls get `--hostname` and a filled `{owner}/{repo}`, and `authStatus`
+asks about that host. `repoList` and `searchPrs` have no host flag in gh, so
+they get `GH_HOST` in the environment. `withRepo` and `at` keep the runner and
+the rest of the target.
+
+`hostname` is any GitHub host: `github.com`, a GitHub Enterprise Server host,
+or a `<tenant>.ghe.com` host. gh speaks only GitHub's API, so Forgejo, Gitea
+and GitLab are out of reach. A `repo` that is not `owner/name`, or a
+`hostname` that is not a bare host, throws `RangeError`.
+
+## Finding a pull request
+
+`prView` takes a number, a branch or a URL. A URL names its own repository
+and host, so the client's target is not added to it.
+
+```ts
+gh.prView(42)
+gh.prView('feature/login')
+gh.prView('https://github.acme.com/acme/widgets/pull/42')
+```
+
+`prFind` takes what a person typed and runs the lookup it needs:
+
+```ts
+const pr: PullRequest | null = gh.prFind(process.argv[2] ?? '')
+```
+
+It reads the text with `parsePrRef`, which starts no process: `42` and `#42`
+are numbers, `owner/name#42` is a number in that repository, a URL is a URL,
+and any other valid branch name is a branch. Bare digits are tried as a PR
+number first and then as a branch, since a branch can be named `42`. A branch
+gives its open PR, or else its newest closed or merged one, so a tool run
+after the merge still finds it.
+
+`prList({ head })` matches the head branch exactly: `task/foo` never returns
+`task/foo-2`. Two forks can share a branch name; ask for
+`headRepositoryOwner` to tell them apart.
 
 ## Two shape hazards it absorbs
 
@@ -184,10 +254,10 @@ threads?.filter((t) => !t.isResolved)
 
 ```ts
 const issue: IssueRow | null = gh.issueView(7)
-const triage: IssueRow[] | null = gh.issueList({ label: 'status:triage', limit: 50 })
+const triage: ListResult<IssueRow> | null = gh.issueList({ label: 'status:triage', limit: 50 })
 gh.setIssueLabel(7, 'status:triage', 'status:define')
 
-const labels: Label[] | null = gh.labelList({ limit: 100 })
+const labels: ListResult<Label> | null = gh.labelList({ limit: 100 })
 gh.createLabel({ name: 'status:triage', color: '1f6feb', description: 'Triage stage' })
 gh.editLabel('status:triage', { description: 'Waiting for triage' })
 ```
@@ -253,8 +323,9 @@ await gh.prComment(42, 'rebased') // the comment's URL, or ''
 await gh.prUpdateBranch(42, 'rebase')
 ```
 
-These methods take `AsyncCallOptions`: `raw`, `rawChecked`, `prList`, `prView`, `openPrFor`, `prViewSettled`, `prBody`, `api`,
-`labelList`, `issueList` and `issueView`. The options are `timeoutMs` and an `AbortSignal` in
+These methods take `AsyncCallOptions`: `raw`, `rawChecked`, `prList`, `prView`, `prFind`,
+`openPrFor`, `prViewSettled`, `prBody`, `api`, `graphql`, `labelList`, `issueList`, `issueView`,
+`repoList`, `repoView` and `searchPrs`. The options are `timeoutMs` and an `AbortSignal` in
 `signal`.
 
 `api(endpoint, opts)` (on `Gh` and `AsyncGh`) is a REST GET through `gh api`.
@@ -263,7 +334,50 @@ It never throws; the result is `{ ok, status, etag, body, malformed, stderr, err
 was stopped (a missing binary, a timeout).
 Pass `etag` for a conditional request (`If-None-Match`; a 304 comes back as
 `status: 304, body: null`), or `includeHeaders: true` to read status and ETag
-without one. If `gh` prints more than one header block, the last one is read. `{owner}` and `{repo}` in the endpoint are filled in by gh.
+without one. If `gh` prints more than one header block, the last one is read. `{owner}` and
+`{repo}` in the endpoint come from the client's repo, or are filled in by gh from the clone.
+
+## Reading every page
+
+`api` with `paginate: true` fetches every page and, when each page is an array, joins them into one
+`body`:
+
+```ts
+const branches = gh.api('repos/{owner}/{repo}/branches', { paginate: true }).body
+```
+
+`graphql` (experimental) runs a query and returns each page's `data`. It returns `null` when the
+call failed or any page has `errors` or no `data`: a partial answer is no answer. `nodesAt` joins
+one connection's `nodes` across the pages, and is `null` when any page lacks them.
+
+```ts
+const query = `query($owner: String!, $name: String!, $endCursor: String) {
+  repository(owner: $owner, name: $name) {
+    pullRequests(first: 100, after: $endCursor) {
+      pageInfo { hasNextPage endCursor }
+      nodes { number title }
+    }
+  }
+}`
+const pages = gh.graphql(query, { owner: '{owner}', name: '{repo}' }, { paginate: true })
+const prs = nodesAt(pages, ['repository', 'pullRequests'])
+```
+
+With `paginate`, the query must take `$endCursor` and page one connection; gh follows only that
+one. `graphql` refuses a mutation with `RangeError`; send one through `raw`.
+
+## Repositories and search
+
+```ts
+const repos: ListResult<Repository> | null = gh.repoList('acme', { archived: false, limit: 200 })
+const repo: Repository | null = gh.repoView('acme/widgets')
+const hits: ListResult<PrSearchHit> | null = gh.searchPrs('TICKET-123', { owner: 'acme' })
+```
+
+A `Repository` carries `nameWithOwner`, `owner`, `name`, `description`, `defaultBranch`,
+`visibility`, `isArchived` and `url`. `gh search prs` has its own field set: a `PrSearchHit` names
+its `repository` but has no head or base branch, so it is not a `PullRequest`. Its `state` is
+upper-cased to match. The query takes GitHub's search syntax and may start with `-`.
 
 ## Injecting the subprocess seam
 
@@ -274,7 +388,7 @@ suite runs offline:
 ```ts
 const empty: CommandRunner = { run: () => ({ exitCode: 0, stdout: '[]', stderr: '' }) }
 
-new Gh('/repo', { runner: empty }).prList() // []
+new Gh('/repo', { runner: empty }).prList() // { rows: [], truncated: false }
 ```
 
 This package re-exports `CommandFailed` and the runner and result types (`CommandRunner`,
@@ -289,42 +403,52 @@ experimental.
 
 ### Clients
 
-- `Gh`: the synchronous client, bound to one working directory.
+- `Gh`: the synchronous client, bound to one working directory, and optionally a repository and
+  host.
 - `AsyncGh`: the awaitable client, with the same methods.
-- `AsyncCallOptions`: `timeoutMs` and `signal`, accepted by eleven methods of `AsyncGh`.
+- `GhOptions` and `AsyncGhOptions`: the runner, `repo` and `hostname` a client is built with.
+- `AsyncCallOptions`: `timeoutMs` and `signal`, accepted by sixteen methods of `AsyncGh`.
 - `defaultRunnerFactory` and `RunnerFactory`: how a client makes its default runner for `gh`.
 
 Methods on both clients:
 
 - Escape hatches: `raw` runs any `gh` call and returns the result. `rawChecked` throws on a failed
-  exit. `at` returns the same client rooted at another directory.
-- Pull request queries: `prList`, `prView`, `openPrFor`, `prViewSettled`, `prBody` and
-  `prReviewThreads`.
+  exit. `at` returns the same client rooted at another directory, and `withRepo` the same client
+  aimed at another repository.
+- Pull request queries: `prList`, `prView`, `prFind`, `openPrFor`, `prViewSettled`, `prBody`,
+  `prReviewThreads` and `searchPrs`.
 - Pull request changes: `createPr`, `editPr`, `editPrBody`, `prComment`, `prUpdateBranch`,
   `prSetDraft`, `prMerge`, `prDiff` and `createReview`.
 - Issue and label queries: `issueList`, `issueView` and `labelList`.
+- Repository queries: `repoList` and `repoView`.
 - Issue and label changes: `setIssueLabel`, `createLabel`, `editLabel` and `issueCommentEdit`.
-- REST: `api` is a GET through `gh api` that never throws.
+- REST and GraphQL: `api` is a GET through `gh api` and `graphql` a query; neither throws.
 - Setup checks: `installed`, `authenticated`, `authStatus` and `ready`.
 - `ownerRepo` reads the owner and repository from a remote URL. It starts no process.
 
 ### Verbs
 
-A verb is plain data: argv, a `checked` flag, optional stdin and a `parse` function. Each client
-method has a verb of the same name, except the escape hatches, `at`, `prViewSettled`, `openPrFor`,
-`authenticated`, `ready` and `ownerRepo`. `openPrsForBranch` is a verb with no method.
+A verb is plain data: argv, a `checked` flag, a `readOnly` flag, optional stdin and environment,
+and a `parse` function. `readOnly` is true for every query and `prDiff`, and false for every
+mutation, so a caller that keeps an allowlist of safe calls can check a verb before running it.
+Each verb takes an optional `GhTarget` last. Each client method has a verb of the same name, except
+the escape hatches, `at`, `withRepo`, `prViewSettled`, `openPrFor`, `prFind`, `authenticated`,
+`ready` and `ownerRepo`. `openPrsForBranch` is a verb with no method.
 
-- `GhVerb`: the shape of a verb.
+- `GhVerb`: the shape of a verb. `GhTarget`: the `repo` and `hostname` a verb talks to.
 - Verb builders: `prList`, `prView`, `prBody`, `openPrsForBranch`, `prReviewThreads`, `prDiff`,
   `createPr`, `editPr`, `editPrBody`, `prComment`, `prUpdateBranch`, `prSetDraft`, `prMerge`,
   `createReview`, `issueList`, `issueView`, `labelList`, `setIssueLabel`, `createLabel`,
-  `editLabel`, `issueCommentEdit`, `api`, `installed` and `authStatus`.
-- `pickPrForBranch`: the row whose head branch is exactly the one you name. `gh` matches a head
-  filter as a prefix.
-- Field lists: `PR_REF_FIELDS` (enough to identify a PR), `PR_LIST_FIELDS` (for triage) and
-  `PR_VIEW_FIELDS` (the full set).
-- Option and result types: `PrListOptions`, `IssueListOptions`, `CreatePrOptions`,
-  `CreateReviewOptions`, `ReviewComment`, `CreateLabelOptions`, `ApiOptions`, `ApiResponse`,
+  `editLabel`, `issueCommentEdit`, `repoList`, `repoView`, `searchPrs`, `api`, `graphql`,
+  `installed` and `authStatus`.
+- `pickPrForBranch`: the first row whose head branch is exactly the one you name, for rows that
+  came from somewhere other than `prList({ head })`, such as a `head:` search.
+- `nodesAt`: one connection's nodes, joined across `graphql` pages.
+- Field lists: `PR_REF_FIELDS` (enough to identify a PR), `PR_LIST_FIELDS` (for triage),
+  `PR_VIEW_FIELDS` (the full set), `REPO_FIELDS` and `SEARCH_PR_FIELDS`.
+- Option and result types: `ListResult`, `PrListOptions`, `IssueListOptions`, `RepoListOptions`,
+  `SearchPrsOptions`, `CreatePrOptions`, `CreateReviewOptions`, `ReviewComment`,
+  `CreateLabelOptions`, `ApiOptions`, `ApiResponse`, `GraphqlOptions`, `GraphqlVariable`,
   `AuthStatus`, `PrMergeMethod` and `ReviewThread`.
 
 ### Parsers
@@ -334,14 +458,18 @@ method has a verb of the same name, except the escape hatches, `at`, `prViewSett
 - `normalizeAuthorLogin`: drops a `[bot]` suffix from a login.
 - `parseOwnerRepo`: reads a remote URL into `{ owner, repo }`, or `null`.
 - `ownerRepoSlug`: writes `{ owner, repo }` as `owner/repo`.
-- `parsePrUrl`: reads a pull request URL into its owner, repository and number, or `null`.
+- `parsePrUrl`: reads a pull request URL on any GitHub host into its host, owner, repository and
+  number, or `null`.
+- `parsePrRef`: reads what a person typed to name a pull request into a `PrRef`, or `null`.
 
 ### Types
 
-- Model: `PullRequest`, `Review`, `Comment`, `CheckRun`, `Actor`, `Label` and `IssueRow`.
-- Enums: `PullRequestState`, `MergeableState`, `MergeStateStatus`, `ReviewDecision`, `ReviewState`
-  and `CheckConclusion`.
-- `OwnerRepo` and `PullRequestRef`: a repository, and a pull request in one.
+- Model: `PullRequest`, `Review`, `Comment`, `CheckRun`, `Actor`, `Label`, `IssueRow`,
+  `Repository` and `PrSearchHit`.
+- Enums: `PullRequestState`, `MergeableState`, `MergeStateStatus`, `ReviewDecision`, `ReviewState`,
+  `CheckConclusion` and `RepositoryVisibility`.
+- `OwnerRepo`, `PullRequestRef` and `PrRef`: a repository, a pull request in one, and what a person
+  typed to name a pull request.
 
 ### From the command seam
 
@@ -364,6 +492,10 @@ The experimental items:
 - `createReview`, the verb and the method on both clients
 - `CreateReviewOptions`
 - `ReviewComment`
+- `graphql`, the verb and the method on both clients
+- `nodesAt`
+- `GraphqlOptions`
+- `GraphqlVariable`
 
 Every other export and method is stable, `prDiff` included.
 
@@ -376,8 +508,8 @@ shell, so nothing in it is specific to one shell.
 
 - **Closing a PR and deleting a branch.** `prMerge` merges and leaves the branch alone. Closing and
   deleting belong to a caller's own policy layer, where the audit trail lives.
-- **A full REST client.** `api()` is a GET; anything else goes through
-  `raw(["api", …])`.
+- **A full REST or GraphQL client.** `api()` is a GET and `graphql()` a query; anything else goes
+  through `raw(["api", …])`.
 - **Anything that reads a token.**
 
 ## Licence

package/async.ts

@@ -16,22 +16,24 @@ import {
   type CommandResult,
 } from '@osdlc/command-seam'
 
-import { parseOwnerRepo } from './repo.ts'
-import type { IssueRow, Label, OwnerRepo, PullRequest } from './types.ts'
+import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from './repo.ts'
+import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts'
 import * as v from './verbs.ts'
 import type {
   ApiOptions,
   ApiResponse,
   AuthStatus,
+  GhTarget,
   GhVerb,
   IssueListOptions,
+  ListResult,
   PrListOptions,
 } from './verbs.ts'
 
 /**
- * Per-call options for {@link AsyncGh}. Eleven methods accept them: `raw`, `rawChecked`,
- * `prList`, `prView`, `openPrFor`, `prViewSettled`, `prBody`, `api`, `labelList`,
- * `issueList` and `issueView`.
+ * Per-call options for {@link AsyncGh}. Sixteen methods accept them: `raw`, `rawChecked`,
+ * `prList`, `prView`, `prFind`, `openPrFor`, `prViewSettled`, `prBody`, `api`, `graphql`,
+ * `labelList`, `issueList`, `issueView`, `repoList`, `repoView` and `searchPrs`.
  */
 export interface AsyncCallOptions {
   /**
@@ -47,19 +49,39 @@ export interface AsyncCallOptions {
 /** How long to wait between merge-state retries, in milliseconds. */
 const MERGE_STATE_RETRY_DELAY_MS = 1_500
 
-/** A typed, awaitable gh client bound to one working directory. */
+/** What an {@link AsyncGh} is built with: the runner, and the repository and host it talks to. */
+export interface AsyncGhOptions extends GhTarget {
+  runner?: AsyncCommandRunner | undefined
+}
+
+/**
+ * A typed, awaitable gh client bound to one working directory, and optionally
+ * to one repository and host. `repo` and `hostname` work as on `Gh`.
+ */
 export class AsyncGh {
   readonly cwd: string
+  readonly repo: string | undefined
+  readonly hostname: string | undefined
+  private readonly target: GhTarget
   private readonly runner: AsyncCommandRunner
 
-  constructor(cwd: string, opts: { runner?: AsyncCommandRunner | undefined } = {}) {
+  constructor(cwd: string, opts: AsyncGhOptions = {}) {
+    v.checkTarget(opts)
     this.cwd = cwd
+    this.repo = opts.repo
+    this.hostname = opts.hostname
+    this.target = { repo: opts.repo, hostname: opts.hostname }
     this.runner = resolveRunnerAsync('gh', opts.runner)
   }
 
-  /** The same client rooted at a different directory (same runner). */
+  /** The same client rooted at a different directory (same runner, repo and host). */
   at(cwd: string): AsyncGh {
-    return new AsyncGh(cwd, { runner: this.runner })
+    return new AsyncGh(cwd, { runner: this.runner, repo: this.repo, hostname: this.hostname })
+  }
+
+  /** The same client aimed at another repository (same runner, directory and host). */
+  withRepo(repo: string): AsyncGh {
+    return new AsyncGh(this.cwd, { runner: this.runner, repo, hostname: this.hostname })
   }
 
   // ── escape hatches ────────────────────────────────────────────────────────
@@ -78,6 +100,7 @@ export class AsyncGh {
   private async exec<T>(verb: GhVerb<T>, call: AsyncCallOptions = {}): Promise<T> {
     const opts: AsyncCommandRunOptions = { cwd: this.cwd }
     if (verb.input !== undefined) opts.input = verb.input
+    if (verb.env !== undefined) opts.env = verb.env
     if (call.timeoutMs !== undefined) opts.timeoutMs = call.timeoutMs
     if (call.signal !== undefined) opts.signal = call.signal
     const result = verb.checked
@@ -89,16 +112,31 @@ export class AsyncGh {
   // ── queries ───────────────────────────────────────────────────────────────
 
   /** Pull requests matching `opts`, or null when gh failed. */
-  prList(opts: PrListOptions & AsyncCallOptions = {}): Promise<PullRequest[] | null> {
-    return this.exec(v.prList(opts), opts)
+  prList(opts: PrListOptions & AsyncCallOptions = {}): Promise<ListResult<PullRequest> | null> {
+    return this.exec(v.prList(opts, this.target), opts)
   }
 
-  /** One PR with the heavy fields, or null when gh failed. */
+  /** One PR by number, branch or URL, with the heavy fields, or null. See `Gh.prView`. */
   prView(
-    number: number,
+    ref: number | string,
     opts: { fields?: readonly string[] | undefined } & AsyncCallOptions = {},
   ): Promise<PullRequest | null> {
-    return this.exec(v.prView(number, opts.fields ?? v.PR_VIEW_FIELDS), opts)
+    return this.exec(v.prView(ref, opts.fields ?? v.PR_VIEW_FIELDS, this.target), opts)
+  }
+
+  /** The one PR that `input` names, or null. See `Gh.prFind`. */
+  async prFind(
+    input: string,
+    opts: { fields?: readonly string[] | undefined } & AsyncCallOptions = {},
+  ): Promise<PullRequest | null> {
+    const ref = parsePrRef(input)
+    if (ref === null) return null
+    const call = { ...opts, fields: opts.fields ?? v.PR_LIST_FIELDS }
+    if (ref.kind === 'url') return this.prView(ref.url, call)
+    if (ref.kind === 'branch') return prForBranchOn(this, ref.name, call)
+    const client = ref.repo === null ? this : this.withRepo(ownerRepoSlug(ref.repo))
+    const pr = await client.prView(ref.number, call)
+    return pr !== null || ref.orBranch === null ? pr : prForBranchOn(this, ref.orBranch, call)
   }
 
   /** The open PR whose head exactly equals `branch`, or null. See `Gh.openPrFor`. */
@@ -116,7 +154,7 @@ export class AsyncGh {
       timeoutMs: opts.timeoutMs,
       signal: opts.signal,
     })
-    return v.pickPrForBranch(rows, branch)
+    return v.pickPrForBranch(rows?.rows ?? null, branch)
   }
 
   /** {@link prView}, re-asked until GitHub settles the merge state. See `Gh.prViewSettled`. */
@@ -141,27 +179,66 @@ export class AsyncGh {
 
   /** A PR's body text, or null when gh failed. */
   prBody(number: number, opts: AsyncCallOptions = {}): Promise<string | null> {
-    return this.exec(v.prBody(number), opts)
+    return this.exec(v.prBody(number, this.target), opts)
   }
 
   /** A REST GET through `gh api`; failure is `ok: false`, never a rejection. */
   api(endpoint: string, opts: ApiOptions & AsyncCallOptions = {}): Promise<ApiResponse> {
-    return this.exec(v.api(endpoint, opts), opts)
+    return this.exec(v.api(endpoint, opts, this.target), opts)
+  }
+
+  /**
+   * A GraphQL query; each page's `data`, or null. See `Gh.graphql`.
+   *
+   * @experimental
+   */
+  graphql(
+    query: string,
+    variables: Record<string, v.GraphqlVariable> = {},
+    opts: v.GraphqlOptions & AsyncCallOptions = {},
+  ): Promise<unknown[] | null> {
+    return this.exec(v.graphql(query, variables, opts, this.target), opts)
   }
 
   /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
-  labelList(opts: { limit?: number | undefined } & AsyncCallOptions = {}): Promise<Label[] | null> {
-    return this.exec(v.labelList(opts), opts)
+  labelList(
+    opts: { limit?: number | undefined } & AsyncCallOptions = {},
+  ): Promise<ListResult<Label> | null> {
+    return this.exec(v.labelList(opts, this.target), opts)
   }
 
   /** Issues matching `opts`, or null when gh failed. */
-  issueList(opts: IssueListOptions & AsyncCallOptions = {}): Promise<IssueRow[] | null> {
-    return this.exec(v.issueList(opts), opts)
+  issueList(opts: IssueListOptions & AsyncCallOptions = {}): Promise<ListResult<IssueRow> | null> {
+    return this.exec(v.issueList(opts, this.target), opts)
   }
 
   /** One issue with its labels, or null when gh failed. */
   issueView(number: number, opts: AsyncCallOptions = {}): Promise<IssueRow | null> {
-    return this.exec(v.issueView(number), opts)
+    return this.exec(v.issueView(number, this.target), opts)
+  }
+
+  /** An owner's repositories, or null when gh failed. See `Gh.repoList`. */
+  repoList(
+    owner: string,
+    opts: v.RepoListOptions & AsyncCallOptions = {},
+  ): Promise<ListResult<Repository> | null> {
+    return this.exec(v.repoList(owner, opts, this.target), opts)
+  }
+
+  /** One repository, or null when gh failed. See `Gh.repoView`. */
+  repoView(
+    repo?: string | undefined,
+    opts: { fields?: readonly string[] | undefined } & AsyncCallOptions = {},
+  ): Promise<Repository | null> {
+    return this.exec(v.repoView(repo, opts.fields ?? v.REPO_FIELDS, this.target), opts)
+  }
+
+  /** Pull requests across repositories matching a search query, or null. See `Gh.searchPrs`. */
+  searchPrs(
+    query: string,
+    opts: v.SearchPrsOptions & AsyncCallOptions = {},
+  ): Promise<ListResult<PrSearchHit> | null> {
+    return this.exec(v.searchPrs(query, opts, this.target), opts)
   }
 
   /** True iff the `gh` binary is on PATH and runs. */
@@ -176,7 +253,7 @@ export class AsyncGh {
 
   /** Login state and what `gh auth status` printed. */
   authStatus(): Promise<AuthStatus> {
-    return this.exec(v.authStatus())
+    return this.exec(v.authStatus(this.target))
   }
 
   /** True iff `gh` is installed AND authenticated; short-circuits. */
@@ -196,7 +273,7 @@ export class AsyncGh {
 
   /** Open a PR and resolve to its URL ('' if gh printed none). */
   createPr(opts: v.CreatePrOptions): Promise<string> {
-    return this.exec(v.createPr(opts))
+    return this.exec(v.createPr(opts, this.target))
   }
 
   /** Retitle or rewrite a PR body. */
@@ -204,22 +281,22 @@ export class AsyncGh {
     number: number,
     opts: { title?: string | undefined; body?: string | undefined },
   ): Promise<void> {
-    return this.exec(v.editPr(number, opts))
+    return this.exec(v.editPr(number, opts, this.target))
   }
 
   /** Rewrite just a PR's body. */
   editPrBody(number: number, body: string): Promise<void> {
-    return this.exec(v.editPrBody(number, body))
+    return this.exec(v.editPrBody(number, body, this.target))
   }
 
   /** The PR's unified diff; rejects with `CommandFailed` when gh cannot produce it. */
   prDiff(number: number): Promise<string> {
-    return this.exec(v.prDiff(number))
+    return this.exec(v.prDiff(number, this.target))
   }
 
   /** Post one conversation comment on a PR; resolves to its URL ('' if gh printed none). */
   prComment(number: number, body: string): Promise<string> {
-    return this.exec(v.prComment(number, body))
+    return this.exec(v.prComment(number, body, this.target))
   }
 
   /**
@@ -228,17 +305,17 @@ export class AsyncGh {
    * @experimental
    */
   createReview(number: number, opts: v.CreateReviewOptions): Promise<string> {
-    return this.exec(v.createReview(number, opts))
+    return this.exec(v.createReview(number, opts, this.target))
   }
 
   /** Bring a PR's head branch up to date with its base. */
   prUpdateBranch(number: number, style: 'merge' | 'rebase' = 'merge'): Promise<void> {
-    return this.exec(v.prUpdateBranch(number, style))
+    return this.exec(v.prUpdateBranch(number, style, this.target))
   }
 
   /** Mark a PR ready for review (`draft: false`) or convert it to a draft (`draft: true`). */
   prSetDraft(number: number, draft: boolean): Promise<void> {
-    return this.exec(v.prSetDraft(number, draft))
+    return this.exec(v.prSetDraft(number, draft, this.target))
   }
 
   /**
@@ -248,22 +325,22 @@ export class AsyncGh {
    */
   async issueCommentEdit(commentId: string, body: string): Promise<void> {
     // async, so a bad id rejects the Promise instead of throwing at the call.
-    return this.exec(v.issueCommentEdit(commentId, body))
+    return this.exec(v.issueCommentEdit(commentId, body, this.target))
   }
 
   /** Merge a PR; GitHub refuses when its head is no longer `opts.headSha`. */
   prMerge(number: number, opts: { method: v.PrMergeMethod; headSha: string }): Promise<void> {
-    return this.exec(v.prMerge(number, opts))
+    return this.exec(v.prMerge(number, opts, this.target))
   }
 
   /** A PR's review threads, or null when they could not be read completely. */
   prReviewThreads(number: number): Promise<v.ReviewThread[] | null> {
-    return this.exec(v.prReviewThreads(number))
+    return this.exec(v.prReviewThreads(number, this.target))
   }
 
   /** Create a label (or force it to `opts`'s color/description if it exists). */
   createLabel(opts: v.CreateLabelOptions): Promise<void> {
-    return this.exec(v.createLabel(opts))
+    return this.exec(v.createLabel(opts, this.target))
   }
 
   /** Recolor and/or redescribe an existing label. */
@@ -271,15 +348,32 @@ export class AsyncGh {
     name: string,
     opts: { color?: string | undefined; description?: string | undefined },
   ): Promise<void> {
-    return this.exec(v.editLabel(name, opts))
+    return this.exec(v.editLabel(name, opts, this.target))
   }
 
   /** Swap an issue's label in a single `gh issue edit` call. */
   setIssueLabel(number: number, currentLabel: string | null, newLabel: string): Promise<void> {
-    return this.exec(v.setIssueLabel(number, currentLabel, newLabel))
+    return this.exec(v.setIssueLabel(number, currentLabel, newLabel, this.target))
   }
 }
 
+/** The open PR for `branch`, else its newest closed or merged one. */
+async function prForBranchOn(
+  gh: AsyncGh,
+  branch: string,
+  call: { fields: readonly string[] } & AsyncCallOptions,
+): Promise<PullRequest | null> {
+  const rows = await gh.prList({
+    head: branch,
+    state: 'all',
+    limit: 20,
+    fields: v.branchPrFields(call.fields),
+    timeoutMs: call.timeoutMs,
+    signal: call.signal,
+  })
+  return v.branchPr(rows)
+}
+
 function sleepAsync(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }