@osdlc/typed-gh 0.6.0 → 0.9.0

package/dist/run.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `runVerb` and `runVerbAsync` — run one {@link GhVerb} through a runner the
+ * caller owns, with everything the verb asks for applied.
+ *
+ * A verb carries more than `argv`: `input` (a payload on stdin), `env` (the
+ * target host as `GH_HOST`), and `checked` (whether a non-zero exit throws).
+ * `verb.parse(await runner.run(verb.argv))` drops the first two without a
+ * word, so a query goes to github.com and a review is never sent. These two
+ * apply all of it, as `Gh` and `AsyncGh` do; both clients call them.
+ */
+import type { AsyncCommandRunner, CommandRunner } from '@osdlc/command-seam';
+import type { GhVerb } from './verbs.ts';
+/** What a verb run is given besides the verb: the directory and the cap on the call. */
+export interface RunVerbOptions {
+    cwd: string;
+    /** Hard cap on the call, as in command-seam. */
+    timeoutMs?: number | undefined;
+}
+/** {@link RunVerbOptions} for {@link runVerbAsync}, with the abort signal. */
+export interface RunVerbAsyncOptions extends RunVerbOptions {
+    /** Aborts the call; the runner stops the child. */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Run `verb` through `runner` and return its parsed value, honouring the
+ * verb's `input`, `env`, `timeoutMs` and `checked`, and its checked or
+ * unchecked contract: a failed `gh` throws a `FailureError` carrying the
+ * classified `GhFailure`, output that cannot be read throws one of kind
+ * `unreadable`, and a query for one thing answers `null` when GitHub says
+ * there is no such thing.
+ *
+ * A plain `(binary, argv, opts) => result` function is not a runner: wrap it
+ * as `{ run: (argv, opts) => fn('gh', argv, opts) }`.
+ */
+export declare function runVerb<T>(verb: GhVerb<T>, runner: CommandRunner, opts: RunVerbOptions): T;
+/** {@link runVerb} for an `AsyncCommandRunner`; rejects where that throws. */
+export declare function runVerbAsync<T>(verb: GhVerb<T>, runner: AsyncCommandRunner, opts: RunVerbAsyncOptions): Promise<T>;

package/dist/run.js

@@ -0,0 +1,49 @@
+/**
+ * `runVerb` and `runVerbAsync` — run one {@link GhVerb} through a runner the
+ * caller owns, with everything the verb asks for applied.
+ *
+ * A verb carries more than `argv`: `input` (a payload on stdin), `env` (the
+ * target host as `GH_HOST`), and `checked` (whether a non-zero exit throws).
+ * `verb.parse(await runner.run(verb.argv))` drops the first two without a
+ * word, so a query goes to github.com and a review is never sent. These two
+ * apply all of it, as `Gh` and `AsyncGh` do; both clients call them.
+ */
+import { runCheckedGh, runCheckedGhAsync, settle } from "./doors.js";
+/**
+ * Run `verb` through `runner` and return its parsed value, honouring the
+ * verb's `input`, `env`, `timeoutMs` and `checked`, and its checked or
+ * unchecked contract: a failed `gh` throws a `FailureError` carrying the
+ * classified `GhFailure`, output that cannot be read throws one of kind
+ * `unreadable`, and a query for one thing answers `null` when GitHub says
+ * there is no such thing.
+ *
+ * A plain `(binary, argv, opts) => result` function is not a runner: wrap it
+ * as `{ run: (argv, opts) => fn('gh', argv, opts) }`.
+ */
+export function runVerb(verb, runner, opts) {
+    const run = { cwd: opts.cwd };
+    if (verb.input !== undefined)
+        run.input = verb.input;
+    if (verb.env !== undefined)
+        run.env = verb.env;
+    if (opts.timeoutMs !== undefined)
+        run.timeoutMs = opts.timeoutMs;
+    const result = verb.checked ? runCheckedGh(runner, verb.argv, run) : runner.run(verb.argv, run);
+    return settle(verb, result, runner.binary);
+}
+/** {@link runVerb} for an `AsyncCommandRunner`; rejects where that throws. */
+export async function runVerbAsync(verb, runner, opts) {
+    const run = { cwd: opts.cwd };
+    if (verb.input !== undefined)
+        run.input = verb.input;
+    if (verb.env !== undefined)
+        run.env = verb.env;
+    if (opts.timeoutMs !== undefined)
+        run.timeoutMs = opts.timeoutMs;
+    if (opts.signal !== undefined)
+        run.signal = opts.signal;
+    const result = verb.checked
+        ? await runCheckedGhAsync(runner, verb.argv, run)
+        : await runner.run(verb.argv, run);
+    return settle(verb, result, runner.binary);
+}

package/dist/sync.d.ts

@@ -7,11 +7,15 @@
  * 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.
  *
- * Tri-modal, same as the git client: queries return parsed values and never
- * throw, mutations throw `CommandFailed`, and `raw`/`rawChecked` are the
- * escape hatches.
+ * The same three doors as the git client. The plain method returns a value
+ * or throws: a failed `gh` throws a `FailureError` carrying the classified
+ * `GhFailure`, output that cannot be read throws one of kind `unreadable`, and a query for one thing (`prView`, `issueView`,
+ * `repoView`) answers `null` when GitHub says there is no such thing.
+ * `gh.try.*` returns the failure as a `Result<T, GhFailure>`; `gh.soft.*` returns
+ * `null` for it. `raw`/`rawChecked` are the escape hatches.
  */
 import { type CommandResult, type CommandRunner } from '@osdlc/command-seam';
+import { type Soft, type TriedSync } from './doors.ts';
 import * as v from './verbs.ts';
 import type { ApiOptions, ApiResponse, AuthStatus, GhTarget, IssueListOptions, ListResult, PrListOptions } from './verbs.ts';
 import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts';
@@ -47,28 +51,49 @@ export declare class Gh {
     readonly hostname: string | undefined;
     private readonly target;
     private readonly runner;
+    private tried;
+    private softened;
     constructor(cwd: string, opts?: GhOptions);
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd: string): Gh;
     /** The same client aimed at another repository (same runner, directory and host). */
     withRepo(repo: string): Gh;
+    /**
+     * The whole surface again, returning a `Result<T, GhFailure>` instead of
+     * throwing: `gh.try.prList()` is `{ ok: true, value } | { ok: false, error }`.
+     * A query for one thing that finds nothing is `ok: true` with `null`. See
+     * `./doors.ts`.
+     *
+     * The type leaves out the escape hatches and the pure helpers; at runtime
+     * the proxy wraps `raw` and `rawChecked` too. Call those on the client itself.
+     */
+    get try(): TriedSync<Gh>;
+    /**
+     * Each query again, returning `null` instead of throwing when `gh` fails. A
+     * mutation has no soft form. Do not gate a write on a `null` from `soft`:
+     * it is the answer for "could not ask" as well as for "nothing there". Use
+     * `try` where the difference matters.
+     */
+    get soft(): Soft<Gh>;
     /** Unchecked passthrough for verbs not yet lifted into the API. */
     raw(argv: string[], opts?: {
         timeoutMs?: number | undefined;
     }): CommandResult;
-    /** Checked passthrough — throws `CommandFailed` on a non-zero exit. */
+    /** Checked passthrough — throws the classified failure on a non-zero exit. */
     rawChecked(argv: string[], opts?: {
         timeoutMs?: number | undefined;
     }): CommandResult;
     /** Run one verb from the table, honouring its checked/unchecked contract. */
     private exec;
-    /** Pull requests matching `opts`, or null when gh failed. */
+    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run throws. */
+    private read;
+    /** Pull requests matching `opts`. Throws when gh fails; `soft.prList` gives null instead. */
     prList(opts?: PrListOptions & {
         timeoutMs?: number | undefined;
-    }): ListResult<PullRequest> | null;
+    }): ListResult<PullRequest>;
     /**
-     * One PR by number, branch or URL, with the heavy fields; null when gh
-     * failed or there is no such PR.
+     * One PR by number, branch or URL, with the heavy fields; null when there is
+     * no such PR. Throws when gh fails otherwise.
      */
     prView(ref: number | string, opts?: {
         fields?: readonly string[] | undefined;
@@ -119,52 +144,52 @@ export declare class Gh {
         sleep?: ((ms: number) => void) | undefined;
         timeoutMs?: number | undefined;
     }): PullRequest | null;
-    /** A PR's body text, or null when gh failed. */
+    /** A PR's body text. Throws when gh fails. */
     prBody(number: number, opts?: {
         timeoutMs?: number | undefined;
-    }): string | null;
+    }): string;
     /**
-     * A REST GET through `gh api`. Never throws: failure is `ok: false` on the
-     * returned {@link ApiResponse}.
+     * A REST GET through `gh api`. Never throws for a failed call, in any door:
+     * failure is `ok: false` on the returned {@link ApiResponse}.
      */
     api(endpoint: string, opts?: ApiOptions & {
         timeoutMs?: number | undefined;
     }): ApiResponse;
     /**
-     * A GraphQL query; each page's `data`, or null on a failed or partial
-     * result. See the `graphql` verb.
+     * A GraphQL query; each page's `data`. Throws on a failed or partial result;
+     * `soft.graphql` gives null. See the `graphql` verb.
      *
      * @experimental
      */
     graphql(query: string, variables?: Record<string, v.GraphqlVariable>, opts?: v.GraphqlOptions & {
         timeoutMs?: number | undefined;
-    }): unknown[] | null;
-    /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
+    }): unknown[];
+    /** Every label on the repository (up to `opts.limit`, default 1000). Throws when gh fails. */
     labelList(opts?: {
         limit?: number | undefined;
         timeoutMs?: number | undefined;
-    }): ListResult<Label> | null;
-    /** Issues matching `opts` (open by default, up to 200), or null when gh failed. */
+    }): ListResult<Label>;
+    /** Issues matching `opts` (open by default, up to 200). Throws when gh fails. */
     issueList(opts?: IssueListOptions & {
         timeoutMs?: number | undefined;
-    }): ListResult<IssueRow> | null;
-    /** One issue with its labels, or null when gh failed. */
+    }): ListResult<IssueRow>;
+    /** One issue with its labels; null when there is no such issue. Throws when gh fails otherwise. */
     issueView(number: number, opts?: {
         timeoutMs?: number | undefined;
     }): IssueRow | null;
