@osdlc/typed-gh 0.7.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @osdlc/typed-gh
 
+## 0.9.1
+
+### Patch Changes
+
+- 96385dc: An empty `hostname` now means no host, the same as leaving it out. It used to throw `RangeError`, so a caller that reads the host from its own config had to write `hostname: value || undefined`. Passing `hostname: 'github.com'` is unchanged: it still reaches gh as given, because naming github.com explicitly keeps a call there when `GH_HOST` or gh's default host points at another host. The README now says so.
+
+## 0.9.0
+
+### Minor Changes
+
+- cc2abe4: `api` now keeps GitHub's error body when a request fails. `body` is parsed even when gh exits with an error, and a new `message` field holds `body.message`. `ApiResponse` gains this `message` field as required. `malformed` is now also set when a failed call prints something that is not JSON. The docs now say that `status` is only filled in when headers were requested.
+
+### Patch Changes
+
+- 72f5049: `prList` always requests the `number` field. Before, a `fields` list without `number` returned no rows.
+- Updated dependencies [b5aac07]
+- Updated dependencies [41ef520]
+  - @osdlc/typed-git@0.7.0
+
+## 0.8.0
+
+### Minor Changes
+
+- ae400e5: Added `runVerb` and `runVerbAsync`, with `RunVerbOptions` and `RunVerbAsyncOptions`. They run one verb through a runner the caller owns and apply what the verb carries: `env` (the target host, as `GH_HOST`, for `repoList` and `searchPrs`), `input` (the payload `createReview` sends on stdin), `timeoutMs` and the checked contract. Running `verb.parse(await run(verb.argv))` yourself dropped `env` and `input` without an error. `Gh` and `AsyncGh` now call them, so there is one copy of that logic.
+
 ## 0.7.0
 
 ### Minor Changes

package/CONTRIBUTING.md

@@ -68,7 +68,7 @@ version and writes the CHANGELOG from the pending changesets. See
   the package by name. A test fails if an exported function is not called, or
   an exported type not imported, in `examples/`. `tests/exports.test.ts` lists
   the few exports that have no example yet.
-- Shell out only through the command seam, never with a raw `child_process`
+- Run commands only through `@osdlc/command-seam`, never with a raw `child_process`
   call.
 - Add a changeset for a change users can see. See above.
 - Record a design choice in

package/README.md

@@ -17,8 +17,8 @@ npm install @osdlc/typed-gh
 
 `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
+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/`. It also needs 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.
 
 ```ts
@@ -34,11 +34,11 @@ The `examples` folder in the repository runs the same calls as tests.
 
 ## When not to use it
 
-- **`gh` is not installed.** In a browser or a serverless function, use an HTTP client such as
+- `gh` is not installed. In a browser or a serverless function, use an HTTP client such as
   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
+- 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
   and `graphql()` is a query. Anything else goes through `raw`.
 
 ## How it compares
@@ -60,15 +60,14 @@ and `@osdlc/typed-git`.
 
 ## Authentication is `gh`'s
 
-No token is read, stored, or forwarded. That is the reason this shells out to
-the CLI rather than speaking REST: the credential already exists in the user's
-keychain, and a library that reaches for `GITHUB_TOKEN` is a library that can
-leak one.
+No token is read, stored, or forwarded. That is why this package runs the CLI
+instead of calling the REST API. The credential is already in the user's
+keychain. A library that reads `GITHUB_TOKEN` can leak it.
 
 ## A total model
 
-`gh --json` returns only the fields you asked for, so every field on
-`PullRequest` has a "not known" value and none of them is `undefined`:
+`gh --json` returns only the fields you asked for. So every field on
+`PullRequest` has a "not known" value, and none of them is `undefined`:
 
 ```ts
 const pr = parsePullRequest({ number: 7 })
@@ -90,34 +89,35 @@ 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 doors, as in `typed-git`, so failure is never ambiguous
+## Three ways to call, as in `typed-git`, so a failure is never mistaken for an answer
 
 | | 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 |
