@osdlc/typed-gh 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,4 +1,40 @@
-# 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
 

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.
 
@@ -88,18 +90,69 @@ 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'
 
-| | 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. |
+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`."
+}
+```
 
-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".
+### `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
 
@@ -108,9 +161,9 @@ 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 })
+const page: ListResult<PullRequest> = gh.prList({ limit: 50 })
 
-if (page?.truncated) console.warn('more than 50 open PRs; raise the limit')
+if (page.truncated) console.warn('more than 50 open PRs; raise the limit')
 ```
 
 `prList`, `issueList`, `labelList`, `repoList` and `searchPrs` all work this
@@ -130,7 +183,7 @@ acme.withRepo('acme/gadgets').prList()
 acme.api('repos/{owner}/{repo}/branches')
 ```
 
-The target goes into the argv, so a `CommandFailed` shows which repository a
+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
@@ -213,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)
@@ -241,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: ListResult<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: ListResult<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' })
 ```
@@ -279,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
@@ -307,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
@@ -317,7 +370,7 @@ 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')
@@ -346,8 +399,8 @@ without one. If `gh` prints more than one header block, the last one is read. `{
 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
+`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
@@ -369,9 +422,9 @@ 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' })
+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`,
@@ -422,9 +475,15 @@ Methods on both clients:
 - Issue and label queries: `issueList`, `issueView` and `labelList`.
 - Repository queries: `repoList` and `repoView`.
 - Issue and label changes: `setIssueLabel`, `createLabel`, `editLabel` and `issueCommentEdit`.
-- REST and GraphQL: `api` is a GET through `gh api` and `graphql` a query; neither 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
 
@@ -473,7 +532,7 @@ the escape hatches, `at`, `withRepo`, `prViewSettled`, `openPrFor`, `prFind`, `a
 
 ### 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.
 
@@ -514,4 +573,4 @@ shell, so nothing in it is specific to one shell.
 
 ## 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).

package/dist/async.d.ts

@@ -1,13 +1,16 @@
 /**
  * `AsyncGh` — the awaitable GitHub client, with the same methods as {@link Gh}.
  *
- * Same tri-modal contract, promised: queries resolve to parsed values and
- * never reject on a gh failure, mutations reject with `CommandFailed`, and
- * `raw`/`rawChecked` are the hatches. It is driven by the same pure verb
+ * 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.
  */
 import { type AsyncCommandRunner, type CommandResult } from '@osdlc/command-seam';
+import { type Soft, type TriedAsync } from './doors.ts';
 import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts';
 import * as v from './verbs.ts';
 import type { ApiOptions, ApiResponse, AuthStatus, GhTarget, IssueListOptions, ListResult, PrListOptions } from './verbs.ts';
@@ -40,19 +43,31 @@ export declare class AsyncGh {
     readonly hostname: string | undefined;
     private readonly target;
     private readonly runner;
+    private tried;
+    private softened;
     constructor(cwd: string, opts?: AsyncGhOptions);
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd: string): AsyncGh;
     /** The same client aimed at another repository (same runner, directory and host). */
     withRepo(repo: string): AsyncGh;
+    /**
+     * The whole surface again, resolving to a `Result<T, GhFailure>` instead of
+     * rejecting. A query for one thing that finds nothing is `ok: true` with
+     * `null`. See `Gh.try`.
+     */
+    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. */
     raw(argv: string[], opts?: AsyncCallOptions): Promise<CommandResult>;
-    /** Checked passthrough — rejects with `CommandFailed` on a non-zero exit. */
+    /** Checked passthrough — 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. */
     private exec;
-    /** Pull requests matching `opts`, or null when gh failed. */
-    prList(opts?: PrListOptions & AsyncCallOptions): Promise<ListResult<PullRequest> | null>;
+    /** {@link exec} for a verb that never answers `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. */
+    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?: {
         fields?: readonly string[] | undefined;
@@ -72,32 +87,32 @@ export declare class AsyncGh {
         fields?: readonly string[] | undefined;
         sleep?: ((ms: number) => Promise<void>) | undefined;
     } & AsyncCallOptions): Promise<PullRequest | null>;
-    /** A PR's body text, or null when gh failed. */
-    prBody(number: number, opts?: AsyncCallOptions): Promise<string | 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. */
     api(endpoint: string, opts?: ApiOptions & AsyncCallOptions): Promise<ApiResponse>;
     /**
-     * A GraphQL query; each page's `data`, or null. See `Gh.graphql`.
+     * A GraphQL query; each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
      *
      * @experimental
      */
-    graphql(query: string, variables?: Record<string, v.GraphqlVariable>, opts?: v.GraphqlOptions & AsyncCallOptions): Promise<unknown[] | null>;
-    /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
+    graphql(query: string, variables?: Record<string, v.GraphqlVariable>, opts?: v.GraphqlOptions & AsyncCallOptions): Promise<unknown[]>;
+    /** Every label on the repository (up to `opts.limit`, default 1000). Rejects when gh fails. */
     labelList(opts?: {
         limit?: number | undefined;
-    } & AsyncCallOptions): Promise<ListResult<Label> | null>;
-    /** Issues matching `opts`, or null when gh failed. */
-    issueList(opts?: IssueListOptions & AsyncCallOptions): Promise<ListResult<IssueRow> | null>;
-    /** One issue with its labels, or null when gh failed. */
+    } & 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. */
     issueView(number: number, opts?: AsyncCallOptions): Promise<IssueRow | null>;
