@osdlc/typed-gh 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,4 +1,64 @@
-# Changelog
+# @osdlc/typed-gh
+
+## 0.7.0
+
+### Minor Changes
+
+- d9b0f77: **Breaking:** the plain door throws the classified failure. A failed `gh` (a mutation, `prDiff`, `rawChecked`, a query) now throws a `FailureError` whose `failure` is the `GhFailure` and whose `failure.cause` is the `CommandFailed`, where it threw the `CommandFailed` itself. The bare `CommandFailed` only had command-seam's generic `exit` kind, so a signed-out `gh` during a write exited 1 from `runMain` instead of 23. Read `error.failure.argv` and `error.failure.cause.result` where you read `error.argv` and `error.result`.
+  
+  **Breaking:** the single-thing queries no longer treat every `Could not resolve to a …` as absence. `prView` answers `null` only for a missing pull request, `issueView` only for a missing issue and `repoView` only for a missing repository; a mistyped `--repo` is now a `not-found` failure, and a bare `HTTP 404` is a failure. The absence test reads stderr and stdout, as the classifier does.
+  
+  An `HTTP 403` is now `not-authenticated` (SAML, a missing scope), the same as Forgejo's 401 and 403, unless the text says it is a rate limit, which stays `rate-limited`. The `try` and `soft` doors recognise a thrown failure by shape, so two installed copies of `@osdlc/command-seam` or `@osdlc/result` agree.
+- d9b0f77: `Gh` and `AsyncGh` get `typed-git`'s three doors. **Breaking:** a query no longer answers `null` for a failure. The plain method returns its value or throws `CommandFailed` (a `FailureError` carrying a `GhFailure` of kind `unreadable` when `gh` exited 0 but its output could not be read). A query for one thing (`prView`, `issueView`, `repoView`, and `prFind`, `openPrFor`, `prViewSettled` over them) still answers `null` when GitHub says there is no such thing. `prList`, `prBody`, `graphql`, `labelList`, `issueList`, `repoList`, `searchPrs` and `prReviewThreads` now return a non-null value and throw. `installed`, `authenticated`, `authStatus`, `ready` and `api` are unchanged: their failure is part of their value.
+  
+  New: `gh.try.*` returns `Result<T, GhFailure>` from `@osdlc/result`; `gh.soft.*` returns `null` for a failed query, which is the old query behaviour, now opt-in (`TriedSync`, `TriedAsync`, `Soft`). `GhFailure` carries a `kind`, a one-line `message`, a `hint` for a person, `detail`, `argv`, `exitCode` and the `CommandFailed` as `cause`. `GhFailureKind` is every `@osdlc/command-seam` kind plus `not-authenticated`, `network`, `not-found`, `rate-limited` and `unreadable`, read from `gh`'s stderr. `classifyGhFailure(commandFailed)` is exported. `@osdlc/result` is now a dependency.
+
+### Patch Changes
+
+- fb712e0: Ship the compiled `dist/` only. The `bun` export condition and the TypeScript source are no longer in the package, so Bun, Node and every bundler load the same compiled ESM and `.d.ts` files. Bun still works through the compiled `dist/`.
+- fb712e0: Make every package follow the same conventions. The published manifests and READMEs change; the runtime code and the `dist/` files do not.
+  
+  - `author` is `sksizer` in every manifest (`@osdlc/typed-gh` had none).
+  - `engines.node` is no wider than any dependency's. `@osdlc/typed-gh` and `@osdlc/code-host` now declare `^22.22.2 || ^24.15.0 || >=26.0.0`, the range of `@osdlc/typed-git` and its dependency `hosted-git-info`. `@osdlc/cli-tool` and `@osdlc/trust-repo` declare `>=22`, not `>=22.18`: a `dist/` install needs no TypeScript stripping.
+  - `@osdlc/tsconfig` and `@osdlc/prettier-config` are ESM with `sideEffects: false`, and ship SECURITY.md and CONTRIBUTING.md. `@osdlc/prettier-config` has an `exports` map (`.` is `index.json`) in place of `main`.
+  - Every README has `## Install` and `## Licence` sections, and every CHANGELOG starts `# @osdlc/<name>`.
+  - `@osdlc/color` and `@osdlc/markdown-contract` no longer set a coverage threshold.
+  - `@osdlc/yaml-splice` reaches its WebAssembly glue through a `#wasm` entry in `imports`. The shipped `dist/` files are the same.
+- Updated dependencies [d9b0f77]
+- Updated dependencies [d9b0f77]
+- Updated dependencies [fb712e0]
+- Updated dependencies [fb712e0]
+- Updated dependencies [d9b0f77]
+- Updated dependencies [d9b0f77]
+- Updated dependencies [d9b0f77]
+- Updated dependencies [d9b0f77]
+  - @osdlc/command-seam@0.9.0
+  - @osdlc/typed-git@0.6.0
+  - @osdlc/result@0.1.0
+
+## 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
 