-    /** An owner's repositories (up to `opts.limit`, default 100), or null when gh failed. */
+    /** An owner's repositories (up to `opts.limit`, default 100). Throws when gh fails. */
     repoList(owner: string, opts?: v.RepoListOptions & {
         timeoutMs?: number | undefined;
-    }): ListResult<Repository> | null;
-    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when gh failed. */
+    }): ListResult<Repository>;
+    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when there is no such repository. */
     repoView(repo?: string | undefined, opts?: {
         fields?: readonly string[] | undefined;
         timeoutMs?: number | undefined;
     }): Repository | null;
-    /** Pull requests across repositories matching a search query, or null when gh failed. */
+    /** Pull requests across repositories matching a search query. Throws when gh fails. */
     searchPrs(query: string, opts?: v.SearchPrsOptions & {
         timeoutMs?: number | undefined;
-    }): ListResult<PrSearchHit> | null;
+    }): ListResult<PrSearchHit>;
     /** True iff the `gh` binary is on PATH and runs. */
     installed(): boolean;
     /**
@@ -196,7 +221,7 @@ export declare class Gh {
         title?: string | undefined;
         body?: string | undefined;
     }): void;
-    /** The PR's unified diff; throws `CommandFailed` when gh cannot produce it. */
+    /** The PR's unified diff; throws the classified failure when gh cannot produce it. */
     prDiff(number: number): string;
     /** Post one conversation comment on a PR; returns its URL ('' if gh printed none). */
     prComment(number: number, body: string): string;