+| `gh.query()` (the method that throws) | 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
+`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`. That means 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
+A missing item is an answer, not a failure. A query for one thing (`prView`, `issueView`,
+`repoView`, and `prFind` and `openPrFor`, which use them) returns `null` in all
+three call styles 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
+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.
+Setup checks return their failure as a value. `installed()`, `authenticated()`,
+`authStatus()`, `ready()` and `api()` return their failure as part of their
+value, in all three call styles. For them, "gh is not installed" is the answer
+to the question they ask.
 
 ```ts
 import { describe } from '@osdlc/result'
@@ -130,11 +130,11 @@ if (!result.ok) {
 
 ### `GhFailure`
 
-The error of `try` is a `GhFailure`, a `Failure` from `@osdlc/result`: a `kind`
+The error of `try` is a `GhFailure`, a `Failure` from `@osdlc/result`. It has 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
+`CommandFailed` it was read from in `cause`. The methods that throw throw 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.
 
@@ -149,7 +149,7 @@ signed in" for a write and exits with the same code as for a read.
 | `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`,
+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.
@@ -157,7 +157,7 @@ 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`
+one row more than `limit` and returns `{ rows, truncated }`. That is at most `limit`
 rows, and `truncated: true` when there were more.
 
 ```ts
@@ -172,8 +172,8 @@ 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:
+Name a repository, a host, or both, and every call targets them instead. No
+clone is needed:
 
 ```ts
 const acme = new Gh(process.cwd(), { repo: 'acme/widgets', hostname: 'github.acme.com' })
@@ -184,15 +184,18 @@ 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`
+call hit. `pr`, `issue` and `label` calls get `--repo github.acme.com/acme/widgets`.
+`api` calls get `--hostname` and a filled `{owner}/{repo}`. `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
+or a `<tenant>.ghe.com` host. An empty string means no host, so a value read
+from config can be passed as it is. `github.com` is not dropped: it goes to gh
+as `--repo github.com/owner/name`, `--hostname` or `GH_HOST`, which keeps the
+call on github.com even when the environment sets another default host. gh
+supports only GitHub's API, so Forgejo, Gitea and GitLab are not supported. A `repo` that is not `owner/name`, or a
 `hostname` that is not a bare host, throws `RangeError`.
 
 ## Finding a pull request
@@ -212,7 +215,7 @@ gh.prView('https://github.acme.com/acme/widgets/pull/42')
 const pr: PullRequest | null = gh.prFind(process.argv[2] ?? '')
 ```
 
-It reads the text with `parsePrRef`, which starts no process: `42` and `#42`
+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
@@ -220,19 +223,19 @@ 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
+`task/foo-2`. Two forks can share a branch name. Ask for
 `headRepositoryOwner` to tell them apart.
 
-## Two shape hazards it absorbs
+## Two payload differences it handles
 
-**Author logins differ by transport.** GraphQL (`gh pr view --json`) returns a
-login without a suffix (`github-actions`). REST (`gh api`) returns the suffixed
-one (`github-actions[bot]`). Comparing one with the other never matches, and
-no error shows it. That is how bot noise gets treated as human review
-feedback. Logins are cut to the suffix-less form once, when a payload is
-parsed.
+Author logins differ between GraphQL and REST. GraphQL (`gh pr view --json`)
+returns a login without a suffix (`github-actions`). REST (`gh api`) returns
+the suffixed one (`github-actions[bot]`). Comparing one with the other never
+matches, and no error shows it. Then a bot's comments are treated as human
+review feedback. Logins are cut to the form without the suffix once, when a
+payload is parsed.
 
-**`statusCheckRollup` holds two node types.** A modern `CheckRun` carries
+`statusCheckRollup` holds two node types. A modern `CheckRun` carries
 `name`/`status`/`conclusion`. A legacy `StatusContext` carries
 `context`/`state`. Both map onto one `verdict` axis:
 
