@osdlc/typed-gh 0.5.0 → 0.7.0

package/dist/async.d.ts

@@ -1,20 +1,23 @@
 /**
  * `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 { IssueRow, Label, OwnerRepo, PullRequest } from './types.ts';
+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, IssueListOptions, PrListOptions } from './verbs.ts';
+import type { ApiOptions, ApiResponse, AuthStatus, GhTarget, IssueListOptions, ListResult, PrListOptions } from './verbs.ts';
 /**
- * Per-call options for {@link AsyncGh}. Eleven methods accept them: `raw`, `rawChecked`,
- * `prList`, `prView`, `openPrFor`, `prViewSettled`, `prBody`, `api`, `labelList`,
- * `issueList` and `issueView`.
+ * Per-call options for {@link AsyncGh}. Sixteen methods accept them: `raw`, `rawChecked`,
+ * `prList`, `prView`, `prFind`, `openPrFor`, `prViewSettled`, `prBody`, `api`, `graphql`,
+ * `labelList`, `issueList`, `issueView`, `repoList`, `repoView` and `searchPrs`.
  */
 export interface AsyncCallOptions {
     /**
@@ -26,25 +29,51 @@ export interface AsyncCallOptions {
     /** Aborts the call; the runner stops the child. */
     signal?: AbortSignal | undefined;
 }
-/** A typed, awaitable gh client bound to one working directory. */
+/** What an {@link AsyncGh} is built with: the runner, and the repository and host it talks to. */
+export interface AsyncGhOptions extends GhTarget {
+    runner?: AsyncCommandRunner | undefined;
+}
+/**
+ * A typed, awaitable gh client bound to one working directory, and optionally
+ * to one repository and host. `repo` and `hostname` work as on `Gh`.
+ */
 export declare class AsyncGh {
     readonly cwd: string;
+    readonly repo: string | undefined;
+    readonly hostname: string | undefined;
+    private readonly target;
     private readonly runner;
-    constructor(cwd: string, opts?: {
-        runner?: AsyncCommandRunner | undefined;
-    });
-    /** The same client rooted at a different directory (same 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<PullRequest[] | null>;
-    /** One PR with the heavy fields, or null when gh failed. */
-    prView(number: number, opts?: {
+    /** {@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;
+    } & AsyncCallOptions): Promise<PullRequest | null>;
+    /** The one PR that `input` names, or null. See `Gh.prFind`. */
+    prFind(input: string, opts?: {
         fields?: readonly string[] | undefined;
     } & AsyncCallOptions): Promise<PullRequest | null>;
     /** The open PR whose head exactly equals `branch`, or null. See `Gh.openPrFor`. */
@@ -58,18 +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>;
-    /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
+    /**
+     * 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[]>;
+    /** Every label on the repository (up to `opts.limit`, default 1000). Rejects when gh fails. */
     labelList(opts?: {
         limit?: number | undefined;
-    } & AsyncCallOptions): Promise<Label[] | null>;
-    /** Issues matching `opts`, or null when gh failed. */
-    issueList(opts?: IssueListOptions & AsyncCallOptions): Promise<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. 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. 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. */
@@ -92,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>;
@@ -118,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. */
@@ -129,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,60 +1,111 @@
 /**
  * `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 { parseOwnerRepo } from "./repo.js";
+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. */
 const MERGE_STATE_RETRY_DELAY_MS = 1_500;
-/** A typed, awaitable gh client bound to one working directory. */
+/**
+ * A typed, awaitable gh client bound to one working directory, and optionally
+ * to one repository and host. `repo` and `hostname` work as on `Gh`.
+ */
 export class AsyncGh {
     cwd;
+    repo;
+    hostname;
+    target;
     runner;
+    tried;
+    softened;
     constructor(cwd, opts = {}) {
+        v.checkTarget(opts);
         this.cwd = cwd;
+        this.repo = opts.repo;
+        this.hostname = opts.hostname;
+        this.target = { repo: opts.repo, hostname: opts.hostname };
         this.runner = resolveRunnerAsync('gh', opts.runner);
     }
-    /** The same client rooted at a different directory (same runner). */
+    /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd) {
-        return new AsyncGh(cwd, { runner: this.runner });
+        return new AsyncGh(cwd, { runner: this.runner, repo: this.repo, hostname: this.hostname });
+    }
+    /** The same client aimed at another repository (same runner, directory and host). */
+    withRepo(repo) {
+        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 = {}) {
         const opts = { cwd: this.cwd };
         if (verb.input !== undefined)
             opts.input = verb.input;
+        if (verb.env !== undefined)
+            opts.env = verb.env;
         if (call.timeoutMs !== undefined)
             opts.timeoutMs = call.timeoutMs;
         if (call.signal !== undefined)
             opts.signal = call.signal;
         const result = verb.checked
-            ? 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), opts);
-    }
-    /** One PR with the heavy fields, or null when gh failed. */
-    prView(number, opts = {}) {
-        return this.exec(v.prView(number, opts.fields ?? v.PR_VIEW_FIELDS), 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 = {}) {
+        return this.exec(v.prView(ref, opts.fields ?? v.PR_VIEW_FIELDS, this.target), opts);
+    }
+    /** The one PR that `input` names, or null. See `Gh.prFind`. */
+    async prFind(input, opts = {}) {
+        const ref = parsePrRef(input);
+        if (ref === null)
+            return null;
+        const call = { ...opts, fields: opts.fields ?? v.PR_LIST_FIELDS };
+        if (ref.kind === 'url')
+            return this.prView(ref.url, call);
+        if (ref.kind === 'branch')
+            return prForBranchOn(this, ref.name, call);
+        const client = ref.repo === null ? this : this.withRepo(ownerRepoSlug(ref.repo));
+        const pr = await client.prView(ref.number, call);
+        return pr !== null || ref.orBranch === null ? pr : prForBranchOn(this, ref.orBranch, call);
     }
     /** The open PR whose head exactly equals `branch`, or null. See `Gh.openPrFor`. */
     async openPrFor(branch, opts = {}) {
@@ -65,7 +116,7 @@ export class AsyncGh {
             timeoutMs: opts.timeoutMs,
             signal: opts.signal,
         });
-        return v.pickPrForBranch(rows, branch);
+        return v.pickPrForBranch(rows.rows, branch);
     }
     /** {@link prView}, re-asked until GitHub settles the merge state. See `Gh.prViewSettled`. */
     async prViewSettled(number, opts = {}) {
@@ -81,25 +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), 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), opts);
+        return this.exec(v.api(endpoint, opts, this.target), opts);
     }