@@ -223,8 +248,8 @@ export declare class Gh {
         method: v.PrMergeMethod;
         headSha: string;
     }): void;
-    /** A PR's review threads, or null when they could not be read completely. */
-    prReviewThreads(number: number): v.ReviewThread[] | null;
+    /** A PR's review threads. Throws when they could not be read completely. */
+    prReviewThreads(number: number): v.ReviewThread[];
     /** Create a label (or force it to `opts`'s color/description if it already exists). */
     createLabel(opts: v.CreateLabelOptions): void;
     /** Recolor and/or redescribe an existing label. */
@@ -239,4 +264,3 @@ export declare class Gh {
      */
     setIssueLabel(number: number, currentLabel: string | null, newLabel: string): void;
 }
-//# sourceMappingURL=sync.d.ts.map

package/dist/sync.js

@@ -7,11 +7,16 @@
  * 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.
  *
- * Tri-modal, same as the git client: queries return parsed values and never
- * throw, mutations throw `CommandFailed`, and `raw`/`rawChecked` are the
- * escape hatches.
+ * The same three doors as the git client. The plain method returns a value
+ * or throws: a failed `gh` throws a `FailureError` carrying the classified
+ * `GhFailure`, output that cannot be read throws one of kind `unreadable`, and a query for one thing (`prView`, `issueView`,
+ * `repoView`) answers `null` when GitHub says there is no such thing.
+ * `gh.try.*` returns the failure as a `Result<T, GhFailure>`; `gh.soft.*` returns
+ * `null` for it. `raw`/`rawChecked` are the escape hatches.
  */