package/CONTRIBUTING.md

@@ -39,8 +39,9 @@ pnpm --filter @osdlc/typed-gh smoke
 
 ## Running the tests
 
-[Bun](https://bun.sh) is only the test runner. pnpm installs and
-runs the scripts, and the `test` script runs `bun test`. The tests run offline: a fake
+pnpm installs and runs the scripts, and the `test` script runs Vitest under
+Node. Build first, since the workspace packages resolve each other through
+`dist/`. The tests run offline: a fake
 runner stands in for `gh`, so they need no network, no login and no `gh`
 binary.
 
@@ -71,4 +72,4 @@ version and writes the CHANGELOG from the pending changesets. See
   call.
 - Add a changeset for a change users can see. See above.
 - Record a design choice in
-  [`docs/decisions/`](https://github.com/osdlc/osdlc/tree/main/packages/ts/typed-gh/docs/decisions).
+  [`docs/planning/decisions/`](https://github.com/osdlc/osdlc/tree/main/packages/ts/typed-gh/docs/planning/decisions).

package/README.md

@@ -15,7 +15,9 @@ scripts, release bots and coding agents. It is the GitHub-side companion of
 npm install @osdlc/typed-gh
 ```
 
-It needs Node 22 or later (or Bun), and the `gh` CLI on `PATH`, signed in with `gh auth login`.
+`pnpm add @osdlc/typed-gh` and `yarn add @osdlc/typed-gh` work too.
+
+It needs Node `^22.22.2 || ^24.15.0 || >=26.0.0`, the range of its dependency `@osdlc/typed-git` (Bun also works, through the compiled `dist/`), and the `gh` CLI on `PATH`, signed in with `gh auth login`.
 It is supported on macOS and Linux. Windows is not supported yet; it will be once a Windows CI job
 runs the tests.
 
@@ -25,7 +27,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 +38,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
 
@@ -88,17 +90,138 @@ and `ReviewDecision` (`APPROVED`, `CHANGES_REQUESTED`, `REVIEW_REQUIRED`,
 `null`). A value GitHub adds to either reads as `UNKNOWN` or `null`. A check
 that decides whether to merge can then match every member.
 
-## Three modes, so failure is never ambiguous
+## Three doors, as in `typed-git`, so failure is never ambiguous
+
+| | a value | on failure |
+| --- | --- | --- |
+| **`gh.query()`** (the plain method) | the value | throws a `FailureError` carrying the classified `GhFailure` (kind `unreadable` when `gh` succeeded but its output cannot be read) |
+| **`gh.try.query()`** | `{ ok: true, value }` | `{ ok: false, error: GhFailure }` |
+| **`gh.soft.query()`** | the value | `null` (queries only; a mutation has no soft form) |
+| **`raw(argv)`** | the raw `CommandResult`; you decide | the same |
+
+A query returns a list or a value, never an empty list on failure.
+`prList()` returning `{ rows: [], truncated: false }` means *this repository
+has no open PRs*. A failed call throws, or is `{ ok: false }` through `try`, or
+`null` through `soft`: *we could not ask*. If the two were the same, an
+expired credential would read as "nothing to do".
+
+**Absence is an answer.** A query for one thing (`prView`, `issueView`,
+`repoView`, and `prFind` and `openPrFor` over them) returns `null` on every
+door when GitHub says there is no such thing: "Could not resolve to a
+PullRequest" or "no pull requests found for branch" for `prView`, "Could not
+resolve to an Issue" for `issueView`, "Could not resolve to a Repository" for
+`repoView`. `gh.try.prView(99)` is `{ ok: true, value: null }`. Every other
+failure is a failure, including a wrong repository: `prView(7)` against a
+mistyped `--repo` is a `not-found` failure, not an absent PR. The check reads
+stderr and stdout, as the classifier does.
+
+**Probes answer.** `installed()`, `authenticated()`, `authStatus()`, `ready()`
+and `api()` return their failure as part of their value, in every door, because
+"gh is not installed" is the answer to the question they ask.
+
+```ts
+import { describe } from '@osdlc/result'
+
+const result = gh.try.prList({ limit: 50 })
+if (!result.ok) {
+  console.error(describe(result.error)) // e.g. "gh is not signed in to GitHub. Run `gh auth login`."
+}
+```
+
+### `GhFailure`
+
+The error of `try` is a `GhFailure`, a `Failure` from `@osdlc/result`: a `kind`
+to branch on, a one-line `message` and a `hint` for a person (`describe(error)`
+joins them), `gh`'s own output in `detail`, the `argv` and `exitCode`, and the
+`CommandFailed` it was read from in `cause`. The plain door throws the same
+failure, wrapped in a `FailureError` (`error.failure`), so a CLI that reports a
+thrown failure, such as `runMain` from `@osdlc/cli-tool`, shows "gh is not
+signed in" for a write and exits with the same code as for a read.
+
+| `kind` | When (gh's stderr) | `message` / `hint` |
+| --- | --- | --- |
+| `not-installed` | `gh` is not on `PATH` | `` `gh` is not installed or not on PATH. `` / ``Install it from https://cli.github.com, then run `gh auth login`.`` |
+| `not-authenticated` | `gh auth login`, `HTTP 401`, `HTTP 403` (unless a rate limit), `Bad credentials`, `not logged in` | `gh is not signed in to GitHub.` / ``Run `gh auth login`.`` |
+| `network` | `error connecting to`, `Could not resolve host`, `no such host`, `dial tcp`, `i/o timeout` | `GitHub could not be reached.` / `Check your network connection.` |
+| `not-found` | `Could not resolve to a …`, `HTTP 404`, `no pull requests found for branch` | `GitHub has no such pull request, issue or repository, or you cannot see it.` / `Check the number or name, and that your account can see the repository.` |
+| `rate-limited` | `API rate limit exceeded`, `secondary rate limit`, `HTTP 429` | `GitHub's API rate limit was reached.` / `Wait a few minutes and try again.` |
+| `unreadable` | `gh` exited 0 but its output could not be read completely | `gh answered, but its output could not be read completely.` (no hint, no `cause`) |
+| `not-executable`, `bad-cwd`, `timeout`, `output-cap`, `signal`, `aborted`, `spawn` | as in `@osdlc/command-seam` | command-seam's message, no hint |
+| `exit` | any other non-zero exit | `gh`'s first stderr line |
+
+The patterns are `gh`'s English messages; anything else is a plain `exit`,
+never a wrong kind. Rate limiting is checked before authentication, then
+network, then not-found. `classifyGhFailure(commandFailed)` makes the same
+classification for a `CommandFailed` you caught yourself.
+
+## 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> = 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
 
-| | on failure |
-| --- | --- |
-| **queries** | return the absence value, `null`. Never throw. |
-| **mutations** | throw `CommandFailed`, carrying argv and the full result. |
-| **`raw(argv)`** | hand back the raw `CommandResult`; you decide. |
+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 failure's `argv` 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')
+```
 
-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".
+`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
 
@@ -143,7 +266,7 @@ about staleness, never the measure of it. Compute that from the commit graph
 
 ## Changing pull requests
 
-Mutations throw `CommandFailed` when `gh` fails.
+Mutations throw the classified failure (a `FailureError`) when `gh` fails. `gh.try.editPr(…)` returns the failure as a `Result` instead; a mutation has no `soft` form.
 
 ```ts
 const url = gh.createPr(options)
@@ -171,23 +294,23 @@ gh.prMerge(9, { method, headSha: 'abc1234' })
 ```
 
 `prReviewThreads(n)` reads the review threads, so you can look for open ones before you merge. It
-returns `null` when it could not read all of them (a failed call, an unexpected payload, or more
-than 100 threads). That is not the same as "no threads".
+throws when it could not read all of them (a failed call, an unexpected payload, or more
+than 100 threads; `soft.prReviewThreads` is `null`). That is not the same as "no threads".
 
 ```ts
-const threads: ReviewThread[] | null = gh.prReviewThreads(9)
+const threads: ReviewThread[] = gh.prReviewThreads(9)
 
-threads?.filter((t) => !t.isResolved)
+threads.filter((t) => !t.isResolved)
 ```
 
 ## Issues and labels
 
 ```ts
-const issue: IssueRow | null = gh.issueView(7)
-const triage: IssueRow[] | null = gh.issueList({ label: 'status:triage', limit: 50 })
+const issue: IssueRow | null = gh.issueView(7) // null: there is no issue 7
+const triage: ListResult<IssueRow> = 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> = gh.labelList({ limit: 100 })
 gh.createLabel({ name: 'status:triage', color: '1f6feb', description: 'Triage stage' })
 gh.editLabel('status:triage', { description: 'Waiting for triage' })
 ```
@@ -209,7 +332,7 @@ const review = gh.createReview(9, {
 gh.issueCommentEdit('4204154439', 'Updated: CI is green.')
 ```
 
-`prDiff` returns the unified diff and throws `CommandFailed` when `gh` cannot produce it.
+`prDiff` returns the unified diff and throws the classified failure when `gh` cannot produce it.
 
 `createReview` is experimental. It posts a review of kind `COMMENT`: it cannot approve or request
 changes. Each inline comment sits on one line of the new side of the diff. It returns the review's
@@ -237,9 +360,9 @@ const prs = verb.parse(result)
 ## `AsyncGh`
 
 The awaitable form of `Gh`, with the same methods, for a fan-out that must not block the event loop.
-Same tri-modal contract (queries resolve to a value or `null` and never
-reject, mutations reject with `CommandFailed`, `raw`/`rawChecked` are the
-hatches), driven by the same verb table, so the two cannot drift. It takes an
+Same three doors, promised (the plain method rejects with the classified failure,
+`try` resolves to a `Result<T, GhFailure>`, `soft` resolves `null` for a failed
+query, `raw`/`rawChecked` are the hatches), driven by the same verb table, so the two cannot drift. It takes an
 `AsyncCommandRunner` and defaults to `spawnRunnerAsync("gh")`.
 
 ```ts
@@ -247,14 +370,15 @@ import { AsyncGh } from '@osdlc/typed-gh'
 
 const gh = new AsyncGh('/repo')
 const prs = await Promise.all(branches.map((b) => gh.openPrFor(b)))
-const body = await gh.prBody(42) // string | null
+const body = await gh.prBody(42) // string; rejects when gh fails
 await gh.editPrBody(42, `${body}\n\nfooter`)
 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 +387,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 throws when the
+call failed or any page has `errors` or no `data` (`soft.graphql` is `null`): 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> = gh.repoList('acme', { archived: false, limit: 200 })
+const repo: Repository | null = gh.repoView('acme/widgets') // null: no such repository
+const hits: ListResult<PrSearchHit> = 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 +441,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 +456,58 @@ 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 never throws (failure is `ok: false`); `graphql` is a query and throws on a failed or partial answer.
 - Setup checks: `installed`, `authenticated`, `authStatus` and `ready`.
 - `ownerRepo` reads the owner and repository from a remote URL. It starts no process.
+- `try` and `soft`: the whole surface again as a `Result<T, GhFailure>`, and the queries again with `null` for a failure. `TriedSync`, `TriedAsync` and `Soft` are their types.
+
+### Failures
+
+- `GhFailure` and `GhFailureKind`: the error of `try`, and its kinds (see "`GhFailure`" above).
+- `classifyGhFailure(commandFailed)`: the `GhFailure` for a `CommandFailed`.
 
 ### 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,18 +517,22 @@ 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
 
-- `CommandFailed`: thrown by a mutation. It carries the argv and the result.
+- `CommandFailed`: re-exported from `@osdlc/command-seam`. A failed call throws a `FailureError` whose `failure.cause` is the `CommandFailed`, which carries the argv and the result.
 - `CommandRunner`, `AsyncCommandRunner`, `CommandResult` and `CommandRunOptions`: the runner types
   that appear in signatures.
 
@@ -364,6 +551,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,10 +567,10 @@ 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
 
-`MIT OR Apache-2.0`, at your option. See `LICENSE-MIT` and `LICENSE-APACHE`.
+`MIT OR Apache-2.0`, at your option. See [LICENSE-MIT](./LICENSE-MIT) and [LICENSE-APACHE](./LICENSE-APACHE).