@osdlc/typed-gh 0.5.0 → 0.6.0

package/index.ts

@@ -17,9 +17,9 @@
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */
 
-export { AsyncGh, type AsyncCallOptions } from './async.ts'
+export { AsyncGh, type AsyncCallOptions, type AsyncGhOptions } from './async.ts'
 
-export { Gh, defaultRunnerFactory, type RunnerFactory } from './sync.ts'
+export { Gh, defaultRunnerFactory, type GhOptions, type RunnerFactory } from './sync.ts'
 
 export {
   api,
@@ -27,6 +27,7 @@ export {
   createPr,
   editPr,
   editPrBody,
+  graphql,
   createLabel,
   createReview,
   editLabel,
@@ -34,6 +35,7 @@ export {
   issueList,
   issueView,
   labelList,
+  nodesAt,
   openPrsForBranch,
   pickPrForBranch,
   prBody,
@@ -46,27 +48,45 @@ export {
   prReviewThreads,
   prUpdateBranch,
   prView,
+  repoList,
+  repoView,
+  searchPrs,
   setIssueLabel,
   PR_LIST_FIELDS,
   PR_REF_FIELDS,
   PR_VIEW_FIELDS,
+  REPO_FIELDS,
+  SEARCH_PR_FIELDS,
   type ApiOptions,
   type ApiResponse,
   type AuthStatus,
   type CreateLabelOptions,
   type CreatePrOptions,
   type CreateReviewOptions,
+  type GhTarget,
+  type GraphqlOptions,
+  type GraphqlVariable,
   type GhVerb,
   type IssueListOptions,
+  type ListResult,
   type PrListOptions,
   type PrMergeMethod,
+  type RepoListOptions,
   type ReviewComment,
   type ReviewThread,
+  type SearchPrsOptions,
 } from './verbs.ts'
 
 export { anyCheckFailed, normalizeAuthorLogin, parsePullRequest } from './parse.ts'
 
-export { ownerRepoSlug, parseOwnerRepo, parsePrUrl, type PullRequestRef } from './repo.ts'
+export {
+  ownerRepoSlug,
+  parseOwnerRepo,
+  parsePrRef,
+  parsePrUrl,
+  type PrRef,
+  type PullRequestRef,
+} from './repo.ts'
 
 export type {
   Actor,
@@ -79,7 +99,10 @@ export type {
   MergeStateStatus,
   OwnerRepo,
   PullRequest,
+  PrSearchHit,
   PullRequestState,
+  Repository,
+  RepositoryVisibility,
   Review,
   ReviewDecision,
   ReviewState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A typed GitHub client for TypeScript over the gh CLI. A total PullRequest/Review/CheckRun model, pure argv builders and parsers, and a tri-modal client — queries return parsed values, mutations throw, raw() is the escape hatch. Uses gh's own credentials; reads no token.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
     "LICENSE-APACHE"
   ],
   "dependencies": {
-    "@osdlc/command-seam": "^0.8.0",
-    "@osdlc/typed-git": "^0.5.2"
+    "@osdlc/typed-git": "^0.5.3",
+    "@osdlc/command-seam": "^0.8.0"
   },
   "engines": {
     "node": ">=22"

package/parse.ts

@@ -25,7 +25,9 @@ import type {
   Comment,
   Label,
   MergeableState,
+  PrSearchHit,
   PullRequest,
+  Repository,
   Review,
   ReviewDecision,
 } from './types.ts'
@@ -250,3 +252,51 @@ export function parsePullRequest(raw: unknown): PullRequest | null {
     updatedAt: strOrNull(raw['updatedAt'] ?? raw['updated_at']),
   }
 }
+
+// ── repositories and search ─────────────────────────────────────────────────
+
+/** A `gh repo list`/`view --json` row as a {@link Repository}, or null without `nameWithOwner`. */
+export function parseRepository(raw: unknown): Repository | null {
+  if (!isRecord(raw)) return null
+  const nameWithOwner = str(raw['nameWithOwner'])
+  const slash = nameWithOwner.indexOf('/')
+  if (slash <= 0 || slash === nameWithOwner.length - 1) return null
+  const branch = raw['defaultBranchRef']
+  return {
+    nameWithOwner,
+    owner: nameWithOwner.slice(0, slash),
+    name: nameWithOwner.slice(slash + 1),
+    description: str(raw['description']),
+    defaultBranch: isRecord(branch) ? strOrNull(branch['name']) : null,
+    visibility: strOrNull(raw['visibility']),
+    isArchived: bool(raw['isArchived']),
+    url: str(raw['url']),
+  }
+}
+
+/** A `gh search prs --json` row as a {@link PrSearchHit}, or null without a `number`. */
+export function parsePrSearchHit(raw: unknown): PrSearchHit | null {
+  if (!isRecord(raw)) return null
+  const number = raw['number']
+  if (typeof number !== 'number') return null
+  const repo = raw['repository']
+  const slug = isRecord(repo) ? str(repo['nameWithOwner']) : ''
+  const slash = slug.indexOf('/')
+  return {
+    number,
+    title: str(raw['title']),
+    // Search answers in lower case; `PullRequest.state` is upper case.
+    state: str(raw['state']).toUpperCase(),
+    url: str(raw['url']),
+    isDraft: bool(raw['isDraft']),
+    repository:
+      slash > 0 && slash < slug.length - 1
+        ? { owner: slug.slice(0, slash), repo: slug.slice(slash + 1) }
+        : null,
+    author: parseActor(raw['author']),
+    labels: parseLabels(raw['labels']),
+    createdAt: strOrNull(raw['createdAt']),
+    updatedAt: strOrNull(raw['updatedAt']),
+    closedAt: strOrNull(raw['closedAt']),
+  }
+}

package/repo.ts

@@ -29,31 +29,105 @@ export function ownerRepoSlug(r: OwnerRepo): string {
   return `${r.owner}/${r.repo}`
 }
 
-/** A pull request coordinate: the repository and the PR's number within it. */
+/** A pull request coordinate: the host, the repository and the PR's number within it. */
 export interface PullRequestRef extends OwnerRepo {
+  /** The GitHub host, lower-cased: `github.com`, or an Enterprise host. */
+  hostname: string
   number: number
 }
 
 /**
- * The `{owner, repo, number}` a GitHub pull-request URL names, or null when
- * `url` is not one.
+ * The `{hostname, owner, repo, number}` a GitHub pull-request URL names, or
+ * null when `url` is not one.
  *
- * Accepts `https://github.com/<owner>/<repo>/pull/<n>` with or without a
- * scheme, a `www.` prefix, a trailing slash, a sub-page (`/files`,
- * `/commits`), a query string or a fragment — every shape a browser's address
- * bar hands over. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
+ * Accepts `https://<host>/<owner>/<repo>/pull/<n>` with or without a scheme,
+ * a trailing slash, a sub-page (`/files`, `/commits`), a query string or a
+ * fragment — every shape a browser's address bar hands over. The host is
+ * `github.com` (a `www.` prefix is dropped) or a GitHub Enterprise host such
+ * as `github.acme.com` or `acme.ghe.com`; without a scheme the host must
+ * contain a dot. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
  * as part of the project path.
- *
- * GitHub.com only. A GitHub Enterprise host is a different coordinate space
- * (the `gh` CLI needs `--hostname`), so it is not silently accepted.
  */
 export function parsePrUrl(url: string): PullRequestRef | null {
   const m =
-    /^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)(?:[/?#].*)?$/i.exec(
+    /^(?:(https?:)\/\/)?([a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::\d+)?)\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)(?:[/?#].*)?$/i.exec(
       url.trim(),
     )
   if (m === null) return null
-  const number = Number(m[3])
+  const host = m[2]!.toLowerCase()
+  if (m[1] === undefined && !host.includes('.')) return null
+  const number = Number(m[5])
   if (!Number.isSafeInteger(number) || number <= 0) return null
-  return { owner: m[1]!, repo: m[2]!.replace(/\.git$/, ''), number }
+  return {
+    hostname: host === 'www.github.com' ? 'github.com' : host,
+    owner: m[3]!,
+    repo: m[4]!.replace(/\.git$/, ''),
+    number,
+  }
+}
+
+/**
+ * What a person typed to name a pull request, read by {@link parsePrRef}.
+ *
+ * - `number`: `42`, `#42`, or `owner/name#42` (then `repo` is set). For bare
+ *   digits, `orBranch` holds the same text, since a branch can be named `42`.
+ * - `url`: a pull request URL, with what {@link parsePrUrl} read from it.
+ * - `branch`: any other text that is a valid branch name.
+ */
+export type PrRef =
+  | { kind: 'number'; number: number; repo: OwnerRepo | null; orBranch: string | null }
+  | ({ kind: 'url'; url: string } & PullRequestRef)
+  | { kind: 'branch'; name: string }
+
+/**
+ * Read what a person typed to name a pull request: a number, `#42`,
+ * `owner/name#42`, a URL, or a branch name. Null when it is none of these.
+ *
+ * Pure: it starts no process. Digits are read as a number first, the way
+ * `gh pr view 42` reads them; `orBranch` keeps the branch reading. The
+ * clients' `prFind` tries both.
+ */
+export function parsePrRef(input: string): PrRef | null {
+  const text = input.trim()
+  const digits = /^(#?)(\d+)$/.exec(text)
+  if (digits !== null) {
+    const number = Number(digits[2])
+    if (Number.isSafeInteger(number) && number > 0) {
+      return { kind: 'number', number, repo: null, orBranch: digits[1] === '' ? text : null }
+    }
+  }
+  const qualified = /^([^/\s#]+)\/([^/\s#]+)#(\d+)$/.exec(text)
+  if (qualified !== null) {
+    const number = Number(qualified[3])
+    if (!Number.isSafeInteger(number) || number <= 0) return null
+    if (!isRepoSlug(`${qualified[1]}/${qualified[2]}`)) return null
+    return {
+      kind: 'number',
+      number,
+      repo: { owner: qualified[1]!, repo: qualified[2]! },
+      orBranch: null,
+    }
+  }
+  const url = parsePrUrl(text)
+  if (url !== null) return { kind: 'url', url: text, ...url }
+  return isBranchName(text) ? { kind: 'branch', name: text } : null
+}
+
+/** True for `owner/name` as GitHub spells it. */
+export function isRepoSlug(text: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9_.][A-Za-z0-9_.-]*$/.test(text)
+}
+
+/**
+ * True when `name` is a branch name git would accept (`git check-ref-format
+ * --branch`), and does not start with `-`, so it cannot read as a flag.
+ */
+function isBranchName(name: string): boolean {
+  if (name === '' || name === '@' || name.startsWith('-') || name.startsWith('/')) return false
+  if (name.endsWith('/') || name.endsWith('.')) return false
+  // Control characters, space, and the characters git reserves.
+  // oxlint-disable-next-line no-control-regex
+  if (/[\x00-\x20\x7f~^:?*[\\]/.test(name)) return false
+  if (name.includes('..') || name.includes('@{') || name.includes('//')) return false
+  return name.split('/').every((part) => !part.startsWith('.') && !part.endsWith('.lock'))
 }

package/sync.ts

@@ -26,12 +26,14 @@ import type {
   ApiOptions,
   ApiResponse,
   AuthStatus,
+  GhTarget,
   GhVerb,
   IssueListOptions,
+  ListResult,
   PrListOptions,
 } from './verbs.ts'
-import { parseOwnerRepo } from './repo.ts'
-import type { IssueRow, Label, OwnerRepo, PullRequest } from './types.ts'
+import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from './repo.ts'
+import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts'
 
 /**
  * Factory of per-binary runners — the injectable subprocess seam a CLI tail
@@ -46,8 +48,20 @@ export const defaultRunnerFactory: RunnerFactory = spawnRunner
 /** How long to wait between merge-state retries, in milliseconds. */
 const MERGE_STATE_RETRY_DELAY_MS = 1_500
 
+/** 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`;
@@ -55,16 +69,28 @@ const MERGE_STATE_RETRY_DELAY_MS = 1_500
  */
 export class Gh {
   readonly cwd: string
+  readonly repo: string | undefined
+  readonly hostname: string | undefined
+  private readonly target: GhTarget
   private readonly runner: CommandRunner
 
-  constructor(cwd: string, opts: { runner?: CommandRunner | undefined } = {}) {
+  constructor(cwd: string, opts: GhOptions = {}) {
+    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: string): Gh {
-    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: string): Gh {
+    return new Gh(this.cwd, { runner: this.runner, repo, hostname: this.hostname })
   }
 
   // ── escape hatches ────────────────────────────────────────────────────────
@@ -83,6 +109,7 @@ export class Gh {
   private exec<T>(verb: GhVerb<T>, timeoutMs?: number | undefined): T {
     const opts: CommandRunOptions = { 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)
@@ -93,16 +120,45 @@ export class Gh {
   // ── queries ───────────────────────────────────────────────────────────────
 
   /** Pull requests matching `opts`, or null when gh failed. */
-  prList(opts: PrListOptions & { timeoutMs?: number | undefined } = {}): PullRequest[] | null {
-    return this.exec(v.prList(opts), opts.timeoutMs)
+  prList(
+    opts: PrListOptions & { timeoutMs?: number | undefined } = {},
+  ): ListResult<PullRequest> | null {
+    return this.exec(v.prList(opts, this.target), opts.timeoutMs)
   }
 
-  /** One PR with the heavy fields, or null when gh failed. */
+  /**
+   * One PR by number, branch or URL, with the heavy fields; null when gh
+   * failed or there is no such PR.
+   */
   prView(
-    number: number,
+    ref: number | string,
+    opts: { fields?: readonly string[] | undefined; timeoutMs?: number | undefined } = {},
+  ): PullRequest | null {
+    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: string,
     opts: { fields?: readonly string[] | undefined; timeoutMs?: number | undefined } = {},
   ): PullRequest | null {
-    return this.exec(v.prView(number, opts.fields ?? v.PR_VIEW_FIELDS), opts.timeoutMs)
+    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)
   }
 
   /**
@@ -124,7 +180,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 ?? null, branch)
   }
 
   /**
@@ -161,7 +217,7 @@ export class Gh {
 
   /** A PR's body text, or null when gh failed. */
   prBody(number: number, opts: { timeoutMs?: number | undefined } = {}): string | null {
-    return this.exec(v.prBody(number), opts.timeoutMs)
+    return this.exec(v.prBody(number, this.target), opts.timeoutMs)
   }
 
   /**
@@ -169,24 +225,64 @@ export class Gh {
    * returned {@link ApiResponse}.
    */
   api(endpoint: string, opts: ApiOptions & { timeoutMs?: number | undefined } = {}): ApiResponse {
-    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`, or null on a failed or partial
+   * result. See the `graphql` verb.
+   *
+   * @experimental
+   */
+  graphql(
+    query: string,
+    variables: Record<string, v.GraphqlVariable> = {},
+    opts: v.GraphqlOptions & { timeoutMs?: number | undefined } = {},
+  ): unknown[] | null {
+    return this.exec(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. */
   labelList(
     opts: { limit?: number | undefined; timeoutMs?: number | undefined } = {},
-  ): Label[] | null {
-    return this.exec(v.labelList(opts), opts.timeoutMs)
+  ): ListResult<Label> | null {
+    return this.exec(v.labelList(opts, this.target), opts.timeoutMs)
   }
 
   /** Issues matching `opts` (open by default, up to 200), or null when gh failed. */
-  issueList(opts: IssueListOptions & { timeoutMs?: number | undefined } = {}): IssueRow[] | null {
-    return this.exec(v.issueList(opts), opts.timeoutMs)
+  issueList(
+    opts: IssueListOptions & { timeoutMs?: number | undefined } = {},
+  ): ListResult<IssueRow> | null {
+    return this.exec(v.issueList(opts, this.target), opts.timeoutMs)
   }
 
   /** One issue with its labels, or null when gh failed. */
   issueView(number: number, opts: { timeoutMs?: number | undefined } = {}): IssueRow | null {
-    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), or null when gh failed. */
+  repoList(
+    owner: string,
+    opts: v.RepoListOptions & { timeoutMs?: number | undefined } = {},
+  ): ListResult<Repository> | null {
+    return this.exec(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. */
+  repoView(
+    repo?: string | undefined,
+    opts: { fields?: readonly string[] | undefined; timeoutMs?: number | undefined } = {},
+  ): Repository | null {
+    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. */
+  searchPrs(
+    query: string,
+    opts: v.SearchPrsOptions & { timeoutMs?: number | undefined } = {},
+  ): ListResult<PrSearchHit> | null {
+    return this.exec(v.searchPrs(query, opts, this.target), opts.timeoutMs)
   }
 
   /** True iff the `gh` binary is on PATH and runs. */
@@ -206,7 +302,7 @@ export class Gh {
 
   /** Login state and what `gh auth status` printed; `authenticated()` is its `ok`. */
   authStatus(): AuthStatus {
-    return this.exec(v.authStatus())
+    return this.exec(v.authStatus(this.target))
   }
 
   /**
@@ -232,22 +328,22 @@ export class Gh {
 
   /** Open a PR and return its URL ('' if gh printed none). */
   createPr(opts: v.CreatePrOptions): string {
-    return this.exec(v.createPr(opts))
+    return this.exec(v.createPr(opts, this.target))
   }
 
   /** Retitle or rewrite a PR body. */
   editPr(number: number, opts: { title?: string | undefined; body?: string | undefined }): void {
-    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. */
   prDiff(number: number): string {
-    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: number, body: string): string {
-    return this.exec(v.prComment(number, body))
+    return this.exec(v.prComment(number, body, this.target))
   }
 
   /**
@@ -256,22 +352,22 @@ export class Gh {
    * @experimental
    */
   createReview(number: number, opts: v.CreateReviewOptions): string {
-    return this.exec(v.createReview(number, opts))
+    return this.exec(v.createReview(number, opts, this.target))
   }
 
   /** Rewrite just a PR's body. */
   editPrBody(number: number, body: string): void {
-    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: number, style: 'merge' | 'rebase' = 'merge'): void {
-    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: number, draft: boolean): void {
-    this.exec(v.prSetDraft(number, draft))
+    this.exec(v.prSetDraft(number, draft, this.target))
   }
 
   /**
@@ -280,22 +376,22 @@ export class Gh {
    * @experimental
    */
   issueCommentEdit(commentId: string, body: string): void {
-    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: number, opts: { method: v.PrMergeMethod; headSha: string }): void {
-    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. */
   prReviewThreads(number: number): v.ReviewThread[] | null {
-    return this.exec(v.prReviewThreads(number))
+    return this.exec(v.prReviewThreads(number, this.target))
   }
 
   /** Create a label (or force it to `opts`'s color/description if it already exists). */
   createLabel(opts: v.CreateLabelOptions): void {
-    this.exec(v.createLabel(opts))
+    this.exec(v.createLabel(opts, this.target))
   }
 
   /** Recolor and/or redescribe an existing label. */
@@ -303,7 +399,7 @@ export class Gh {
     name: string,
     opts: { color?: string | undefined; description?: string | undefined },
   ): void {
-    this.exec(v.editLabel(name, opts))
+    this.exec(v.editLabel(name, opts, this.target))
   }
 
   /**
@@ -312,10 +408,26 @@ export class Gh {
    * or briefly-double-labeled intermediate state.
    */
   setIssueLabel(number: number, currentLabel: string | null, newLabel: string): void {
-    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: Gh,
+  branch: string,
+  call: { fields: readonly string[]; timeoutMs?: number | undefined },
+): PullRequest | null {
+  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/types.ts

@@ -184,3 +184,43 @@ export interface OwnerRepo {
   owner: string
   repo: string
 }
+
+/** 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
+}