@@ -248,21 +251,20 @@ as green, a red build could merge.
 
 ## The merge state is not stable on a cold query
 
-GitHub computes mergeability lazily: the first query kicks it off and answers
-`UNKNOWN` until it lands. A caller that believes that first answer mis-triages
-every PR that is merely slow.
+GitHub computes mergeability only when asked. The first query starts the
+computation and answers `UNKNOWN` until it finishes. A caller that trusts that
+first answer misjudges every PR whose computation is slow.
 
 ```ts
 const pr = gh.prViewSettled(7, { attempts: 3 }) // 3 is the default
 ```
 
-`UNKNOWN` is still a legitimate final verdict, so callers must handle it.
+`UNKNOWN` can still be the final answer, so callers must handle it.
 
-Note also that `mergeStateStatus: "BEHIND"` only ever appears when branch
-protection *requires* an up-to-date branch. Without that rule a branch a
-hundred commits behind still reports `CLEAN` — so it is a corroborating hint
-about staleness, never the measure of it. Compute that from the commit graph
-(`typed-git`'s `aheadBehind`).
+`mergeStateStatus: "BEHIND"` appears only when branch protection requires an
+up-to-date branch. Without that rule, a branch a hundred commits behind still
+reports `CLEAN`. So `BEHIND` is a hint that a branch is out of date, not a
+measure of it. Compute that from the commit graph (`typed-git`'s `aheadBehind`).
 
 ## Changing pull requests
 
@@ -283,9 +285,9 @@ a draft.
 
 ## Merging
 
-`prMerge` takes the head commit you judged. GitHub refuses the merge if the head has moved since,
-so a push that lands between your check and the merge cannot ride in unreviewed. The branch is not
-deleted. That is yours to do.
+`prMerge` takes the head commit you checked. GitHub refuses the merge if the head has moved since.
+So a push that lands between your check and the merge cannot be merged without review. The branch
+is not deleted. That is up to you.
 
 ```ts
 const method: PrMergeMethod = 'squash'
@@ -316,8 +318,8 @@ gh.editLabel('status:triage', { description: 'Waiting for triage' })
 ```
 
 `issueList` returns open issues, up to `limit` (default 200). `labelList` returns up to `limit`
-labels (default 1000; `gh`'s own default is 30). `setIssueLabel` removes one label and adds
-another in one `gh issue edit` call. `createLabel` passes `--force`, so it is safe to repeat: an
+labels (default 1000. `gh`'s own default is 30). `setIssueLabel` removes one label and adds
+another in one `gh issue edit` call. `createLabel` passes `--force`, so it is safe to repeat. An
 existing label gets the color and description you pass.
 
 ## Diffs, reviews and comments
@@ -334,20 +336,20 @@ gh.issueCommentEdit('4204154439', 'Updated: CI is green.')
 
 `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
+`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
 URL.
 
-`issueCommentEdit` is experimental. It takes the comment's numeric REST id, as text: the `id` from
+`issueCommentEdit` is experimental. It takes the comment's numeric REST id, as text. That is the `id` from
 `gh api repos/{owner}/{repo}/issues/<n>/comments`. The `Comment.id` that `prView` returns is a
 GraphQL node id, which this REST path does not accept. An id that is not all digits throws
 `RangeError` before `gh` runs (`AsyncGh` returns a rejected Promise).
 
-## Pure halves, for an async fan-out
+## Verbs and parsers, for running calls yourself
 
-The verb table and every parser are side-effect free, so concurrent callers
-drive them through their own `AsyncCommandRunner` without duplicating a line
-of parsing:
+The verb table and every parser have no side effects. So code that runs many
+calls at once can run them through its own `AsyncCommandRunner` and reuse the
+parsing:
 
 ```ts
 import { prList } from '@osdlc/typed-gh'
@@ -357,13 +359,32 @@ const result = await runner.run(verb.argv, { cwd: '/repo', timeoutMs: 5_000 })
 const prs = verb.parse(result)
 ```
 
+That is only safe for a verb with no `env` or `input`. `repoList` and `searchPrs` send the target
+host as `GH_HOST` (`env`), and `createReview` sends its payload on stdin (`input`). A runner call
+that passes only `verb.argv` drops both, with no error. The query goes to github.com, and the review
+is never sent. `runVerb` (and `runVerbAsync`, for an `AsyncCommandRunner`) run a verb the way `Gh` and
+`AsyncGh` do, with `cwd`, `env`, `input`, `timeoutMs` and the checked contract applied, and return
+the parsed value or throw the classified failure:
+
+```ts
+import { repoList, runVerbAsync } from '@osdlc/typed-gh'
+
+const repos = await runVerbAsync(repoList('acme', {}, { hostname: 'ghe.example.com' }), runner, {
+  cwd: '/repo',
+  timeoutMs: 5_000,
+})
+```
+
+They take a `CommandRunner`. A plain `(binary, argv, opts) => result` function is wrapped as
+`{ run: (argv, opts) => fn('gh', argv, opts) }`.
+
 ## `AsyncGh`
 
-The awaitable form of `Gh`, with the same methods, for a fan-out that must not block the event loop.
-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")`.
+The awaitable form of `Gh`, with the same methods, for code that runs many calls at once and must
+not block the event loop. It has the same three call styles, as Promises. The plain method rejects
+with the classified failure. `try` resolves to a `Result<T, GhFailure>`. `soft` resolves `null` for
+a failed query. `raw` and `rawChecked` run any `gh` call. Both clients use the same verb table, so
+they cannot drift apart. It takes an `AsyncCommandRunner` and defaults to `spawnRunnerAsync("gh")`.
 
 ```ts
 import { AsyncGh } from '@osdlc/typed-gh'
@@ -382,11 +403,12 @@ These methods take `AsyncCallOptions`: `raw`, `rawChecked`, `prList`, `prView`,
 `signal`.
 
 `api(endpoint, opts)` (on `Gh` and `AsyncGh`) is a REST GET through `gh api`.
-It never throws; the result is `{ ok, status, etag, body, malformed, stderr, error? }`.
-`stderr` is gh's own; `error` holds the runner's message when gh never ran or
+It never throws. The result is `{ ok, status, etag, body, message, malformed, stderr, error? }`.
+On failure `body` still carries GitHub's error object and `message` its text. `status` is read only when headers were requested (`etag` or `includeHeaders`).
+`stderr` is gh's own. `error` holds the runner's message when gh never ran or
 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
+Pass `etag` for a conditional request (`If-None-Match`. A 304 comes back as
+`status: 304, body: null`). Or pass `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 come from the client's repo, or are filled in by gh from the clone.
 
@@ -400,7 +422,7 @@ const branches = gh.api('repos/{owner}/{repo}/branches', { paginate: true }).bod
 ```
 
 `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
+call failed or any page has `errors` or no `data` (`soft.graphql` is `null`). A partial answer counts as a failure. `nodesAt` joins
 one connection's `nodes` across the pages, and is `null` when any page lacks them.
 
 ```ts
@@ -416,8 +438,8 @@ const pages = gh.graphql(query, { owner: '{owner}', name: '{repo}' }, { paginate
 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`.
+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
 
@@ -428,15 +450,15 @@ 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
+`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
+## Passing your own runner
 
 `Gh` takes a `CommandRunner` from
-[`@osdlc/command-seam`](https://github.com/osdlc/osdlc/tree/main/packages/ts/command-seam), so a
-suite runs offline:
+[`@osdlc/command-seam`](https://github.com/osdlc/osdlc/tree/main/packages/ts/command-seam), so
+tests can run offline:
 
 ```ts
 const empty: CommandRunner = { run: () => ({ exitCode: 0, stdout: '[]', stderr: '' }) }
@@ -462,10 +484,12 @@ experimental.
 - `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`.
+- `runVerb` and `runVerbAsync`, with `RunVerbOptions` and `RunVerbAsyncOptions`: run one verb through
+  a runner you own, with its `env`, `input`, timeout and checked contract applied.
 
 Methods on both clients:
 
-- Escape hatches: `raw` runs any `gh` call and returns the result. `rawChecked` throws on a failed
+- Direct calls: `raw` runs any `gh` call and returns the result. `rawChecked` throws on a failed
   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`,
@@ -491,7 +515,7 @@ A verb is plain data: argv, a `checked` flag, a `readOnly` flag, optional stdin
 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`,
+`raw`, `rawChecked`, `at`, `withRepo`, `prViewSettled`, `openPrFor`, `prFind`, `authenticated`,
 `ready` and `ownerRepo`. `openPrsForBranch` is a verb with no method.
 
 - `GhVerb`: the shape of a verb. `GhTarget`: the `repo` and `hostname` a verb talks to.
@@ -540,9 +564,9 @@ the escape hatches, `at`, `withRepo`, `prViewSettled`, `openPrFor`, `prFind`, `a
 
 The package is at 0.x. Each item is stable or experimental.
 
-- **Stable** items change only with a minor release, and a breaking change is marked
+- Stable items change only with a minor release, and a breaking change is marked
   **Breaking** in the CHANGELOG.
-- **Experimental** items may change or go in any release. Each has an `@experimental` tag in its
+- Experimental items may change or go in any release. Each has an `@experimental` tag in its
   TSDoc.
 
 The experimental items:
@@ -565,11 +589,11 @@ shell, so nothing in it is specific to one shell.
 
 ## What is not here
 
-- **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 or GraphQL client.** `api()` is a GET and `graphql()` a query; anything else goes
+- Closing a PR and deleting a branch. `prMerge` merges and leaves the branch alone. Closing and
+  deleting belong in the caller's own code, which keeps its own record of what it did.
+- 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.**
+- Anything that reads a token.
 
 ## Licence
 

package/SECURITY.md

@@ -33,8 +33,8 @@ not intend are in scope.
   keychain entry, or `GH_TOKEN` and `GITHUB_TOKEN` in the environment. The
   child process inherits the caller's environment.
 - **No shell is involved.** The package starts `gh` directly and passes each
-  value as one argument, so spaces and shell metacharacters in a title or a
-  body are inert.
+  value as one argument. Spaces and shell metacharacters in a title or a
+  body have no effect.
 - **`gh` still parses its arguments.** A positional value that starts with `-`,
   such as a label name, can be read as a flag. Check untrusted input before you
   pass it.
@@ -51,5 +51,5 @@ not intend are in scope.
   and PR titles, bodies and comments travel in argv. Do not log the message
   where those are private. `createReview` sends its payload on stdin instead.
 - **`prMerge` needs the head sha.** GitHub refuses the merge when the PR head
-  is no longer that sha, so a push made after review cannot ride in. Pass the
-  sha you judged, not one read just before the call.
+  is no longer that sha, so a push made after review is not merged by this
+  call. Pass the sha you reviewed, not one read just before the call.

package/dist/async.d.ts

@@ -1,13 +1,14 @@
 /**
- * `AsyncGh` — the awaitable GitHub client, with the same methods as {@link Gh}.
+ * `AsyncGh`: the awaitable GitHub client, with the same methods as {@link Gh}.
  *
- * Same three doors, promised: the plain method resolves to a value or rejects
- * (a `FailureError` carrying the classified `GhFailure` for a failed gh or output it cannot read;
- * a query for one thing resolves `null` when GitHub has no such thing),
- * `try` resolves to a `Result<T, GhFailure>`, `soft` resolves `null` for a
- * failure, and `raw`/`rawChecked` are the hatches. It is driven by the same pure verb
- * table as `Gh`, so the two cannot drift on argv or parsing. Use it where the
- * sync client would block the event loop: a fan-out of per-PR queries.
+ * It has the same three call styles, as Promises. The plain method resolves to
+ * a value or rejects with a `FailureError` carrying the classified `GhFailure`,
+ * for a failed gh or output it cannot read. A query for one thing resolves
+ * `null` when GitHub has no such thing. `try` resolves to a
+ * `Result<T, GhFailure>`. `soft` resolves `null` for a failure. `raw` and
+ * `rawChecked` run any `gh` call. It uses the same verb table as `Gh`, so the
+ * two cannot differ on argv or parsing. Use it where the sync client would
+ * block the event loop, such as many per-PR queries at once.
  */
 import { type AsyncCommandRunner, type CommandResult } from '@osdlc/command-seam';
 import { type Soft, type TriedAsync } from './doors.ts';
@@ -26,7 +27,7 @@ export interface AsyncCallOptions {
      * non-number.
      */
     timeoutMs?: number | undefined;
-    /** Aborts the call; the runner stops the child. */
+    /** Aborts the call. The runner stops the child process. */
     signal?: AbortSignal | undefined;
 }
 /** What an {@link AsyncGh} is built with: the runner, and the repository and host it talks to. */
@@ -58,15 +59,15 @@ export declare class AsyncGh {
     get try(): TriedAsync<AsyncGh>;
     /** Each query again, resolving `null` instead of rejecting when `gh` fails. See `Gh.soft`. */
     get soft(): Soft<AsyncGh>;
-    /** Unchecked passthrough for verbs not yet lifted into the API. */
+    /** Run any `gh` call and return the result, whatever the exit code. */
     raw(argv: string[], opts?: AsyncCallOptions): Promise<CommandResult>;
-    /** Checked passthrough — rejects with the classified failure on a non-zero exit. */
+    /** Run any `gh` call. Rejects with the classified failure on a non-zero exit. */
     rawChecked(argv: string[], opts?: AsyncCallOptions): Promise<CommandResult>;
-    /** Run one verb from the table, honouring its checked/unchecked contract. */
+    /** Run one verb from the table, checked or unchecked as the verb says. */
     private exec;
-    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run rejects. */
+    /** {@link exec} for a verb that never returns `null` as a value. A failed or unreadable run rejects. */
     private read;
-    /** Pull requests matching `opts`. Rejects when gh fails; `soft.prList` resolves null instead. */
+    /** Pull requests matching `opts`. Rejects when gh fails. `soft.prList` resolves null instead. */
     prList(opts?: PrListOptions & AsyncCallOptions): Promise<ListResult<PullRequest>>;
     /** One PR by number, branch or URL, with the heavy fields, or null. See `Gh.prView`. */
     prView(ref: number | string, opts?: {
@@ -81,7 +82,7 @@ export declare class AsyncGh {
         limit?: number | undefined;
         fields?: readonly string[] | undefined;
     } & AsyncCallOptions): Promise<PullRequest | null>;
-    /** {@link prView}, re-asked until GitHub settles the merge state. See `Gh.prViewSettled`. */
+    /** {@link prView}, asked again until GitHub has computed the merge state. See `Gh.prViewSettled`. */
     prViewSettled(number: number, opts?: {
         attempts?: number | undefined;
         fields?: readonly string[] | undefined;
@@ -89,10 +90,10 @@ export declare class AsyncGh {
     } & AsyncCallOptions): Promise<PullRequest | null>;
     /** A PR's body text. Rejects when gh fails. */
     prBody(number: number, opts?: AsyncCallOptions): Promise<string>;
-    /** A REST GET through `gh api`; failure is `ok: false`, never a rejection. */
+    /** A REST GET through `gh api`. Failure is `ok: false`, never a rejection. */
     api(endpoint: string, opts?: ApiOptions & AsyncCallOptions): Promise<ApiResponse>;
     /**
-     * A GraphQL query; each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
+     * A GraphQL query. Resolves to each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
      *
      * @experimental
      */
@@ -103,11 +104,11 @@ export declare class AsyncGh {
     } & AsyncCallOptions): Promise<ListResult<Label>>;
     /** Issues matching `opts`. Rejects when gh fails. */
     issueList(opts?: IssueListOptions & AsyncCallOptions): Promise<ListResult<IssueRow>>;
-    /** One issue with its labels; null when there is no such issue. */
+    /** One issue with its labels, or null when there is no such issue. */
     issueView(number: number, opts?: AsyncCallOptions): Promise<IssueRow | null>;
     /** An owner's repositories. Rejects when gh fails. See `Gh.repoList`. */
     repoList(owner: string, opts?: v.RepoListOptions & AsyncCallOptions): Promise<ListResult<Repository>>;
-    /** One repository; null when there is no such repository. See `Gh.repoView`. */
+    /** One repository, or null when there is no such repository. See `Gh.repoView`. */
     repoView(repo?: string | undefined, opts?: {
         fields?: readonly string[] | undefined;
     } & AsyncCallOptions): Promise<Repository | null>;
@@ -119,11 +120,11 @@ export declare class AsyncGh {
     authenticated(): Promise<boolean>;
     /** Login state and what `gh auth status` printed. */
     authStatus(): Promise<AuthStatus>;
-    /** True iff `gh` is installed AND authenticated; short-circuits. */
+    /** True iff `gh` is installed and authenticated. Skips the auth check when `gh` is not installed. */
     ready(): Promise<boolean>;
     /**
      * `{owner, repo}` parsed from the remote URL you pass, or null when it is
-     * null or names no project. Pure, so it is sync on purpose.
+     * null or names no project. It starts no process, so it is sync on purpose.
      */
     ownerRepo(remoteUrl: string | null): OwnerRepo | null;
     /** Open a PR and resolve to its URL ('' if gh printed none). */
@@ -135,12 +136,12 @@ export declare class AsyncGh {
     }): Promise<void>;
     /** Rewrite just a PR's body. */
     editPrBody(number: number, body: string): Promise<void>;
-    /** The PR's unified diff; rejects with the classified failure when gh cannot produce it. */
+    /** The PR's unified diff. Rejects with the classified failure when gh cannot produce it. */
     prDiff(number: number): Promise<string>;
-    /** Post one conversation comment on a PR; resolves to its URL ('' if gh printed none). */
+    /** Post one conversation comment on a PR. Resolves to its URL ('' if gh printed none). */
     prComment(number: number, body: string): Promise<string>;
     /**
-     * Create a `COMMENT` review with inline comments; resolves to the review's URL ('' if none came back).
+     * Create a `COMMENT` review with inline comments. Resolves to the review's URL ('' if none came back).
      *
      * @experimental
      */
@@ -150,17 +151,17 @@ export declare class AsyncGh {
     /** Mark a PR ready for review (`draft: false`) or convert it to a draft (`draft: true`). */
     prSetDraft(number: number, draft: boolean): Promise<void>;
     /**
-     * Rewrite one PR conversation comment's body. `commentId` is the numeric REST id; anything else rejects with `RangeError`.
+     * Rewrite one PR conversation comment's body. `commentId` is the numeric REST id. Anything else rejects with `RangeError`.
      *
      * @experimental
      */
     issueCommentEdit(commentId: string, body: string): Promise<void>;
-    /** Merge a PR; GitHub refuses when its head is no longer `opts.headSha`. */
+    /** Merge a PR. GitHub refuses when its head is no longer `opts.headSha`. */
     prMerge(number: number, opts: {
         method: v.PrMergeMethod;
         headSha: string;
     }): Promise<void>;
-    /** A PR's review threads, or null when they could not be read completely. */
+    /** A PR's review threads. Rejects when they could not be read completely. `soft.prReviewThreads` resolves null instead. */
     prReviewThreads(number: number): Promise<v.ReviewThread[]>;
     /** Create a label (or force it to `opts`'s color/description if it exists). */
     createLabel(opts: v.CreateLabelOptions): Promise<void>;