@osdlc/typed-gh 0.5.0 → 0.7.0

package/dist/sync.d.ts

@@ -7,14 +7,18 @@
  * 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, IssueListOptions, PrListOptions } from './verbs.ts';
-import type { IssueRow, Label, OwnerRepo, PullRequest } from './types.ts';
+import type { ApiOptions, ApiResponse, AuthStatus, GhTarget, IssueListOptions, ListResult, PrListOptions } from './verbs.ts';
+import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts';
 /**
  * Factory of per-binary runners — the injectable subprocess seam a CLI tail
  * threads through its call graph. Production uses `spawnRunner`; tests supply
@@ -23,8 +27,19 @@ import type { IssueRow, Label, OwnerRepo, PullRequest } from './types.ts';
 export type RunnerFactory = (binary: string) => CommandRunner;
 /** Default factory: real, spawnSync-backed runners. */
 export declare const defaultRunnerFactory: RunnerFactory;
+/** What a client is built with: the runner, and the repository and host it talks to. */
+export interface GhOptions extends GhTarget {
+    runner?: CommandRunner | undefined;
+}
 /**
- * A typed gh client bound to one working directory.
+ * A typed gh client bound to one working directory, and optionally to one
+ * repository and host.
+ *
+ * With `repo`, every call names that repository (`--repo`, or the
+ * `{owner}/{repo}` of an `api` endpoint), so no clone is needed. Without it,
+ * gh uses the repository of the clone at `cwd`. With `hostname`, every call
+ * goes to that GitHub host. An invalid `repo` or `hostname` throws
+ * `RangeError`.
  *
  * Every `timeoutMs` option is a hard cap on the call. An invalid value
  * throws, as in command-seam: `RangeError` for 0, a negative value or `NaN`;
@@ -32,28 +47,68 @@ export declare const defaultRunnerFactory: RunnerFactory;
  */
 export declare class Gh {
     readonly cwd: string;
+    readonly repo: string | undefined;
+    readonly hostname: string | undefined;
+    private readonly target;
     private readonly runner;
-    constructor(cwd: string, opts?: {
-        runner?: CommandRunner | undefined;
-    });
-    /** The same client rooted at a different directory (same 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;
-    }): PullRequest[] | null;
-    /** One PR with the heavy fields, or null when gh failed. */
-    prView(number: number, opts?: {
+    }): ListResult<PullRequest>;
+    /**
+     * 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;
+        timeoutMs?: number | undefined;
+    }): PullRequest | null;
+    /**
+     * The one PR that `input` names, or null: what a person typed, such as `42`,
+     * `#42`, `owner/name#42`, a URL or a branch (read by `parsePrRef`).
+     *
+     * Digits are a PR number first; when no such PR comes back, they are tried
+     * as a branch. A branch gives its open PR, or else its newest closed or
+     * merged one, so a tool run after the merge still finds it. Fields default
+     * to {@link PR_LIST_FIELDS}.
+     */
+    prFind(input: string, opts?: {
         fields?: readonly string[] | undefined;
         timeoutMs?: number | undefined;
     }): PullRequest | null;
@@ -89,30 +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;
-    /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
+    /**
+     * 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[];
+    /** Every label on the repository (up to `opts.limit`, default 1000). Throws when gh fails. */
     labelList(opts?: {
         limit?: number | undefined;
         timeoutMs?: number | undefined;
-    }): 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;
-    }): 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). Throws when gh fails. */
+    repoList(owner: string, opts?: v.RepoListOptions & {
+        timeoutMs?: number | undefined;
+    }): 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. Throws when gh fails. */
+    searchPrs(query: string, opts?: v.SearchPrsOptions & {
+        timeoutMs?: number | undefined;
+    }): ListResult<PrSearchHit>;
     /** True iff the `gh` binary is on PATH and runs. */
     installed(): boolean;
     /**
@@ -144,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;
@@ -171,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. */
@@ -187,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,19 +7,30 @@
  * 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, settle, softSync, triedSync } from "./doors.js";
 import * as v from "./verbs.js";