-    /** An owner's repositories, or null when gh failed. See `Gh.repoList`. */
-    repoList(owner: string, opts?: v.RepoListOptions & AsyncCallOptions): Promise<ListResult<Repository> | null>;
-    /** One repository, or null when gh failed. See `Gh.repoView`. */
+    /** 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`. */
     repoView(repo?: string | undefined, opts?: {
         fields?: readonly string[] | undefined;
     } & AsyncCallOptions): Promise<Repository | null>;
-    /** Pull requests across repositories matching a search query, or null. See `Gh.searchPrs`. */
-    searchPrs(query: string, opts?: v.SearchPrsOptions & AsyncCallOptions): Promise<ListResult<PrSearchHit> | null>;
+    /** Pull requests across repositories matching a search query. Rejects when gh fails. See `Gh.searchPrs`. */
+    searchPrs(query: string, opts?: v.SearchPrsOptions & AsyncCallOptions): Promise<ListResult<PrSearchHit>>;
     /** True iff the `gh` binary is on PATH and runs. */
     installed(): Promise<boolean>;
     /** True iff `gh` holds credentials. */
@@ -120,7 +135,7 @@ 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 `CommandFailed` 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). */
     prComment(number: number, body: string): Promise<string>;
@@ -146,7 +161,7 @@ export declare class AsyncGh {
         headSha: string;
     }): Promise<void>;
     /** A PR's review threads, or null when they could not be read completely. */
-    prReviewThreads(number: number): Promise<v.ReviewThread[] | null>;
+    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>;
     /** Recolor and/or redescribe an existing label. */
@@ -157,4 +172,3 @@ export declare class AsyncGh {
     /** Swap an issue's label in a single `gh issue edit` call. */
     setIssueLabel(number: number, currentLabel: string | null, newLabel: string): Promise<void>;
 }
-//# sourceMappingURL=async.d.ts.map

package/dist/async.js

@@ -1,13 +1,16 @@
 /**
  * `AsyncGh` — the awaitable GitHub client, with the same methods as {@link Gh}.
  *
- * Same tri-modal contract, promised: queries resolve to parsed values and
- * never reject on a gh failure, mutations reject with `CommandFailed`, and
- * `raw`/`rawChecked` are the hatches. It is driven by the same pure verb
+ * 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.
  */
-import { runCheckedAsync, resolveRunnerAsync, } from '@osdlc/command-seam';
+import { resolveRunnerAsync, } from '@osdlc/command-seam';
+import { runCheckedGhAsync, settle, softAsync, triedAsync, } from "./doors.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
 import * as v from "./verbs.js";
 /** How long to wait between merge-state retries, in milliseconds. */