-import { runChecked, resolveRunner, spawnRunner, } from '@osdlc/command-seam';
+import { resolveRunner, spawnRunner, } from '@osdlc/command-seam';
+import { runCheckedGh, softSync, triedSync } from "./doors.js";
+import { runVerb } from "./run.js";
 import * as v from "./verbs.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
 /** Default factory: real, spawnSync-backed runners. */
@@ -38,6 +43,8 @@ export class Gh {
     hostname;
     target;
     runner;
+    tried;
+    softened;
     constructor(cwd, opts = {}) {
         v.checkTarget(opts);
         this.cwd = cwd;
@@ -54,37 +61,52 @@ export class Gh {
     withRepo(repo) {
         return new Gh(this.cwd, { runner: this.runner, repo, hostname: this.hostname });
     }
+    /**
+     * The whole surface again, returning a `Result<T, GhFailure>` instead of
+     * throwing: `gh.try.prList()` is `{ ok: true, value } | { ok: false, error }`.
+     * A query for one thing that finds nothing is `ok: true` with `null`. See
+     * `./doors.ts`.
+     *
+     * The type leaves out the escape hatches and the pure helpers; at runtime
+     * the proxy wraps `raw` and `rawChecked` too. Call those on the client itself.
+     */
+    get try() {
+        return (this.tried ??= triedSync(this));
+    }
+    /**
+     * Each query again, returning `null` instead of throwing when `gh` fails. A
+     * mutation has no soft form. Do not gate a write on a `null` from `soft`:
+     * it is the answer for "could not ask" as well as for "nothing there". Use
+     * `try` where the difference matters.
+     */
+    get soft() {
+        return (this.softened ??= softSync(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 — throws `CommandFailed` on a non-zero exit. */
+    /** Checked passthrough — throws the classified failure on a non-zero exit. */
     rawChecked(argv, opts = {}) {
-        return runChecked(this.runner, argv, { cwd: this.cwd, ...opts });
+        return runCheckedGh(this.runner, argv, { cwd: this.cwd, ...opts });
     }
     /** Run one verb from the table, honouring its checked/unchecked contract. */
     exec(verb, timeoutMs) {
-        const opts = { cwd: this.cwd };
-        if (verb.input !== undefined)
-            opts.input = verb.input;
-        if (verb.env !== undefined)
-            opts.env = verb.env;
-        if (timeoutMs !== undefined)
-            opts.timeoutMs = timeoutMs;
-        const result = verb.checked
-            ? runChecked(this.runner, verb.argv, opts)
-            : this.runner.run(verb.argv, opts);
-        return verb.parse(result);
+        return runVerb(verb, this.runner, { cwd: this.cwd, timeoutMs });
+    }
+    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run throws. */
+    read(verb, timeoutMs) {
+        return this.exec(verb, timeoutMs);
     }
     // ── queries ───────────────────────────────────────────────────────────────
-    /** Pull requests matching `opts`, or null when gh failed. */
+    /** Pull requests matching `opts`. Throws when gh fails; `soft.prList` gives null instead. */
     prList(opts = {}) {
-        return this.exec(v.prList(opts, this.target), opts.timeoutMs);
+        return this.read(v.prList(opts, this.target), opts.timeoutMs);
     }
     /**
-     * One PR by number, branch or URL, with the heavy fields; null when gh
-     * failed or there is no such PR.
+     * One PR by number, branch or URL, with the heavy fields; null when there is
+     * no such PR. Throws when gh fails otherwise.
      */
     prView(ref, opts = {}) {
         return this.exec(v.prView(ref, opts.fields ?? v.PR_VIEW_FIELDS, this.target), opts.timeoutMs);
@@ -128,7 +150,7 @@ export class Gh {
             limit: opts.limit ?? 5,
             fields: opts.fields ?? v.PR_REF_FIELDS,
         });
-        return v.pickPrForBranch(rows?.rows ?? null, branch);
+        return v.pickPrForBranch(rows.rows, branch);
     }
     /**
      * {@link prView}, re-asked until GitHub settles the merge state.
@@ -155,49 +177,49 @@ export class Gh {
         }
         return last;
     }
-    /** A PR's body text, or null when gh failed. */
+    /** A PR's body text. Throws when gh fails. */
     prBody(number, opts = {}) {
-        return this.exec(v.prBody(number, this.target), opts.timeoutMs);
+        return this.read(v.prBody(number, this.target), opts.timeoutMs);
     }
     /**
-     * A REST GET through `gh api`. Never throws: failure is `ok: false` on the
-     * returned {@link ApiResponse}.
+     * A REST GET through `gh api`. Never throws for a failed call, in any door:
+     * failure is `ok: false` on the returned {@link ApiResponse}.
      */
     api(endpoint, opts = {}) {
         return this.exec(v.api(endpoint, opts, this.target), opts.timeoutMs);
     }
     /**
-     * A GraphQL query; each page's `data`, or null on a failed or partial
-     * result. See the `graphql` verb.
+     * A GraphQL query; each page's `data`. Throws on a failed or partial result;
+     * `soft.graphql` gives null. See the `graphql` verb.
      *
      * @experimental
      */
     graphql(query, variables = {}, opts = {}) {
-        return this.exec(v.graphql(query, variables, opts, this.target), opts.timeoutMs);
+        return this.read(v.graphql(query, variables, opts, this.target), opts.timeoutMs);
     }
-    /** 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). Throws when gh fails. */
     labelList(opts = {}) {
-        return this.exec(v.labelList(opts, this.target), opts.timeoutMs);
+        return this.read(v.labelList(opts, this.target), opts.timeoutMs);
     }
-    /** Issues matching `opts` (open by default, up to 200), or null when gh failed. */
+    /** Issues matching `opts` (open by default, up to 200). Throws when gh fails. */
     issueList(opts = {}) {
-        return this.exec(v.issueList(opts, this.target), opts.timeoutMs);
+        return this.read(v.issueList(opts, this.target), opts.timeoutMs);
     }
-    /** One issue with its labels, or null when gh failed. */
+    /** One issue with its labels; null when there is no such issue. Throws when gh fails otherwise. */
     issueView(number, opts = {}) {
         return this.exec(v.issueView(number, this.target), opts.timeoutMs);
     }
-    /** An owner's repositories (up to `opts.limit`, default 100), or null when gh failed. */
+    /** An owner's repositories (up to `opts.limit`, default 100). Throws when gh fails. */
     repoList(owner, opts = {}) {
-        return this.exec(v.repoList(owner, opts, this.target), opts.timeoutMs);
+        return this.read(v.repoList(owner, opts, this.target), opts.timeoutMs);
     }
-    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when gh failed. */
+    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when there is no such repository. */
     repoView(repo, opts = {}) {
         return this.exec(v.repoView(repo, opts.fields ?? v.REPO_FIELDS, this.target), opts.timeoutMs);
     }
-    /** Pull requests across repositories matching a search query, or null when gh failed. */
+    /** Pull requests across repositories matching a search query. Throws when gh fails. */
     searchPrs(query, opts = {}) {
-        return this.exec(v.searchPrs(query, opts, this.target), opts.timeoutMs);
+        return this.read(v.searchPrs(query, opts, this.target), opts.timeoutMs);
     }
     /** True iff the `gh` binary is on PATH and runs. */
     installed() {
@@ -242,7 +264,7 @@ export class Gh {
     editPr(number, opts) {
         this.exec(v.editPr(number, opts, this.target));
     }
-    /** The PR's unified diff; throws `CommandFailed` when gh cannot produce it. */
+    /** The PR's unified diff; throws the classified failure when gh cannot produce it. */
     prDiff(number) {
         return this.exec(v.prDiff(number, this.target));
     }
@@ -282,9 +304,9 @@ export class Gh {
     prMerge(number, opts) {
         this.exec(v.prMerge(number, opts, this.target));
     }
-    /** A PR's review threads, or null when they could not be read completely. */
+    /** A PR's review threads. Throws 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 already exists). */
     createLabel(opts) {

package/dist/types.d.ts

@@ -186,4 +186,3 @@ export interface PrSearchHit {
     updatedAt: string | null;
     closedAt: string | null;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/verbs.d.ts

@@ -7,9 +7,12 @@
  * asynchronous fan-out drive the same definitions without either duplicating
  * the other's parsing.
  *
- * `checked` marks a verb whose failure is thrown with stderr: every mutation,
- * and `prDiff`, which is a read. Other queries are unchecked and fold failure
- * into an absence value.
+ * `checked` marks a verb the runner throws for on a non-zero exit, with
+ * stderr: every mutation, and `prDiff`, which is a read. Other queries are run
+ * unchecked and `parse` folds a failure into `null`, which is the verb's
+ * *soft* reading. The clients' plain door reads them through `settle` (see
+ * `doors.ts`) instead: a failure throws, except where the verb declares
+ * `absent` or is a `probe`.
  */
 import { type CommandResult } from '@osdlc/command-seam';
 import type { IssueRow, Label, PrSearchHit, PullRequest, Repository } from './types.ts';
@@ -31,6 +34,19 @@ export interface GhVerb<T> {
      * on `gh search` and `gh repo list`.
      */
     env?: Record<string, string> | undefined;
+    /**
+     * True for a read whose failure is part of its answer: `installed`,
+     * `authStatus` and `api` return what `parse` makes of any result, in every
+     * door. Other reads fail the plain door when gh exits non-zero.
+     */
+    probe?: boolean | undefined;
+    /**
+     * For a read of one thing: whether a non-zero result means GitHub has no such
+     * thing (`prView`, `issueView`, `repoView`). The plain door then returns what
+     * `parse` makes of it, `null`, because absence is an answer. Other non-zero
+     * results fail the call.
+     */
+    absent?: ((result: CommandResult) => boolean) | undefined;
     parse(result: CommandResult): T;
 }
 /**
@@ -104,7 +120,7 @@ export interface PrListOptions {
     search?: string | undefined;
     author?: string | undefined;
     limit?: number | undefined;
-    /** Field subset; defaults to {@link PR_LIST_FIELDS}. */
+    /** Field subset; defaults to {@link PR_LIST_FIELDS}. `number` is always requested. */
     fields?: readonly string[] | undefined;
 }
 /** `gh pr list …` — open PRs by default. `opts.repo` overrides the target's repo. */
@@ -137,13 +153,15 @@ export declare function prBody(number: number, target?: GhTarget): GhVerb<string
 export interface ApiResponse {
     /** True iff gh exited 0 and the status is below 400 (2xx, or a 304 on a conditional GET). */
     ok: boolean;
-    /** HTTP status; read off the header block under `-i`. Without `-i` it is synthesized (200 on exit 0, 0 on failure), not observed. */
+    /** HTTP status; set only when headers were requested (`-i`, `etag` or `includeHeaders`). Without them it is synthesized (200 on exit 0, 0 on failure), not observed. */
     status: number;
     /** The response `ETag`, when headers were requested and one came back. */
     etag: string | null;
-    /** The decoded JSON body; null when empty (e.g. a 304), unparseable, or the call failed. */
+    /** The decoded JSON body, whatever gh's exit code (on failure, GitHub's error object); null when empty (e.g. a 304) or unparseable. */
     body: unknown;
-    /** True when a non-empty body arrived but was not valid JSON (`body` is then null). */
+    /** `body.message` when the body is an object with a string `message` (GitHub's error text), else null. */
+    message: string | null;
+    /** True when a non-empty body arrived but was not valid JSON (`body` is then null); also true on a failed call with a non-JSON body. */
     malformed: boolean;
     /** gh's stderr, trimmed. */
     stderr: string;
@@ -461,4 +479,3 @@ export declare function branchPrFields(fields: readonly string[]): string[];
  * slow, so re-ask a few times before believing it.
  */
 export declare function needsMergeStateRetry(pr: PullRequest): boolean;
-//# sourceMappingURL=verbs.d.ts.map

package/dist/verbs.js

@@ -7,13 +7,21 @@
  * asynchronous fan-out drive the same definitions without either duplicating
  * the other's parsing.
  *
- * `checked` marks a verb whose failure is thrown with stderr: every mutation,
- * and `prDiff`, which is a read. Other queries are unchecked and fold failure
- * into an absence value.
+ * `checked` marks a verb the runner throws for on a non-zero exit, with
+ * stderr: every mutation, and `prDiff`, which is a read. Other queries are run
+ * unchecked and `parse` folds a failure into `null`, which is the verb's
+ * *soft* reading. The clients' plain door reads them through `settle` (see
+ * `doors.ts`) instead: a failure throws, except where the verb declares
+ * `absent` or is a `probe`.
  */
 import { stderrOrError } from '@osdlc/command-seam';
 import { parseLabels, parsePrSearchHit, parsePullRequest, parseRepository } from "./parse.js";
+import { isAbsent } from "./failure.js";
 import { isRepoSlug, parsePrUrl } from "./repo.js";
+/** Whether a failed run says GitHub has no such `thing`: read from the same text the classifier reads. */
+function noSuch(thing) {
+    return (r) => isAbsent(thing, `${r.stderr}\n${r.stdout}`);
+}
 const HOSTNAME = /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?(?::\d+)?$/;
 /**
  * Throw `RangeError` unless `target.repo` is `owner/name` and
@@ -243,9 +251,12 @@ export function prList(opts = {}, target) {
         argv.push('--search', opts.search);
     if (opts.author !== undefined)
         argv.push('--author', opts.author);
-    // The exact-head filter below reads `headRefName`, so ask for it.
-    const fields = opts.fields ?? PR_LIST_FIELDS;
-    const asked = opts.head === undefined ? fields : withFields(fields, ['headRefName']);
+    // A row without `number` does not parse and is dropped, so always ask for it;
+    // the exact-head filter below also reads `headRefName`.
+    const asked = withFields(opts.fields ?? PR_LIST_FIELDS, [
+        'number',
+        ...(opts.head === undefined ? [] : ['headRefName']),
+    ]);
     argv.push('--json', asked.join(','));
     argv.push('--limit', String(limit + 1));
     const head = opts.head;
@@ -300,6 +311,7 @@ export function prView(ref, fields = PR_VIEW_FIELDS, target) {
         ],
         checked: false,
         readOnly: true,
+        absent: noSuch('pr'),
         parse: oneOrNull,
     };
 }
@@ -354,6 +366,7 @@ export function api(endpoint, opts = {}, target) {
         argv,
         checked: false,
         readOnly: true,
+        probe: true,
         parse(r) {
             const response = parseApi(r, withHeaders);
             return paginate ? { ...response, body: flattenPages(response.body) } : response;
@@ -506,7 +519,7 @@ function parseApi(r, withHeaders) {
     }
     let body = null;
     let malformed = false;
-    if (r.exitCode === 0 && bodyText.trim() !== '') {
+    if (bodyText.trim() !== '') {
         try {
             body = JSON.parse(bodyText);
         }
@@ -515,11 +528,15 @@ function parseApi(r, withHeaders) {
         }
     }
     const ok = r.exitCode === 0 && status >= 200 && status < 400;
+    const rawMessage = body !== null && typeof body === 'object' && !Array.isArray(body)
+        ? body['message']
+        : undefined;
     return {
         ok,
         status,
         etag,
         body,
+        message: typeof rawMessage === 'string' ? rawMessage : null,
         malformed,
         stderr: r.stderr.trim(),
         ...(r.error === undefined ? {} : { error: r.error }),
@@ -527,7 +544,13 @@ function parseApi(r, withHeaders) {
 }
 /** `gh --version` — the install probe. True when `gh` runs. */
 export function installed() {
-    return { argv: ['--version'], checked: false, readOnly: true, parse: (r) => r.exitCode === 0 };
+    return {
+        argv: ['--version'],
+        checked: false,
+        readOnly: true,
+        probe: true,
+        parse: (r) => r.exitCode === 0,
+    };
 }
 /** `gh auth status [--hostname <host>]` — the credential probe, for one host when the target names it. */
 export function authStatus(target) {
@@ -535,6 +558,7 @@ export function authStatus(target) {
         argv: ['auth', 'status', ...hostArgs(target)],
         checked: false,
         readOnly: true,
+        probe: true,
         parse: (r) => ({ ok: r.exitCode === 0, detail: stderrOrError(r) || r.stdout.trim() }),
     };
 }
@@ -576,6 +600,7 @@ export function issueView(number, target) {
         argv: ['issue', 'view', String(number), ...repoArgs(target), '--json', ISSUE_FIELDS],
         checked: false,
         readOnly: true,
+        absent: noSuch('issue'),
         parse: oneIssueOrNull,
     };
 }
@@ -660,6 +685,7 @@ export function repoView(repo, fields = REPO_FIELDS, target) {
         argv,
         checked: false,
         readOnly: true,
+        absent: noSuch('repo'),
         parse(r) {
             if (r.exitCode !== 0)
                 return null;