@osdlc/typed-gh 0.5.0 → 0.7.0

package/dist/verbs.d.ts

@@ -7,21 +7,69 @@
  * 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, PullRequest } from './types.ts';
+import type { IssueRow, Label, PrSearchHit, PullRequest, Repository } from './types.ts';
 /** One `gh` invocation: what to run, and how to read what came back. */
 export interface GhVerb<T> {
     argv: string[];
     /** True for every mutation and for `prDiff` — throw on a non-zero exit instead of parsing. */
     checked: boolean;
+    /**
+     * True when the call only reads: it changes nothing on GitHub. Every query
+     * is read-only, and so is `prDiff`; every mutation is not. A caller that
+     * keeps an allowlist of safe calls can check this before running a verb.
+     */
+    readOnly: boolean;
     /** Written to the child's stdin, for a verb whose payload is too large or structured for argv. */
     input?: string | undefined;
+    /**
+     * Variables to set on the child, for a target gh takes no flag for: `GH_HOST`
+     * 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;
 }
+/**
+ * The repository and host a verb talks to. Both are optional: with no `repo`,
+ * gh uses the repository of the clone at the client's working directory, and
+ * with no `hostname`, gh's default host.
+ */
+export interface GhTarget {
+    /** `owner/name`. */
+    repo?: string | undefined;
+    /**
+     * A GitHub host: `github.com`, a GitHub Enterprise Server host such as
+     * `github.acme.com`, or a `<tenant>.ghe.com` host. Other forges are out of
+     * reach: gh speaks only GitHub's API.
+     */
+    hostname?: string | undefined;
+}
+/**
+ * Throw `RangeError` unless `target.repo` is `owner/name` and
+ * `target.hostname` is a bare host. Run by every verb that uses a target, so
+ * no text can reach gh as a flag or change the endpoint a call hits.
+ */
+export declare function checkTarget(target: GhTarget | undefined): void;
 /**
  * The cheapest useful set: enough to identify a PR and nothing more.
  *
@@ -42,6 +90,15 @@ export declare const PR_REF_FIELDS: readonly ["number", "state", "headRefName",
 export declare const PR_LIST_FIELDS: readonly ["number", "state", "title", "url", "isDraft", "baseRefName", "headRefName", "headRefOid", "isCrossRepository", "mergeable", "mergeStateStatus", "reviewDecision", "author", "labels", "mergedAt", "createdAt", "updatedAt"];
 /** {@link PR_LIST_FIELDS} plus the heavy ones a single PR can afford. */
 export declare const PR_VIEW_FIELDS: readonly ["number", "state", "title", "url", "isDraft", "baseRefName", "headRefName", "headRefOid", "isCrossRepository", "mergeable", "mergeStateStatus", "reviewDecision", "author", "labels", "mergedAt", "createdAt", "updatedAt", "body", "comments", "reviews", "statusCheckRollup"];
+/**
+ * A list query's answer: the rows, and whether `limit` cut the list short.
+ * The verb asks gh for one row more than `limit`; `truncated` is true when
+ * that row came back, and `rows` holds at most `limit`.
+ */
+export interface ListResult<T> {
+    rows: T[];
+    truncated: boolean;
+}
 /** What to narrow a listing to. Every filter is optional; none means "all open". */
 export interface PrListOptions {
     /**
@@ -53,8 +110,10 @@ export interface PrListOptions {
     /** Exact base branch filter (gh-side). */
     base?: string | undefined;
     /**
-     * Head branch filter. gh matches this as a prefix, so a caller needing an
-     * exact match filters the rows itself — {@link pickPrForBranch} does.
+     * Head branch filter, exact: `task/foo` does not match `task/foo-2`. Passed
+     * as gh's `--head`, and the rows are filtered again on `headRefName`. Two
+     * forks can share a branch name; ask for `headRepositoryOwner` to tell them
+     * apart.
      */
     head?: string | undefined;
     /** Raw `--search` query, for anything the flags do not cover. */
@@ -64,25 +123,32 @@ export interface PrListOptions {
     /** Field subset; defaults to {@link PR_LIST_FIELDS}. */
     fields?: readonly string[] | undefined;
 }
-/** `gh pr list …` — open PRs by default. */
-export declare function prList(opts?: PrListOptions): GhVerb<PullRequest[] | null>;
-/** `gh pr view <n> --json …` — one PR, with the heavy fields by default. */
-export declare function prView(number: number, fields?: readonly string[]): GhVerb<PullRequest | null>;
+/** `gh pr list …` — open PRs by default. `opts.repo` overrides the target's repo. */
+export declare function prList(opts?: PrListOptions, target?: GhTarget): GhVerb<ListResult<PullRequest> | null>;
 /**
- * Open PRs whose head *starts with* `branch` — gh's own search semantics.
+ * `gh pr view <number|branch|url> --json …` — one PR, with the heavy fields
+ * by default.
+ *
+ * A branch is the PR whose head is that branch, as gh picks it. A URL names
+ * its own repository and host, so the target is not passed with one. A
+ * string that starts with `-` throws `RangeError`.
+ */
+export declare function prView(ref: number | string, fields?: readonly string[], target?: GhTarget): GhVerb<PullRequest | null>;
+/**
+ * Open PRs whose head is exactly `branch`.
  *
  * The common shape behind "which PR is this branch?", bundling the cheap
- * field set with a small limit. Pair it with {@link pickPrForBranch}, which
- * is what turns the prefix match into an exact one.
+ * field set with a small limit. More than one row comes back only when forks
+ * share the branch name.
  */
-export declare function openPrsForBranch(branch: string, limit?: number): GhVerb<PullRequest[] | null>;
+export declare function openPrsForBranch(branch: string, limit?: number, target?: GhTarget): GhVerb<ListResult<PullRequest> | null>;
 /**
  * `gh pr view <n> --json body -q .body` — just the PR body. Null when gh
  * failed. gh's `-q` output ends with a newline that is not part of the body,
  * so every trailing `\r` and `\n` is trimmed (including any that were part of
  * the body, such as the `\r\n` of a body saved with CRLF line endings).
  */
-export declare function prBody(number: number): GhVerb<string | null>;
+export declare function prBody(number: number, target?: GhTarget): GhVerb<string | null>;
 /** One `gh api` answer: HTTP status, entity tag, and the decoded JSON body. */
 export interface ApiResponse {
     /** True iff gh exited 0 and the status is below 400 (2xx, or a 304 on a conditional GET). */
@@ -109,14 +175,65 @@ export interface ApiOptions {
     etag?: string | null | undefined;
     /** Pass `-i` and read status/ETag off the header block (the last one, if several). */
     includeHeaders?: boolean | undefined;
+    /**
+     * Fetch every page (`--paginate --slurp`). `body` is then the pages joined
+     * into one array when every page is an array, else the list of pages.
+     * Cannot be combined with `etag` or `includeHeaders`: with `-i` gh prints
+     * a header block per page. `status` is synthesized, as without `-i`.
+     */
+    paginate?: boolean | undefined;
 }
 /**
  * `gh api [-i] [-H If-None-Match: …] <endpoint>` — a GET against the REST API. `{owner}` and
- * `{repo}` placeholders in the endpoint are filled by gh from the cwd's repo.
+ * `{repo}` placeholders in the endpoint are filled from the target's repo, or by gh from the
+ * cwd's repo when the target names none.
  * Unchecked: failure is a value (`ok: false`), so a caller can tell a 304
  * from an outage.
  */
-export declare function api(endpoint: string, opts?: ApiOptions): GhVerb<ApiResponse>;
+export declare function api(endpoint: string, opts?: ApiOptions, target?: GhTarget): GhVerb<ApiResponse>;
+/**
+ * A GraphQL variable: gh sends a string with `-f` and the rest with `-F`.
+ *
+ * @experimental
+ */
+export type GraphqlVariable = string | number | boolean | null;
+/**
+ * Options for {@link graphql}.
+ *
+ * @experimental
+ */
+export interface GraphqlOptions {
+    /**
+     * Follow every page (`--paginate --slurp`). The query must take
+     * `$endCursor: String` and select `pageInfo { hasNextPage endCursor }` on
+     * the one connection it pages through; gh follows only that connection.
+     */
+    paginate?: boolean | undefined;
+}
+/**
+ * `gh api graphql -f query=… [--paginate --slurp]` — a GraphQL query.
+ *
+ * Returns each page's `data`, one entry per page (one without `paginate`),
+ * or null when the call failed, the output did not parse, or any page
+ * carries `errors` or lacks `data`: a partial answer is no answer. Read one
+ * connection across the pages with {@link nodesAt}.
+ *
+ * A string variable of exactly `{owner}` or `{repo}` is filled from the
+ * target's repo, or by gh from the clone. A mutation document throws
+ * `RangeError`: this is a read, and changes go through `raw`.
+ *
+ * @experimental
+ */
+export declare function graphql(query: string, variables?: Record<string, GraphqlVariable>, opts?: GraphqlOptions, target?: GhTarget): GhVerb<unknown[] | null>;
+/**
+ * The `nodes` of one connection, joined across {@link graphql} pages: walk
+ * `path` into each page and take its `nodes` array. Null when `pages` is
+ * null, or any page lacks the path or a `nodes` array, so a page that came
+ * back short is never read as fewer rows.
+ *
+ * @experimental
+ */
+export declare function nodesAt(pages: unknown[] | null, path: readonly string[]): unknown[] | null;
 /** `gh --version` — the install probe. True when `gh` runs. */
 export declare function installed(): GhVerb<boolean>;
 /**
@@ -127,16 +244,15 @@ export interface AuthStatus {
     ok: boolean;
     detail: string;
 }
-/** `gh auth status` — the credential probe. */
-export declare function authStatus(): GhVerb<AuthStatus>;
+/** `gh auth status [--hostname <host>]` — the credential probe, for one host when the target names it. */
+export declare function authStatus(target?: GhTarget): GhVerb<AuthStatus>;
 /**
- * `gh label list --json name,color,description` — every label on the repo.
- * `limit` defaults to 1000. `gh`'s own default is 30, which would cut off a
- * repository with more labels than that without saying so.
+ * `gh label list --json name,color,description` — every label on the repo,
+ * up to `limit` (default 1000; `gh`'s own default is 30).
  */
 export declare function labelList(opts?: {
     limit?: number | undefined;
-}): GhVerb<Label[] | null>;
+}, target?: GhTarget): GhVerb<ListResult<Label> | null>;
 /** What to narrow an issue listing to. Every filter is optional. */
 export interface IssueListOptions {
     /** Exact label filter, applied by `gh`. */
@@ -145,9 +261,53 @@ export interface IssueListOptions {
     limit?: number | undefined;
 }
 /** `gh issue list --json …` — open issues by default, optionally by label. */
-export declare function issueList(opts?: IssueListOptions): GhVerb<IssueRow[] | null>;
+export declare function issueList(opts?: IssueListOptions, target?: GhTarget): GhVerb<ListResult<IssueRow> | null>;
 /** `gh issue view <n> --json …` — one issue, same field set as {@link issueList}. */
-export declare function issueView(number: number): GhVerb<IssueRow | null>;
+export declare function issueView(number: number, target?: GhTarget): GhVerb<IssueRow | null>;
+/** The `gh repo list`/`view --json` fields a {@link Repository} reads. */
+export declare const REPO_FIELDS: readonly ["nameWithOwner", "description", "defaultBranchRef", "visibility", "isArchived", "url"];
+/** The `gh search prs --json` fields a {@link PrSearchHit} reads. */
+export declare const SEARCH_PR_FIELDS: readonly ["number", "title", "state", "url", "isDraft", "repository", "author", "labels", "createdAt", "updatedAt", "closedAt"];
+/** What to narrow a repository listing to. Every filter is optional. */
+export interface RepoListOptions {
+    /** True for archived repositories only, false to leave them out; both when absent. */
+    archived?: boolean | undefined;
+    visibility?: 'public' | 'private' | 'internal' | undefined;
+    /** The most repositories to return. Defaults to 100. */
+    limit?: number | undefined;
+    /** Field subset; defaults to {@link REPO_FIELDS}. `nameWithOwner` is always asked for. */
+    fields?: readonly string[] | undefined;
+}
+/**
+ * `gh repo list <owner> --json …` — an owner's repositories. The host comes
+ * from the target (`GH_HOST`); the target's repo is not used.
+ */
+export declare function repoList(owner: string, opts?: RepoListOptions, target?: GhTarget): GhVerb<ListResult<Repository> | null>;
+/**
+ * `gh repo view [<[host/]owner/name>] --json …` — one repository: `repo`,
+ * else the target's repo, else the clone at the client's cwd.
+ */
+export declare function repoView(repo?: string | undefined, fields?: readonly string[], target?: GhTarget): GhVerb<Repository | null>;
+/** What to narrow a pull request search to. Every filter is optional. */
+export interface SearchPrsOptions {
+    /** Only repositories this user or organization owns. */
+    owner?: string | undefined;
+    /** Only this `owner/name` repository. */
+    repo?: string | undefined;
+    /** `merged` is `--merged`; `open` and `closed` are `--state`. */
+    state?: 'open' | 'closed' | 'merged' | undefined;
+    /** The most hits to return. Defaults to 100. */
+    limit?: number | undefined;
+    /** Field subset; defaults to {@link SEARCH_PR_FIELDS}. `number` is always asked for. */
+    fields?: readonly string[] | undefined;
+}
+/**
+ * `gh search prs [flags] -- <query>` — pull requests across repositories,
+ * with GitHub's search syntax in `query` (it may start with `-`, as in
+ * `-label:bug`). The host comes from the target (`GH_HOST`); the target's
+ * repo is not used, so pass `opts.repo` or `opts.owner` to narrow.
+ */
+export declare function searchPrs(query: string, opts?: SearchPrsOptions, target?: GhTarget): GhVerb<ListResult<PrSearchHit> | null>;
 /**
  * Options for {@link createPr}. `head` is the branch to merge from and `base`
  * the branch to merge into. `draft` opens the PR as a draft.
@@ -164,18 +324,18 @@ export interface CreatePrOptions {
  * starts with `http://` or `https://`. `''` when it printed none, as
  * {@link prComment} does. A line after the URL, such as a tip, is skipped.
  */
-export declare function createPr(opts: CreatePrOptions): GhVerb<string>;
+export declare function createPr(opts: CreatePrOptions, target?: GhTarget): GhVerb<string>;
 /** `gh pr edit <n>` — retitle or rewrite the body. */
 export declare function editPr(number: number, opts: {
     title?: string | undefined;
     body?: string | undefined;
-}): GhVerb<void>;
+}, target?: GhTarget): GhVerb<void>;
 /** `gh pr edit <n> --body` — rewrite just the body. */