-import { parseOwnerRepo } from "./repo.js";
+import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
 /** Default factory: real, spawnSync-backed runners. */
 export const defaultRunnerFactory = spawnRunner;
 /** How long to wait between merge-state retries, in milliseconds. */
 const MERGE_STATE_RETRY_DELAY_MS = 1_500;
 /**
- * A typed gh client bound to one working directory.
+ * A typed gh client bound to one working directory, and optionally to one
+ * repository and host.
+ *
+ * With `repo`, every call names that repository (`--repo`, or the
+ * `{owner}/{repo}` of an `api` endpoint), so no clone is needed. Without it,
+ * gh uses the repository of the clone at `cwd`. With `hostname`, every call
+ * goes to that GitHub host. An invalid `repo` or `hostname` throws
+ * `RangeError`.
  *
  * Every `timeoutMs` option is a hard cap on the call. An invalid value
  * throws, as in command-seam: `RangeError` for 0, a negative value or `NaN`;
@@ -27,44 +38,110 @@ const MERGE_STATE_RETRY_DELAY_MS = 1_500;
  */
 export class Gh {
     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 = resolveRunner('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 Gh(cwd, { runner: this.runner });
+        return new Gh(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 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)
+            ? runCheckedGh(this.runner, verb.argv, opts)
             : 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 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), opts.timeoutMs);
+        return this.read(v.prList(opts, this.target), opts.timeoutMs);
     }
-    /** 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.timeoutMs);
+    /**
+     * 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);
+    }
+    /**
+     * The one PR that `input` names, or null: what a person typed, such as `42`,
+     * `#42`, `owner/name#42`, a URL or a branch (read by `parsePrRef`).
+     *
+     * Digits are a PR number first; when no such PR comes back, they are tried
+     * as a branch. A branch gives its open PR, or else its newest closed or
+     * merged one, so a tool run after the merge still finds it. Fields default
+     * to {@link PR_LIST_FIELDS}.
+     */
+    prFind(input, opts = {}) {
+        const ref = parsePrRef(input);
+        if (ref === null)
+            return null;
+        const fields = opts.fields ?? v.PR_LIST_FIELDS;
+        const call = { fields, timeoutMs: opts.timeoutMs };
+        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 = 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.
@@ -82,7 +159,7 @@ export class Gh {
             limit: opts.limit ?? 5,
             fields: opts.fields ?? v.PR_REF_FIELDS,
         });