-    /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
+    /**
+     * A GraphQL query; each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
+     *
+     * @experimental
+     */
+    graphql(query, variables = {}, opts = {}) {
+        return this.read(v.graphql(query, variables, opts, this.target), opts);
+    }
+    /** Every label on the repository (up to `opts.limit`, default 1000). Rejects when gh fails. */
     labelList(opts = {}) {
-        return this.exec(v.labelList(opts), 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), 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), opts);
+        return this.exec(v.issueView(number, this.target), opts);
+    }
+    /** An owner's repositories. Rejects when gh fails. See `Gh.repoList`. */
+    repoList(owner, opts = {}) {
+        return this.read(v.repoList(owner, opts, this.target), opts);
+    }
+    /** 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. Rejects when gh fails. See `Gh.searchPrs`. */
+    searchPrs(query, opts = {}) {
+        return this.read(v.searchPrs(query, opts, this.target), opts);
     }
     /** True iff the `gh` binary is on PATH and runs. */
     installed() {
@@ -111,7 +182,7 @@ export class AsyncGh {
     }
     /** Login state and what `gh auth status` printed. */
     authStatus() {
-        return this.exec(v.authStatus());
+        return this.exec(v.authStatus(this.target));
     }
     /** True iff `gh` is installed AND authenticated; short-circuits. */
     async ready() {
@@ -127,23 +198,23 @@ export class AsyncGh {
     // ── mutations (checked) ───────────────────────────────────────────────────
     /** Open a PR and resolve to its URL ('' if gh printed none). */
     createPr(opts) {
-        return this.exec(v.createPr(opts));
+        return this.exec(v.createPr(opts, this.target));
     }
     /** Retitle or rewrite a PR body. */
     editPr(number, opts) {
-        return this.exec(v.editPr(number, opts));
+        return this.exec(v.editPr(number, opts, this.target));
     }
     /** Rewrite just a PR's body. */
     editPrBody(number, body) {
-        return this.exec(v.editPrBody(number, body));
+        return this.exec(v.editPrBody(number, body, this.target));
     }
-    /** The PR's unified diff; rejects with `CommandFailed` when gh cannot produce it. */
+    /** The PR's unified diff; rejects with the classified failure when gh cannot produce it. */
     prDiff(number) {
-        return this.exec(v.prDiff(number));
+        return this.exec(v.prDiff(number, this.target));
     }
     /** Post one conversation comment on a PR; resolves to its URL ('' if gh printed none). */
     prComment(number, body) {
-        return this.exec(v.prComment(number, body));
+        return this.exec(v.prComment(number, body, this.target));
     }
     /**
      * Create a `COMMENT` review with inline comments; resolves to the review's URL ('' if none came back).
@@ -151,15 +222,15 @@ export class AsyncGh {
      * @experimental
      */
     createReview(number, opts) {
-        return this.exec(v.createReview(number, opts));
+        return this.exec(v.createReview(number, opts, this.target));
     }
     /** Bring a PR's head branch up to date with its base. */
     prUpdateBranch(number, style = 'merge') {
-        return this.exec(v.prUpdateBranch(number, style));
+        return this.exec(v.prUpdateBranch(number, style, this.target));
     }
     /** Mark a PR ready for review (`draft: false`) or convert it to a draft (`draft: true`). */
     prSetDraft(number, draft) {
-        return this.exec(v.prSetDraft(number, draft));
+        return this.exec(v.prSetDraft(number, draft, this.target));
     }
     /**
      * Rewrite one PR conversation comment's body. `commentId` is the numeric REST id; anything else rejects with `RangeError`.
@@ -168,29 +239,41 @@ export class AsyncGh {
      */
     async issueCommentEdit(commentId, body) {
         // async, so a bad id rejects the Promise instead of throwing at the call.
-        return this.exec(v.issueCommentEdit(commentId, body));
+        return this.exec(v.issueCommentEdit(commentId, body, this.target));
     }
     /** Merge a PR; GitHub refuses when its head is no longer `opts.headSha`. */
     prMerge(number, opts) {
-        return this.exec(v.prMerge(number, opts));
+        return this.exec(v.prMerge(number, opts, this.target));
     }
     /** A PR's review threads, or null when they could not be read completely. */
     prReviewThreads(number) {
-        return this.exec(v.prReviewThreads(number));
+        return this.read(v.prReviewThreads(number, this.target));
     }
     /** Create a label (or force it to `opts`'s color/description if it exists). */
     createLabel(opts) {
-        return this.exec(v.createLabel(opts));
+        return this.exec(v.createLabel(opts, this.target));
     }
     /** Recolor and/or redescribe an existing label. */
     editLabel(name, opts) {
-        return this.exec(v.editLabel(name, opts));
+        return this.exec(v.editLabel(name, opts, this.target));
     }
     /** Swap an issue's label in a single `gh issue edit` call. */
     setIssueLabel(number, currentLabel, newLabel) {
-        return this.exec(v.setIssueLabel(number, currentLabel, newLabel));
+        return this.exec(v.setIssueLabel(number, currentLabel, newLabel, this.target));
     }
 }
+/** The open PR for `branch`, else its newest closed or merged one. */
+async function prForBranchOn(gh, branch, call) {
+    const rows = await gh.prList({
+        head: branch,
+        state: 'all',
+        limit: 20,
+        fields: v.branchPrFields(call.fields),
+        timeoutMs: call.timeoutMs,
+        signal: call.signal,
+    });
+    return v.branchPr(rows);
+}
 function sleepAsync(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/doors.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The three doors, as `@osdlc/typed-git` has them: the plain verb (checked),
+ * `gh.try.*` and `gh.soft.*`.
+ *
+ *   - **Plain / checked**: a value, or a throw. A failed `gh` throws a
+ *     `FailureError` carrying the classified `GhFailure` (its `cause` is the
+ *     `CommandFailed`), so a caller that reports it, such as `runMain`, reads
+ *     "signed out" or "rate limited" and not a bare exit; output that exited 0
+ *     but could not be read throws one of kind `unreadable`. A verb that
+ *     reads one thing (`prView`, `issueView`, `repoView`) answers `null` when
+ *     GitHub says there is no such thing: absence is an answer.
+ *   - **`try`**: the same call, with the failure returned as
+ *     `Result<T, GhFailure>`. It catches a thrown failure (a `FailureError`, or a
+ *     `CommandFailed` from `raw`-level code) and nothing else: a `RangeError` for a bad argument still throws.
+ *   - **`soft`**: the same call, with `null` for a failure. Only the queries
+ *     have a soft form; no mutation does.
+ *
+ * Both are facades over the whole client, so a new method costs nothing here.
+ */
+import { type AsyncCommandRunner, type AsyncCommandRunOptions, type CommandResult, type CommandRunner, type CommandRunOptions } from '@osdlc/command-seam';
+import { type Failure, type Result } from '@osdlc/result';
+import { type GhFailure } from './failure.ts';
+import type { GhVerb } from './verbs.ts';
+/**
+ * Read the result of running `verb` as the plain door does.
+ *
+ * A checked verb has already thrown on a non-zero exit (the runner is
+ * `runChecked`), and a probe (`installed`, `authStatus`, `api`) carries its
+ * failure in its value. A read that exited non-zero throws `CommandFailed`,
+ * unless the verb's `absent` says gh's answer was "there is no such thing",
+ * which `parse` turns into `null`. A read that exited 0 but parsed to `null`
+ * could not be read completely, and throws.
+ *
+ * @throws `FailureError` carrying the classified {@link GhFailure} for a failed run.
+ * @throws `FailureError` carrying an `unreadable` {@link GhFailure}.
+ */
+export declare function settle<T>(verb: GhVerb<T>, result: CommandResult, binary: string | undefined): T;
+/**
+ * The error the plain door throws for a failed run: a `FailureError` carrying
+ * the {@link GhFailure} that {@link classifyGhFailure} reads from it, with the
+ * `CommandFailed` as its `cause`. Anything else is returned as it is.
+ */
+export declare function ghFailureError(error: unknown): unknown;
+/** {@link runChecked}, throwing {@link ghFailureError}'s classified failure. */
+export declare function runCheckedGh(runner: CommandRunner, argv: string[], opts: CommandRunOptions): CommandResult;
+/** {@link runCheckedAsync}, rejecting with {@link ghFailureError}'s classified failure. */
+export declare function runCheckedGhAsync(runner: AsyncCommandRunner, argv: string[], opts: AsyncCommandRunOptions): Promise<CommandResult>;
+/** The methods the doors leave out: the escape hatches, pure helpers and plain properties. */
+type Triable<C> = Omit<C, 'raw' | 'rawChecked' | 'at' | 'withRepo' | 'ownerRepo' | 'try' | 'soft' | 'cwd' | 'repo' | 'hostname'>;
+/** Every synchronous client method, returning a `Result<T, GhFailure>`. */
+export type TriedSync<C> = {
+    [K in keyof Triable<C>]: Triable<C>[K] extends (...a: infer A) => infer R ? (...a: A) => Result<R, GhFailure> : never;
+};
+/** Every awaitable client method, promising a `Result<T, GhFailure>`. */
+export type TriedAsync<C> = {
+    [K in keyof Triable<C>]: Triable<C>[K] extends (...a: infer A) => Promise<infer R> ? (...a: A) => Promise<Result<R, GhFailure>> : never;
+};
+/**
+ * The queries that have a soft form. A mutation has none: swallowing the failure
+ * of a write is how a caller ends up believing it worked.
+ */
+export declare const SOFT_METHODS: readonly ["prList", "prView", "prFind", "openPrFor", "prViewSettled", "prBody", "graphql", "labelList", "issueList", "issueView", "repoList", "repoView", "searchPrs", "prReviewThreads"];
+/** The name of a method with a soft form. */
+export type SoftMethod = (typeof SOFT_METHODS)[number];
+type OrNull<R> = R extends Promise<infer U> ? Promise<U | null> : R | null;
+/** Each queried method again, returning `null` instead of throwing. One type for both clients. */
+export type Soft<C> = {
+    [K in SoftMethod & keyof C]: C[K] extends (...a: infer A) => infer R ? (...a: A) => OrNull<R> : never;
+};
+/** The failure a caught `CommandFailed` or `FailureError` stands for. */
+export declare function failureOf(error: {
+    failure: Failure;
+}): GhFailure;
+/** Wrap a synchronous client so every method returns a `Result<T, GhFailure>`. */
+export declare function triedSync<C extends object>(client: C): TriedSync<C>;
+/** Wrap an awaitable client so every method promises a `Result<T, GhFailure>`. */
+export declare function triedAsync<C extends object>(client: C): TriedAsync<C>;
+/** Wrap a synchronous client so a failed query returns `null`. */
+export declare function softSync<C extends object>(client: C): Soft<C>;
+/** Wrap an awaitable client so a failed query resolves to `null`. */
+export declare function softAsync<C extends object>(client: C): Soft<C>;
+export {};