-export declare function editPrBody(number: number, body: string): GhVerb<void>;
+export declare function editPrBody(number: number, body: string, target?: GhTarget): GhVerb<void>;
 /** `gh pr update-branch <n> [--rebase]` — bring the head up to date with its base. */
-export declare function prUpdateBranch(number: number, style?: 'merge' | 'rebase'): GhVerb<void>;
+export declare function prUpdateBranch(number: number, style?: 'merge' | 'rebase', target?: GhTarget): GhVerb<void>;
 /** `gh pr ready <n> [--undo]` — mark a draft PR ready for review, or (with `draft`) convert it back to a draft. */
-export declare function prSetDraft(number: number, draft: boolean): GhVerb<void>;
+export declare function prSetDraft(number: number, draft: boolean, target?: GhTarget): GhVerb<void>;
 /**
  * `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<id> -f body=…` — rewrite one
  * conversation comment.
@@ -190,7 +350,7 @@ export declare function prSetDraft(number: number, draft: boolean): GhVerb<void>
  *
  * @experimental
  */
-export declare function issueCommentEdit(commentId: string, body: string): GhVerb<void>;
+export declare function issueCommentEdit(commentId: string, body: string, target?: GhTarget): GhVerb<void>;
 /** How {@link prMerge} lands the commits: `squash` into one, `merge` with a merge commit, or `rebase`. */
 export type PrMergeMethod = 'squash' | 'merge' | 'rebase';
 /**
@@ -203,7 +363,7 @@ export type PrMergeMethod = 'squash' | 'merge' | 'rebase';
 export declare function prMerge(number: number, opts: {
     method: PrMergeMethod;
     headSha: string;
-}): GhVerb<void>;
+}, target?: GhTarget): GhVerb<void>;
 /** One review thread: whether it is resolved and who spoke last. */
 export interface ReviewThread {
     isResolved: boolean;
@@ -218,7 +378,7 @@ export interface ReviewThread {
  * PR is clear to merge must read "could not tell" differently from "no
  * threads".
  */
-export declare function prReviewThreads(number: number): GhVerb<ReviewThread[] | null>;
+export declare function prReviewThreads(number: number, target?: GhTarget): GhVerb<ReviewThread[] | null>;
 /** A label to create. `color` is hex digits such as `d73a4a`. */
 export interface CreateLabelOptions {
     name: string;
@@ -230,12 +390,12 @@ export interface CreateLabelOptions {
  * `--force` makes it safe to repeat: when the label already exists, its color
  * and description are set to these instead of failing.
  */
-export declare function createLabel(opts: CreateLabelOptions): GhVerb<void>;
+export declare function createLabel(opts: CreateLabelOptions, target?: GhTarget): GhVerb<void>;
 /** `gh label edit <name>` — recolor or redescribe; omits a flag not given. */
 export declare function editLabel(name: string, opts: {
     color?: string | undefined;
     description?: string | undefined;
-}): GhVerb<void>;
+}, target?: GhTarget): GhVerb<void>;
 /**
  * `gh issue edit <n> [--remove-label <current>] --add-label <new>` — swap
  * one label for another on an issue in ONE call, so the issue is never
@@ -253,11 +413,11 @@ export declare function editLabel(name: string, opts: {
  * issue carries no prior label to remove — the `--remove-label` flag is then
  * omitted rather than passed empty.
  */
-export declare function setIssueLabel(number: number, currentLabel: string | null, newLabel: string): GhVerb<void>;
+export declare function setIssueLabel(number: number, currentLabel: string | null, newLabel: string, target?: GhTarget): GhVerb<void>;
 /** `gh pr diff <n>` — the PR's unified diff, as text. Checked: an empty diff is a value, a failed call is not. */
-export declare function prDiff(number: number): GhVerb<string>;
+export declare function prDiff(number: number, target?: GhTarget): GhVerb<string>;
 /** `gh pr comment <n> --body <body>` — post a conversation comment, returning the URL gh prints ('' if none). */
-export declare function prComment(number: number, body: string): GhVerb<string>;
+export declare function prComment(number: number, body: string, target?: GhTarget): GhVerb<string>;
 /**
  * One inline comment of a review: a line on the right (new) side of the diff.
  *
@@ -286,19 +446,28 @@ export interface CreateReviewOptions {
  * when GitHub's reply carried none). The event is always `COMMENT`: this
  * library does not offer a way to approve or request changes. Goes through
  * `gh api` with the payload on stdin, because `gh pr review` cannot attach
- * line-anchored comments; `{owner}`/`{repo}` are filled in by `gh` from the
- * client's working directory.
+ * line-anchored comments; `{owner}`/`{repo}` come from the target's repo, or
+ * are filled in by `gh` from the client's working directory.
  *
  * @experimental
  */
-export declare function createReview(number: number, opts: CreateReviewOptions): GhVerb<string>;
+export declare function createReview(number: number, opts: CreateReviewOptions, target?: GhTarget): GhVerb<string>;
 /**
- * The row whose `headRefName` exactly equals `branch`, or null.
+ * The first row whose `headRefName` exactly equals `branch`, or null.
  *
- * gh's `head:` search is a prefix match, so `task/foo` also returns
- * `task/foo-2`. Every caller that means one branch needs this filter.
+ * `prList({ head })` already filters exactly. This is for rows from anywhere
+ * else, such as a `search` query with gh's `head:` qualifier, which matches
+ * `task/foo-2` for `task/foo`.
  */
 export declare function pickPrForBranch(rows: PullRequest[] | null, branch: string): PullRequest | null;
+/**
+ * The PR a branch names, from `prList({ head, state: 'all' })` rows: the open
+ * one, or else the first row (gh lists newest first). Null when there are no
+ * rows or the call failed.
+ */
+export declare function branchPr(result: ListResult<PullRequest> | null): PullRequest | null;
+/** The field set {@link branchPr} needs, ahead of `fields`. */
+export declare function branchPrFields(fields: readonly string[]): string[];
 /**
  * True when GitHub has not finished computing this PR's mergeability.
  *
@@ -308,4 +477,3 @@ export declare function pickPrForBranch(rows: PullRequest[] | null, branch: stri
  * slow, so re-ask a few times before believing it.
  */
 export declare function needsMergeStateRetry(pr: PullRequest): boolean;
-//# sourceMappingURL=verbs.d.ts.map