-        return v.pickPrForBranch(rows, branch);
+        return v.pickPrForBranch(rows.rows, branch);
     }
     /**
      * {@link prView}, re-asked until GitHub settles the merge state.
@@ -109,28 +186,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), 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), opts.timeoutMs);
+        return this.exec(v.api(endpoint, opts, this.target), opts.timeoutMs);
+    }
+    /**
+     * 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.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), 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), 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), opts.timeoutMs);
+        return this.exec(v.issueView(number, this.target), opts.timeoutMs);
+    }
+    /** An owner's repositories (up to `opts.limit`, default 100). Throws when gh fails. */
+    repoList(owner, opts = {}) {
+        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 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. Throws when gh fails. */
+    searchPrs(query, opts = {}) {
+        return this.read(v.searchPrs(query, opts, this.target), opts.timeoutMs);
     }
     /** True iff the `gh` binary is on PATH and runs. */
     installed() {
@@ -147,7 +245,7 @@ export class Gh {
     }
     /** Login state and what `gh auth status` printed; `authenticated()` is its `ok`. */
     authStatus() {
-        return this.exec(v.authStatus());
+        return this.exec(v.authStatus(this.target));
     }
     /**
      * True iff `gh` is installed AND authenticated — the two-step probe.
@@ -169,19 +267,19 @@ export class Gh {
     // ── mutations (checked) ───────────────────────────────────────────────────
     /** Open a PR and return 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) {
-        this.exec(v.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));
+        return this.exec(v.prDiff(number, this.target));
     }
     /** Post one conversation comment on a PR; returns 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; returns the review's URL ('' if none came back).
@@ -189,19 +287,19 @@ export class Gh {
      * @experimental
      */
     createReview(number, opts) {
-        return this.exec(v.createReview(number, opts));
+        return this.exec(v.createReview(number, opts, this.target));
     }
     /** Rewrite just a PR's body. */
     editPrBody(number, body) {
-        this.exec(v.editPrBody(number, body));
+        this.exec(v.editPrBody(number, body, this.target));
     }
     /** Bring a PR's head branch up to date with its base. */
     prUpdateBranch(number, style = 'merge') {
-        this.exec(v.prUpdateBranch(number, style));
+        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) {
-        this.exec(v.prSetDraft(number, draft));
+        this.exec(v.prSetDraft(number, draft, this.target));
     }
     /**
      * Rewrite one PR conversation comment's body. `commentId` is the numeric REST id; anything else throws `RangeError`.
@@ -209,23 +307,23 @@ export class Gh {
      * @experimental
      */
     issueCommentEdit(commentId, body) {
-        this.exec(v.issueCommentEdit(commentId, body));
+        this.exec(v.issueCommentEdit(commentId, body, this.target));
     }
     /** Merge a PR; GitHub refuses when its head is no longer `opts.headSha`. */
     prMerge(number, opts) {
-        this.exec(v.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));
+        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) {
-        this.exec(v.createLabel(opts));
+        this.exec(v.createLabel(opts, this.target));
     }
     /** Recolor and/or redescribe an existing label. */
     editLabel(name, opts) {
-        this.exec(v.editLabel(name, opts));
+        this.exec(v.editLabel(name, opts, this.target));
     }
     /**
      * Swap an issue's label: remove `currentLabel` (when given) and add
@@ -233,9 +331,20 @@ export class Gh {
      * or briefly-double-labeled intermediate state.
      */
     setIssueLabel(number, currentLabel, newLabel) {
-        this.exec(v.setIssueLabel(number, currentLabel, newLabel));
+        this.exec(v.setIssueLabel(number, currentLabel, newLabel, this.target));
     }
 }
+/** The open PR for `branch`, else its newest closed or merged one. */
+function prForBranchOn(gh, branch, call) {
+    const rows = gh.prList({
+        head: branch,
+        state: 'all',
+        limit: 20,
+        fields: v.branchPrFields(call.fields),
+        timeoutMs: call.timeoutMs,
+    });
+    return v.branchPr(rows);
+}
 /**
  * Block the calling thread. Crude on purpose: the synchronous client has no
  * event loop to await on, and the alternative — making every caller async to

package/dist/types.d.ts

@@ -149,4 +149,40 @@ export interface OwnerRepo {
     owner: string;
     repo: string;
 }
-//# sourceMappingURL=types.d.ts.map
+/** Who can see a repository. */
+export type RepositoryVisibility = 'PUBLIC' | 'PRIVATE' | 'INTERNAL' | (string & {});
+/**
+ * A repository, off `gh repo list`/`gh repo view --json`. A field not asked
+ * for comes back at its "not known" value. `nameWithOwner` is the only field
+ * without one: a row without it is dropped.
+ */
+export interface Repository {
+    /** `owner/name`. */
+    nameWithOwner: string;
+    owner: string;
+    name: string;
+    description: string;
+    /** The default branch; null when not asked for, or the repository is empty. */
+    defaultBranch: string | null;
+    visibility: RepositoryVisibility | null;
+    isArchived: boolean;
+    url: string;
+}
+/**
+ * One pull request found by `gh search prs`. Search has its own field set:
+ * it names the repository but carries no head or base branch, so this is not
+ * a {@link PullRequest}. `state` is upper-cased to match `PullRequest`.
+ */
+export interface PrSearchHit {
+    number: number;
+    title: string;
+    state: PullRequestState;
+    url: string;
+    isDraft: boolean;
+    repository: OwnerRepo | null;
+    author: Actor | null;
+    labels: Label[];
+    createdAt: string | null;
+    updatedAt: string | null;
+    closedAt: string | null;
+}