@@ -22,6 +25,8 @@ export class AsyncGh {
     hostname;
     target;
     runner;
+    tried;
+    softened;
     constructor(cwd, opts = {}) {
         v.checkTarget(opts);
         this.cwd = cwd;
@@ -38,14 +43,26 @@ export class AsyncGh {
     withRepo(repo) {
         return new AsyncGh(this.cwd, { runner: this.runner, repo, hostname: this.hostname });
     }
+    /**
+     * The whole surface again, resolving to a `Result<T, GhFailure>` instead of
+     * rejecting. A query for one thing that finds nothing is `ok: true` with
+     * `null`. See `Gh.try`.
+     */
+    get try() {
+        return (this.tried ??= triedAsync(this));
+    }
+    /** Each query again, resolving `null` instead of rejecting when `gh` fails. See `Gh.soft`. */
+    get soft() {
+        return (this.softened ??= softAsync(this));
+    }
     // ── escape hatches ────────────────────────────────────────────────────────
     /** Unchecked passthrough for verbs not yet lifted into the API. */
     raw(argv, opts = {}) {
         return this.runner.run(argv, { cwd: this.cwd, ...opts });
     }
-    /** Checked passthrough — rejects with `CommandFailed` on a non-zero exit. */
+    /** Checked passthrough — rejects with the classified failure on a non-zero exit. */
     rawChecked(argv, opts = {}) {
-        return runCheckedAsync(this.runner, argv, { cwd: this.cwd, ...opts });
+        return runCheckedGhAsync(this.runner, argv, { cwd: this.cwd, ...opts });
     }
     /** Run one verb from the table, honouring its checked/unchecked contract. */
     async exec(verb, call = {}) {
@@ -59,14 +76,18 @@ export class AsyncGh {
         if (call.signal !== undefined)
             opts.signal = call.signal;
         const result = verb.checked
-            ? await runCheckedAsync(this.runner, verb.argv, opts)
+            ? await runCheckedGhAsync(this.runner, verb.argv, opts)
             : await this.runner.run(verb.argv, opts);
-        return verb.parse(result);
+        return settle(verb, result, this.runner.binary);
+    }
+    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run rejects. */
+    async read(verb, call = {}) {
+        return (await this.exec(verb, call));
     }
     // ── queries ───────────────────────────────────────────────────────────────
-    /** Pull requests matching `opts`, or null when gh failed. */
+    /** Pull requests matching `opts`. Rejects when gh fails; `soft.prList` resolves null instead. */
     prList(opts = {}) {
-        return this.exec(v.prList(opts, this.target), opts);
+        return this.read(v.prList(opts, this.target), opts);
     }
     /** One PR by number, branch or URL, with the heavy fields, or null. See `Gh.prView`. */
     prView(ref, opts = {}) {
@@ -95,7 +116,7 @@ export class AsyncGh {
             timeoutMs: opts.timeoutMs,
             signal: opts.signal,
         });
-        return v.pickPrForBranch(rows?.rows ?? null, branch);
+        return v.pickPrForBranch(rows.rows, branch);
     }
     /** {@link prView}, re-asked until GitHub settles the merge state. See `Gh.prViewSettled`. */
     async prViewSettled(number, opts = {}) {
@@ -111,45 +132,45 @@ export class AsyncGh {
         }
         return last;
     }
-    /** A PR's body text, or null when gh failed. */
+    /** A PR's body text. Rejects when gh fails. */
     prBody(number, opts = {}) {
-        return this.exec(v.prBody(number, this.target), opts);
+        return this.read(v.prBody(number, this.target), opts);
     }
     /** A REST GET through `gh api`; failure is `ok: false`, never a rejection. */
     api(endpoint, opts = {}) {
         return this.exec(v.api(endpoint, opts, this.target), opts);
     }
     /**
-     * A GraphQL query; each page's `data`, or null. See `Gh.graphql`.
+     * A GraphQL query; each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
      *
      * @experimental
      */
     graphql(query, variables = {}, opts = {}) {
-        return this.exec(v.graphql(query, variables, opts, this.target), opts);
+        return this.read(v.graphql(query, variables, opts, this.target), opts);
     }
-    /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
+    /** Every label on the repository (up to `opts.limit`, default 1000). Rejects when gh fails. */
     labelList(opts = {}) {
-        return this.exec(v.labelList(opts, this.target), opts);
+        return this.read(v.labelList(opts, this.target), opts);
     }
-    /** Issues matching `opts`, or null when gh failed. */
+    /** Issues matching `opts`. Rejects when gh fails. */
     issueList(opts = {}) {
-        return this.exec(v.issueList(opts, this.target), opts);
+        return this.read(v.issueList(opts, this.target), opts);
     }
-    /** One issue with its labels, or null when gh failed. */
+    /** One issue with its labels; null when there is no such issue. */
     issueView(number, opts = {}) {
         return this.exec(v.issueView(number, this.target), opts);
     }
-    /** An owner's repositories, or null when gh failed. See `Gh.repoList`. */
+    /** An owner's repositories. Rejects when gh fails. See `Gh.repoList`. */
     repoList(owner, opts = {}) {
-        return this.exec(v.repoList(owner, opts, this.target), opts);
+        return this.read(v.repoList(owner, opts, this.target), opts);
     }
-    /** One repository, or null when gh failed. See `Gh.repoView`. */
+    /** One repository; null when there is no such repository. See `Gh.repoView`. */
     repoView(repo, opts = {}) {
         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`. */
+    /** Pull requests across repositories matching a search query. Rejects when gh fails. See `Gh.searchPrs`. */
     searchPrs(query, opts = {}) {
-        return this.exec(v.searchPrs(query, opts, this.target), opts);
+        return this.read(v.searchPrs(query, opts, this.target), opts);
     }
     /** True iff the `gh` binary is on PATH and runs. */
     installed() {
@@ -187,7 +208,7 @@ export class AsyncGh {
     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. */
+    /** The PR's unified diff; rejects with the classified failure when gh cannot produce it. */
     prDiff(number) {
         return this.exec(v.prDiff(number, this.target));
     }
@@ -226,7 +247,7 @@ export class AsyncGh {
     }
     /** A PR's review threads, or null when they could not be read completely. */
     prReviewThreads(number) {
-        return this.exec(v.prReviewThreads(number, this.target));
+        return this.read(v.prReviewThreads(number, this.target));
     }
     /** Create a label (or force it to `opts`'s color/description if it exists). */
     createLabel(opts) {