@osdlc/typed-gh 0.9.5 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @osdlc/typed-gh
 
+## 0.11.1
+
+### Patch Changes
+
+- 272da7a: A list that goes through GitHub search reports `truncated: true` when 1000 rows come back. Search returns at most 1000 results whatever the `limit`, so before, a `limit` of 1000 or more read as complete (`truncated: false`) while more matched. gh uses search for `searchPrs`, for `prList` with a non-empty `search` or an `author`, and for `issueList` with a `label`. A list that does not search is unchanged. `searchPrs` now asks gh for at most 1000 rows: a `limit` of 1000 or more used to fail, because gh refuses a larger search limit.
+
+## 0.11.0
+
+### Minor Changes
+
+- da5e6a3: `parseOwnerRepo` is now `@osdlc/typed-git`'s `parseRemoteRepo` without the host. Behaviour change: a remote that `parseGitUrl` recognises but names no owner and repository for is read host-agnostically (`host/owner/repo`) instead of answering null; every other remote reads as before.
+  `settle`, `runCheckedGh`, `runCheckedGhAsync`, `gh.try`, `gh.soft`, `classifyGhFailure` and the leading-dash guard now use `@osdlc/command-seam`'s `runFailed`, `tryMethods`, `methodFacade`, `classifyFailed` and `notAnOption`, with no change a caller sees: the same failures, and the same `RangeError` and message for an argument that starts with `-`. `repoView` and every `--repo` verb build `[host/]owner/name` through one helper.
+
+### Patch Changes
+
+- Updated dependencies [da5e6a3]
+- Updated dependencies [da5e6a3]
+  - @osdlc/command-seam@0.14.0
+  - @osdlc/typed-git@0.10.0
+
+## 0.10.0
+
+### Minor Changes
+
+- b835ae4: Behaviour change: output that the runner cut short (`outputIncomplete`, at the output cap or a timeout) now fails as `CommandFailed` for every verb but a probe, and in `runCheckedGh`/`runCheckedGhAsync`, instead of being parsed as whole. Behaviour change: every `AsyncGh` method that builds a verb now rejects its Promise on a bad argument (a verb's `RangeError`) instead of throwing at the call site.
+  `parseOwnerRepo` now reads a GitHub Enterprise remote (a host `parseGitUrl` does not know) through `parseRemoteUrl` instead of answering null. `graphql` refuses a document holding a mutation or subscription anywhere (after a fragment, a leading `,`, or a second operation), and a variable named `query` or `operationName`. `prView` passes a scheme-less PR URL (`github.com/o/r/pull/7`) to gh with `https://`, so gh no longer takes it for a branch name. `repoView` treats a hostname of `''` as not set. `createLabel` and `editLabel` refuse a name that starts with `-`. `openPrFor` takes `timeoutMs`.
+
+### Patch Changes
+
+- Updated dependencies [b835ae4]
+- Updated dependencies [b835ae4]
+- Updated dependencies [fdef74f]
+  - @osdlc/command-seam@0.13.0
+  - @osdlc/typed-git@0.9.0
+
+## 0.9.6
+
+### Patch Changes
+
+- 3d6d087: Document that a `Repository`'s `owner` and `name`, and a `PrSearchHit`'s `repository`, come back in GitHub's casing, not as the caller wrote them. The `Repository` and `PrSearchHit` type docs, the `repoList` and `repoView` doc comments and the README say so.
+- f013f38: The default runners now find `git` and `gh` on absolute `PATH` entries only, and spawn the absolute path found. Before, a bare `git` or `gh` was spawned by name with the child's `cwd` set to the checkout, so a file of that name in the checkout could run in place of the real binary: on Windows, where a bare name is searched in `cwd` first, and on every platform through a relative or empty `PATH` entry. A binary that is not found on an absolute entry fails as a missing binary (`not-installed`). typed-gh's `defaultRunnerFactory` does the same lookup. An injected runner is unchanged.
+- Updated dependencies [f013f38]
+- Updated dependencies [f013f38]
+  - @osdlc/command-seam@0.12.1
+  - @osdlc/typed-git@0.8.2
+
 ## 0.9.5
 
 ### Patch Changes

package/README.md

@@ -116,8 +116,9 @@ stderr and stdout, as the classifier does.
 
 Setup checks return their failure as a value. `installed()`, `authenticated()`,
 `authStatus()`, `ready()` and `api()` return their failure as part of their
-value, in all three call styles. For them, "gh is not installed" is the answer
-to the question they ask.
+value, from the plain method and from `try`. They have no soft form:
+`gh.soft.api(...)` throws a `TypeError`. For them, "gh is not installed" is the
+answer to the question they ask.
 
 ```ts
 import { describe } from '@osdlc/result'
@@ -169,6 +170,13 @@ if (page.truncated) console.warn('more than 50 open PRs; raise the limit')
 `prList`, `issueList`, `labelList`, `repoList` and `searchPrs` all work this
 way. A `limit` that is not a positive integer throws `RangeError`.
 
+GitHub search returns at most 1000 results, whatever the `limit`. gh uses
+search for `searchPrs`, for `prList` with a non-empty `search` or an `author`,
+and for `issueList` with a `label`. Those report `truncated: true` when 1000
+rows come back: there may be more that search would not return. Narrow the
+query to see them. `searchPrs` asks gh for at most 1000 rows, since gh refuses
+a larger search limit.
+
 ## A repository without a clone
 
 By default a client talks to the repository of the clone at its directory.
@@ -375,7 +383,8 @@ const repos = await runVerbAsync(repoList('acme', {}, { hostname: 'ghe.example.c
 })
 ```
 
-They take a `CommandRunner`. A plain `(binary, argv, opts) => result` function is wrapped as
+`runVerb` takes a `CommandRunner` and `runVerbAsync` an `AsyncCommandRunner`. A plain
+`(binary, argv, opts) => result` function is not a runner; wrap it yourself as
 `{ run: (argv, opts) => fn('gh', argv, opts) }`.
 
 ## `AsyncGh`
@@ -384,7 +393,8 @@ The awaitable form of `Gh`, with the same methods, for code that runs many calls
 not block the event loop. It has the same three call styles, as Promises. The plain method rejects
 with the classified failure. `try` resolves to a `Result<T, GhFailure>`. `soft` resolves `null` for
 a failed query. `raw` and `rawChecked` run any `gh` call. Both clients use the same verb table, so
-they cannot drift apart. It takes an `AsyncCommandRunner` and defaults to `spawnRunnerAsync("gh")`.
+they cannot drift apart. It takes an `AsyncCommandRunner` and defaults to
+`spawnRunnerAsync("gh", { absolutePathOnly: true })`.
 
 ```ts
 import { AsyncGh } from '@osdlc/typed-gh'
@@ -439,7 +449,7 @@ const prs = nodesAt(pages, ['repository', 'pullRequests'])
 ```
 
 With `paginate`, the query must take `$endCursor` and page one connection. gh follows only that
-one. `graphql` refuses a mutation with `RangeError`. Send one through `raw`.
+one. `graphql` refuses a document holding a mutation or subscription with `RangeError`. Send one through `raw`.
 
 ## Repositories and search
 
@@ -450,9 +460,14 @@ const hits: ListResult<PrSearchHit> = gh.searchPrs('TICKET-123', { owner: 'acme'
 ```
 
 A `Repository` carries `nameWithOwner`, `owner`, `name`, `description`, `defaultBranch`,
-`visibility`, `isArchived` and `url`. `gh search prs` has its own field set. A `PrSearchHit` names
-its `repository` but has no head or base branch, so it is not a `PullRequest`. Its `state` is
-upper-cased to match. The query takes GitHub's search syntax and may start with `-`.
+`visibility`, `isArchived` and `url`. `owner` and `name` are cut from `nameWithOwner`, so they
+come back in GitHub's casing, not as you wrote them: `repoList('ACME')` gives `owner: 'acme'` when
+the account is `acme`, and `repoView` works the same way. To build paths that match your own
+config, use your own value.
+
+`gh search prs` has its own field set. A `PrSearchHit` names its `repository`, also in GitHub's
+casing, but has no head or base branch, so it is not a `PullRequest`. Its `state` is upper-cased to
+match. The query takes GitHub's search syntax and may start with `-`.
 
 ## Passing your own runner
 
@@ -469,7 +484,9 @@ new Gh('/repo', { runner: empty }).prList() // { rows: [], truncated: false }
 This package re-exports `CommandFailed` and the runner and result types (`CommandRunner`,
 `AsyncCommandRunner`, `CommandResult`, `CommandRunOptions`), since they appear in its signatures.
 Import the runners themselves, such as `spawnRunner` and `spawnRunnerAsync`, from
-`@osdlc/command-seam`.
+`@osdlc/command-seam`. The default runners find `gh` on absolute `PATH` entries only, so a file
+named `gh` in the working directory cannot run in its place. Pass `{ absolutePathOnly: true }` when
+you build a real runner yourself.
 
 ## API
 
@@ -539,7 +556,9 @@ Each verb takes an optional `GhTarget` last. Each client method has a verb of th
 - `parsePullRequest`: reads a `gh --json` payload into a `PullRequest`, or `null`.
 - `anyCheckFailed`: true if any check in a list failed.
 - `normalizeAuthorLogin`: drops a `[bot]` suffix from a login.
-- `parseOwnerRepo`: reads a remote URL into `{ owner, repo }`, or `null`.
+- `parseOwnerRepo`: reads a remote URL into `{ owner, repo }`, or `null`. It is
+  `@osdlc/typed-git`'s `parseRemoteRepo` without the host, so any host's remote reads, not only
+  GitHub's. Use `parseRemoteRepo` when you need the host too.
 - `ownerRepoSlug`: writes `{ owner, repo }` as `owner/repo`.
 - `parsePrUrl`: reads a pull request URL on any GitHub host into its host, owner, repository and
   number, or `null`.

package/SECURITY.md

@@ -42,9 +42,10 @@ not intend are in scope.
   value into a REST path. Pass endpoints you built, not text from a user.
   `issueCommentEdit(commentId)` accepts only digits and throws `RangeError`
   for anything else, so its id cannot change the path.
-- **`gh` chooses the repository.** It reads the working directory's git
-  remotes, or `GH_REPO`. A checkout whose `.git/config` points `origin` at
-  another repository sends mutations there. `ownerRepo` only parses a URL you
+- **Without a `repo` option, `gh` chooses the repository.** It reads the
+  working directory's git remotes, or `GH_REPO`. A checkout whose
+  `.git/config` points `origin` at another repository sends mutations there.
+  Pass `repo` (and `hostname`) to name the target in argv. `ownerRepo` only parses a URL you
   give it. It does not check where `gh` will act.
 - **`raw` and `rawChecked` run any `gh` command.** They have no allow list.
 - **`CommandFailed` carries the full argv.** Its message quotes the arguments,

package/dist/async.d.ts

@@ -106,9 +106,15 @@ export declare class AsyncGh {
     issueList(opts?: IssueListOptions & AsyncCallOptions): Promise<ListResult<IssueRow>>;
     /** One issue with its labels, or 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`. */
+    /**
+     * An owner's repositories. Rejects when gh fails. Each row's `owner` is in
+     * GitHub's casing, not as passed. See `Gh.repoList`.
+     */
     repoList(owner: string, opts?: v.RepoListOptions & AsyncCallOptions): Promise<ListResult<Repository>>;
-    /** One repository, or null when there is no such repository. See `Gh.repoView`. */
+    /**
+     * One repository, or null when there is no such repository. `owner` and
+     * `name` are in GitHub's casing, not as passed. See `Gh.repoView`.
+     */
     repoView(repo?: string | undefined, opts?: {
         fields?: readonly string[] | undefined;
     } & AsyncCallOptions): Promise<Repository | null>;

package/dist/async.js

@@ -10,7 +10,7 @@
  * two cannot differ on argv or parsing. Use it where the sync client would
  * block the event loop, such as many per-PR queries at once.
  */
-import { resolveRunnerAsync, } from '@osdlc/command-seam';
+import { spawnRunnerAsync } from '@osdlc/command-seam';
 import { runCheckedGhAsync, softAsync, triedAsync } from "./doors.js";
 import { runVerbAsync } from "./run.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
@@ -35,7 +35,7 @@ export class AsyncGh {
         this.repo = opts.repo;
         this.hostname = opts.hostname;
         this.target = { repo: opts.repo, hostname: opts.hostname };
-        this.runner = resolveRunnerAsync('gh', opts.runner);
+        this.runner = opts.runner ?? spawnRunnerAsync('gh', { absolutePathOnly: true });
     }
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd) {
@@ -79,12 +79,15 @@ export class AsyncGh {
         return (await this.exec(verb, call));
     }
     // ── queries ───────────────────────────────────────────────────────────────
+    //
+    // Every method that builds a verb is `async`, so a bad argument (a verb's
+    // RangeError) rejects the Promise instead of throwing at the call site.
     /** Pull requests matching `opts`. Rejects when gh fails. `soft.prList` resolves null instead. */
-    prList(opts = {}) {
+    async prList(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 = {}) {
+    async 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`. */
@@ -127,11 +130,11 @@ export class AsyncGh {
         return last;
     }
     /** A PR's body text. Rejects when gh fails. */
-    prBody(number, opts = {}) {
+    async 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 = {}) {
+    async api(endpoint, opts = {}) {
         return this.exec(v.api(endpoint, opts, this.target), opts);
     }
     /**
@@ -139,35 +142,41 @@ export class AsyncGh {
      *
      * @experimental
      */
-    graphql(query, variables = {}, opts = {}) {
+    async 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 = {}) {
+    async labelList(opts = {}) {
         return this.read(v.labelList(opts, this.target), opts);
     }
     /** Issues matching `opts`. Rejects when gh fails. */
-    issueList(opts = {}) {
+    async issueList(opts = {}) {
         return this.read(v.issueList(opts, this.target), opts);
     }
     /** One issue with its labels, or null when there is no such issue. */
-    issueView(number, opts = {}) {
+    async 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 = {}) {
+    /**
+     * An owner's repositories. Rejects when gh fails. Each row's `owner` is in
+     * GitHub's casing, not as passed. See `Gh.repoList`.
+     */
+    async repoList(owner, opts = {}) {
         return this.read(v.repoList(owner, opts, this.target), opts);
     }
-    /** One repository, or null when there is no such repository. See `Gh.repoView`. */
-    repoView(repo, opts = {}) {
+    /**
+     * One repository, or null when there is no such repository. `owner` and
+     * `name` are in GitHub's casing, not as passed. See `Gh.repoView`.
+     */
+    async 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 = {}) {
+    async searchPrs(query, opts = {}) {
         return this.read(v.searchPrs(query, opts, this.target), opts);
     }
     /** True iff the `gh` binary is on PATH and runs. */
-    installed() {
+    async installed() {
         return this.exec(v.installed());
     }
     /** True iff `gh` holds credentials. */
@@ -175,7 +184,7 @@ export class AsyncGh {
         return (await this.authStatus()).ok;
     }
     /** Login state and what `gh auth status` printed. */
-    authStatus() {
+    async authStatus() {
         return this.exec(v.authStatus(this.target));
     }
     /** True iff `gh` is installed and authenticated. Skips the auth check when `gh` is not installed. */
@@ -191,23 +200,23 @@ export class AsyncGh {
     }
     // ── mutations (checked) ───────────────────────────────────────────────────
     /** Open a PR and resolve to its URL ('' if gh printed none). */
-    createPr(opts) {
+    async createPr(opts) {
         return this.exec(v.createPr(opts, this.target));
     }
     /** Retitle or rewrite a PR body. */
-    editPr(number, opts) {
+    async editPr(number, opts) {
         return this.exec(v.editPr(number, opts, this.target));
     }
     /** Rewrite just a PR's body. */
-    editPrBody(number, body) {
+    async editPrBody(number, body) {
         return this.exec(v.editPrBody(number, body, this.target));
     }
     /** The PR's unified diff. Rejects with the classified failure when gh cannot produce it. */
-    prDiff(number) {
+    async 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) {
+    async prComment(number, body) {
         return this.exec(v.prComment(number, body, this.target));
     }
     /**
@@ -215,15 +224,15 @@ export class AsyncGh {
      *
      * @experimental
      */
-    createReview(number, opts) {
+    async 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') {
+    async prUpdateBranch(number, style = 'merge') {
         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) {
+    async prSetDraft(number, draft) {
         return this.exec(v.prSetDraft(number, draft, this.target));
     }
     /**
@@ -232,27 +241,26 @@ export class AsyncGh {
      * @experimental
      */
     async issueCommentEdit(commentId, body) {
-        // async, so a bad id rejects the Promise instead of throwing at the call site.
         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) {
+    async prMerge(number, opts) {
         return this.exec(v.prMerge(number, opts, this.target));
     }
     /** A PR's review threads. Rejects when they could not be read completely. `soft.prReviewThreads` resolves null instead. */
-    prReviewThreads(number) {
+    async 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) {
+    async createLabel(opts) {
         return this.exec(v.createLabel(opts, this.target));
     }
     /** Recolor and/or redescribe an existing label. */
-    editLabel(name, opts) {
+    async 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) {
+    async setIssueLabel(number, currentLabel, newLabel) {
         return this.exec(v.setIssueLabel(number, currentLabel, newLabel, this.target));
     }
 }

package/dist/doors.d.ts

@@ -27,12 +27,17 @@ import type { GhVerb } from './verbs.ts';
  * Read the result of running `verb` as the methods that throw do.
  *
  * A checked verb has already thrown on a non-zero exit (the runner is
- * `runChecked`). A probe (`installed`, `authStatus`, `api`) carries its
+ * {@link runCheckedGh}). A probe (`installed`, `authStatus`, `api`) carries its
  * failure in its value. A read that exited non-zero throws the classified
  * failure, 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.
  *
+ * A result flagged `outputIncomplete` throws for every verb but a probe, as
+ * typed-git's `gate` does: gh exited, but the runner stopped reading at the
+ * output cap or a timeout, so a parse would take cut-short output as whole.
+ * Both read a result through command-seam's `runFailed`.
+ *
  * @throws `FailureError` carrying the classified {@link GhFailure} for a failed run.
  * @throws `FailureError` carrying an `unreadable` {@link GhFailure}.
  */
@@ -43,9 +48,14 @@ export declare function settle<T>(verb: GhVerb<T>, result: CommandResult, binary
  * `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. */
+/**
+ * Run `argv` and throw {@link ghFailureError}'s classified failure unless gh
+ * exited 0 with its whole output. Output cut short (`outputIncomplete`) is a
+ * failure too, which `runChecked` alone would not catch: it checks only the
+ * exit code.
+ */
 export declare function runCheckedGh(runner: CommandRunner, argv: string[], opts: CommandRunOptions): CommandResult;
-/** {@link runCheckedAsync}, rejecting with {@link ghFailureError}'s classified failure. */
+/** {@link runCheckedGh} for an awaitable runner, rejecting with the classified failure. */
 export declare function runCheckedGhAsync(runner: AsyncCommandRunner, argv: string[], opts: AsyncCommandRunOptions): Promise<CommandResult>;
 /** The members `try` and `soft` leave out: `raw`, `rawChecked`, helpers that run nothing, and properties. */
 type Triable<C> = Omit<C, 'raw' | 'rawChecked' | 'at' | 'withRepo' | 'ownerRepo' | 'try' | 'soft' | 'cwd' | 'repo' | 'hostname'>;
@@ -73,7 +83,10 @@ export type Soft<C> = {
 export declare function failureOf(error: {
     failure: Failure;
 }): GhFailure;
-/** Wrap a synchronous client so every method returns a `Result<T, GhFailure>`. */
+/**
+ * Wrap a synchronous client so every method returns a `Result<T, GhFailure>`.
+ * The proxy is command-seam's `tryMethods`, so a new method needs no entry.
+ */
 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>;

package/dist/doors.js

@@ -19,30 +19,39 @@
  * `try` and `soft` are proxies over the whole client, so a new method needs no
  * change here.
  */
-import { CommandFailed, isCommandFailed, runChecked, runCheckedAsync, } from '@osdlc/command-seam';
-import { err, FailureError, isFailure, ok } from '@osdlc/result';
+import { CommandFailed, isCommandFailed, methodFacade, runFailed, tryMethods, tryMethodsAsync, } from '@osdlc/command-seam';
+import { FailureError, isFailure } from '@osdlc/result';
 import { classifyGhFailure, unreadableFailure } from "./failure.js";
 /**
  * Read the result of running `verb` as the methods that throw do.
  *
  * A checked verb has already thrown on a non-zero exit (the runner is
- * `runChecked`). A probe (`installed`, `authStatus`, `api`) carries its
+ * {@link runCheckedGh}). A probe (`installed`, `authStatus`, `api`) carries its
  * failure in its value. A read that exited non-zero throws the classified
  * failure, 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.
  *
+ * A result flagged `outputIncomplete` throws for every verb but a probe, as
+ * typed-git's `gate` does: gh exited, but the runner stopped reading at the
+ * output cap or a timeout, so a parse would take cut-short output as whole.
+ * Both read a result through command-seam's `runFailed`.
+ *
  * @throws `FailureError` carrying the classified {@link GhFailure} for a failed run.
  * @throws `FailureError` carrying an `unreadable` {@link GhFailure}.
  */
 export function settle(verb, result, binary) {
-    if (verb.checked || verb.probe === true)
+    if (verb.probe === true)
         return verb.parse(result);
-    if (result.neverExited === true || result.exitCode !== 0) {
-        if (result.neverExited !== true && verb.absent?.(result) === true)
-            return verb.parse(result);
+    // A checked verb's runner has already thrown on a non-zero exit.
+    const failed = verb.checked
+        ? result.outputIncomplete === true
+        : runFailed(result, (r) => verb.absent?.(r) === true);
+    if (failed)
         throw ghFailureError(new CommandFailed(verb.argv, result, binary));
-    }
+    // A non-zero exit that got this far is gh's "there is no such thing".
+    if (verb.checked || result.exitCode !== 0)
+        return verb.parse(result);
     const value = verb.parse(result);
     if (value === null) {
         throw new FailureError(unreadableFailure(verb.argv, result.stdout, binary));
@@ -57,24 +66,35 @@ export function settle(verb, result, binary) {
 export function ghFailureError(error) {
     return isCommandFailed(error) ? new FailureError(classifyGhFailure(error)) : error;
 }
-/** {@link runChecked}, throwing {@link ghFailureError}'s classified failure. */
+/**
+ * Run `argv` and throw {@link ghFailureError}'s classified failure unless gh
+ * exited 0 with its whole output. Output cut short (`outputIncomplete`) is a
+ * failure too, which `runChecked` alone would not catch: it checks only the
+ * exit code.
+ */
 export function runCheckedGh(runner, argv, opts) {
     try {
-        return runChecked(runner, argv, opts);
+        return whole(runner.run(argv, opts), argv, runner.binary);
     }
     catch (error) {
         throw ghFailureError(error);
     }
 }
-/** {@link runCheckedAsync}, rejecting with {@link ghFailureError}'s classified failure. */
+/** {@link runCheckedGh} for an awaitable runner, rejecting with the classified failure. */
 export async function runCheckedGhAsync(runner, argv, opts) {
     try {
-        return await runCheckedAsync(runner, argv, opts);
+        return whole(await runner.run(argv, opts), argv, runner.binary);
     }
     catch (error) {
         throw ghFailureError(error);
     }
 }
+/** `result`, or a `CommandFailed` thrown when it is a failure (command-seam's `runFailed`). */
+function whole(result, argv, binary) {
+    if (runFailed(result))
+        throw new CommandFailed(argv, result, binary);
+    return result;
+}
 /**
  * The queries that have a soft form. A mutation has none. If a write's failure
  * were dropped, the caller would believe the write worked.
@@ -110,45 +130,20 @@ export function failureOf(error) {
     const thrown = error;
     return isCommandFailed(thrown) ? classifyGhFailure(thrown) : error.failure;
 }
-function facade(client, wrap) {
-    return new Proxy(client, {
-        get(target, prop) {
-            // Read from the target, not the proxy. A getter (`try` itself) must run
-            // against the real client, not recurse through the proxy.
-            const value = Reflect.get(target, prop);
-            if (typeof value !== 'function')
-                return value;
-            const method = value;
-            const name = String(prop);
-            return (...args) => wrap(() => method.apply(target, args), name);
-        },
-    });
+/** The failure a thrown value carries, or `null` for a bug to rethrow. */
+function recognize(error) {
+    return isGhFailure(error) ? failureOf(error) : null;
 }
-/** Wrap a synchronous client so every method returns a `Result<T, GhFailure>`. */
+/**
+ * Wrap a synchronous client so every method returns a `Result<T, GhFailure>`.
+ * The proxy is command-seam's `tryMethods`, so a new method needs no entry.
+ */
 export function triedSync(client) {
-    return facade(client, (call) => {
-        try {
-            return ok(call());
-        }
-        catch (error) {
-            if (isGhFailure(error))
-                return err(failureOf(error));
-            throw error;
-        }
-    });
+    return tryMethods(client, recognize);
 }
 /** Wrap an awaitable client so every method promises a `Result<T, GhFailure>`. */
 export function triedAsync(client) {
-    return facade(client, async (call) => {
-        try {
-            return ok(await call());
-        }
-        catch (error) {
-            if (isGhFailure(error))
-                return err(failureOf(error));
-            throw error;
-        }
-    });
+    return tryMethodsAsync(client, recognize);
 }
 function checkSoft(name) {
     if (!SOFT_METHODS.includes(name)) {
@@ -157,7 +152,7 @@ function checkSoft(name) {
 }
 /** Wrap a synchronous client so a failed query returns `null`. */
 export function softSync(client) {
-    return facade(client, (call, name) => {
+    return methodFacade(client, (call, name) => {
         checkSoft(name);
         try {
             return call();
@@ -171,7 +166,7 @@ export function softSync(client) {
 }
 /** Wrap an awaitable client so a failed query resolves to `null`. */
 export function softAsync(client) {
-    return facade(client, async (call, name) => {
+    return methodFacade(client, async (call, name) => {
         checkSoft(name);
         try {
             return await call();

package/dist/failure.js

@@ -7,7 +7,7 @@
  * in English. A message that matches none stays the subprocess layer's `exit`
  * with `gh`'s first stderr line, never a wrong kind.
  */
-import { classifyFailure } from '@osdlc/command-seam';
+import { classifyFailed } from '@osdlc/command-seam';
 import {} from '@osdlc/result';
 const INSTALL_HINT = 'Install it from https://cli.github.com, then run `gh auth login`.';
 const RATE_LIMITED = /API rate limit exceeded|secondary rate limit|rate limit exceeded|HTTP 429/i;
@@ -37,13 +37,8 @@ export function isAbsent(thing, text) {
 export function classifyGhFailure(failed) {
     // The client's runner may not name its binary. It is gh either way, so the
     // messages say `gh` rather than "The command".
-    const f = failed.binary === undefined
-        ? (classifyFailure(failed.result, { binary: 'gh', argv: failed.argv }) ?? failed.failure)
-        : failed.failure;
-    const base = { ...f, cause: failed };
-    if (f.kind === 'not-installed')
-        return { ...base, hint: INSTALL_HINT };
-    if (f.kind !== 'exit')
+    const base = classifyFailed(failed, { binary: 'gh', installHint: INSTALL_HINT });
+    if (base.kind !== 'exit')
         return base;
     const text = `${failed.result.stderr}\n${failed.result.stdout}`;
     if (RATE_LIMITED.test(text)) {

package/dist/repo.d.ts

@@ -2,15 +2,20 @@
  * Reading the GitHub owner and repository from a git remote, and a pull
  * request from a URL or what a person typed.
  *
- * `parseOwnerRepo` uses `@osdlc/typed-git`'s `parseGitUrl`. It lives here so
- * callers do not each write a regex over `remote.origin.url`. Such a regex
- * usually misses a URL form: scp-style, a trailing `.git`, an `ssh://` port,
- * or a bare `owner/repo`.
+ * `parseOwnerRepo` is `@osdlc/typed-git`'s `parseRemoteRepo` without the
+ * host, so it reads every remote form typed-git reads (scp-style, a trailing
+ * `.git`, an `ssh://` port, a bare `owner/repo`, an Enterprise host) and no
+ * caller writes its own regex over `remote.origin.url`.
  */
 import type { OwnerRepo } from './types.ts';
 /**
  * `{owner, repo}` from any git remote reference, or null when it names no
  * project. Handles https, ssh, scp-style, and bare `owner/repo`.
+ *
+ * It is typed-git's `parseRemoteRepo` without the host: a clone URL on a host
+ * `parseGitUrl` does not know, such as a GitHub Enterprise host or another
+ * forge's `host/owner/repo`, is read host-agnostically. It does not check
+ * that the host is GitHub; read `parseRemoteRepo(url).host` for that.
  */
 export declare function parseOwnerRepo(remoteUrl: string): OwnerRepo | null;
 /** `owner/repo`, the form `gh api` paths and `--repo` both take. */

package/dist/repo.js

@@ -2,24 +2,24 @@
  * Reading the GitHub owner and repository from a git remote, and a pull
  * request from a URL or what a person typed.
  *
- * `parseOwnerRepo` uses `@osdlc/typed-git`'s `parseGitUrl`. It lives here so
- * callers do not each write a regex over `remote.origin.url`. Such a regex
- * usually misses a URL form: scp-style, a trailing `.git`, an `ssh://` port,
- * or a bare `owner/repo`.
+ * `parseOwnerRepo` is `@osdlc/typed-git`'s `parseRemoteRepo` without the
+ * host, so it reads every remote form typed-git reads (scp-style, a trailing
+ * `.git`, an `ssh://` port, a bare `owner/repo`, an Enterprise host) and no
+ * caller writes its own regex over `remote.origin.url`.
  */
-import { parseGitUrl } from '@osdlc/typed-git';
+import { parseRemoteRepo } from '@osdlc/typed-git';
 /**
  * `{owner, repo}` from any git remote reference, or null when it names no
  * project. Handles https, ssh, scp-style, and bare `owner/repo`.
+ *
+ * It is typed-git's `parseRemoteRepo` without the host: a clone URL on a host
+ * `parseGitUrl` does not know, such as a GitHub Enterprise host or another
+ * forge's `host/owner/repo`, is read host-agnostically. It does not check
+ * that the host is GitHub; read `parseRemoteRepo(url).host` for that.
  */
 export function parseOwnerRepo(remoteUrl) {
-    const info = parseGitUrl(remoteUrl);
-    if (info === null)
-        return null;
-    const { user, project } = info;
-    if (!user || !project)
-        return null;
-    return { owner: user, repo: project };
+    const remote = parseRemoteRepo(remoteUrl);
+    return remote === null ? null : { owner: remote.owner, repo: remote.repo };
 }
 /** `owner/repo`, the form `gh api` paths and `--repo` both take. */
 export function ownerRepoSlug(r) {

package/dist/sync.d.ts

@@ -22,11 +22,15 @@ import type { ApiOptions, ApiResponse, AuthStatus, GhTarget, IssueListOptions, L
 import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts';
 /**
  * Makes a runner for a binary. A CLI passes one factory to every place that
- * runs a command. Real code uses `spawnRunner`. Tests pass a factory that
- * records calls, so the CLI runs offline.
+ * runs a command. Real code uses {@link defaultRunnerFactory}. Tests pass a
+ * factory that records calls, so the CLI runs offline.
  */
 export type RunnerFactory = (binary: string) => CommandRunner;
-/** The default factory: real runners that use `spawnSync`. */
+/**
+ * The default factory: real runners that use `spawnSync`. A bare name is
+ * found on absolute `PATH` entries only, so a file of that name in the
+ * working directory cannot run in its place.
+ */
 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 {
@@ -126,6 +130,7 @@ export declare class Gh {
     openPrFor(branch: string, opts?: {
         limit?: number | undefined;
         fields?: readonly string[] | undefined;
+        timeoutMs?: number | undefined;
     }): PullRequest | null;
     /**
      * {@link prView}, asked again until GitHub has computed the merge state.
@@ -178,11 +183,18 @@ export declare class Gh {
     issueView(number: number, opts?: {
         timeoutMs?: number | undefined;
     }): IssueRow | null;
-    /** An owner's repositories (up to `opts.limit`, default 100). Throws when gh fails. */
+    /**
+     * An owner's repositories (up to `opts.limit`, default 100). Throws when gh
+     * fails. Each row's `owner` is in GitHub's casing, not as passed.
+     */
     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. */
+    /**
+     * One repository: `repo`, else the client's repo, else the clone at `cwd`.
+     * Null when there is no such repository. `owner` and `name` are in
+     * GitHub's casing, not as passed.
+     */
     repoView(repo?: string | undefined, opts?: {
         fields?: readonly string[] | undefined;
         timeoutMs?: number | undefined;

package/dist/sync.js

@@ -15,13 +15,17 @@
  * the failure as a `Result<T, GhFailure>`. `gh.soft.*` returns `null` for it.
  * `raw` and `rawChecked` run any `gh` call.
  */
-import { resolveRunner, spawnRunner, } from '@osdlc/command-seam';
+import { spawnRunner } from '@osdlc/command-seam';
 import { runCheckedGh, softSync, triedSync } from "./doors.js";
 import { runVerb } from "./run.js";
 import * as v from "./verbs.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
-/** The default factory: real runners that use `spawnSync`. */
-export const defaultRunnerFactory = spawnRunner;
+/**
+ * The default factory: real runners that use `spawnSync`. A bare name is
+ * found on absolute `PATH` entries only, so a file of that name in the
+ * working directory cannot run in its place.
+ */
+export const defaultRunnerFactory = (binary) => spawnRunner(binary, { absolutePathOnly: true });
 /** How long to wait between merge-state retries, in milliseconds. */
 const MERGE_STATE_RETRY_DELAY_MS = 1_500;
 /**
@@ -52,7 +56,7 @@ export class Gh {
         this.repo = opts.repo;
         this.hostname = opts.hostname;
         this.target = { repo: opts.repo, hostname: opts.hostname };
-        this.runner = resolveRunner('gh', opts.runner);
+        this.runner = opts.runner ?? defaultRunnerFactory('gh');
     }
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd) {
@@ -150,6 +154,7 @@ export class Gh {
             head: branch,
             limit: opts.limit ?? 5,
             fields: opts.fields ?? v.PR_REF_FIELDS,
+            timeoutMs: opts.timeoutMs,
         });
         return v.pickPrForBranch(rows.rows, branch);
     }
@@ -210,11 +215,18 @@ export class Gh {
     issueView(number, opts = {}) {
         return this.exec(v.issueView(number, this.target), opts.timeoutMs);
     }
-    /** An owner's repositories (up to `opts.limit`, default 100). Throws when gh fails. */
+    /**
+     * An owner's repositories (up to `opts.limit`, default 100). Throws when gh
+     * fails. Each row's `owner` is in GitHub's casing, not as passed.
+     */
     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. */
+    /**
+     * One repository: `repo`, else the client's repo, else the clone at `cwd`.
+     * Null when there is no such repository. `owner` and `name` are in
+     * GitHub's casing, not as passed.
+     */
     repoView(repo, opts = {}) {
         return this.exec(v.repoView(repo, opts.fields ?? v.REPO_FIELDS, this.target), opts.timeoutMs);
     }

package/dist/types.d.ts

@@ -156,9 +156,14 @@ export type RepositoryVisibility = 'PUBLIC' | 'PRIVATE' | 'INTERNAL' | (string &
  * without one: a row without it is dropped.
  */
 export interface Repository {
-    /** `owner/name`. */
+    /** `owner/name`, in GitHub's casing. */
     nameWithOwner: string;
+    /**
+     * Cut from `nameWithOwner`, so in GitHub's casing, not as the caller wrote
+     * it: `repoList('ACME')` gives `owner: 'acme'` when the account is `acme`.
+     */
     owner: string;
+    /** Cut from `nameWithOwner`, so in GitHub's casing. */
     name: string;
     description: string;
     /** The default branch. Null when not asked for, or when the repository is empty. */
@@ -178,6 +183,7 @@ export interface PrSearchHit {
     state: PullRequestState;
     url: string;
     isDraft: boolean;
+    /** Cut from the hit's `nameWithOwner`, so in GitHub's casing. */
     repository: OwnerRepo | null;
     author: Actor | null;
     labels: Label[];

package/dist/verbs.d.ts

@@ -35,9 +35,9 @@ export interface GhVerb<T> {
     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 all
-     * three call styles. Other reads throw from the plain method when gh exits
-     * non-zero.
+     * `authStatus` and `api` return what `parse` makes of any result, from the
+     * plain method and from `try`; they have no soft form. Other reads throw
+     * from the plain method when gh exits non-zero.
      */
     probe?: boolean | undefined;
     /**
@@ -94,7 +94,10 @@ export declare const PR_VIEW_FIELDS: readonly ["number", "state", "title", "url"
 /**
  * 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`.
+ * that row came back, and `rows` holds at most `limit`. A query that goes
+ * through GitHub search, which returns at most 1000 results, is also
+ * `truncated` when 1000 rows came back: `prList` with a non-empty `search` or
+ * an `author`, `issueList` with a `label`, and `searchPrs`.
  */
 export interface ListResult<T> {
     rows: T[];
@@ -223,8 +226,10 @@ export interface GraphqlOptions {
  * 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`.
+ * target's repo, or by gh from the clone. A document holding any mutation or
+ * subscription throws `RangeError`, as does a variable named `query` or
+ * `operationName`, which gh would send as the request's own fields. This is a
+ * read, and changes go through `raw`.
  *
  * @experimental
  */
@@ -284,12 +289,15 @@ export interface RepoListOptions {
 }
 /**
  * `gh repo list <owner> --json …`: an owner's repositories. The host comes
- * from the target (`GH_HOST`). The target's repo is not used.
+ * from the target (`GH_HOST`). The target's repo is not used. Each row's
+ * `owner` is in GitHub's casing, not as passed. To build paths that match
+ * your config, use your own value.
  */
 export declare function repoList(owner: string, opts?: RepoListOptions, target?: GhTarget): GhVerb<ListResult<Repository> | null>;
 /**
  * `gh repo view [<[host/]owner/name>] --json …`: one repository. That is `repo`,
- * else the target's repo, else the clone at the client's cwd.
+ * else the target's repo, else the clone at the client's cwd. The result's
+ * `owner` and `name` are in GitHub's casing, not as passed.
  */
 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. */

package/dist/verbs.js

@@ -13,7 +13,7 @@
  * `settle` (see `doors.ts`) instead. There a failure throws, except where the
  * verb declares `absent` or is a `probe`.
  */
-import { stderrOrError } from '@osdlc/command-seam';
+import { notAnOption, stderrOrError } from '@osdlc/command-seam';
 import { parseLabels, parsePrSearchHit, parsePullRequest, parseRepository } from "./parse.js";
 import { isAbsent } from "./failure.js";
 import { isRepoSlug, parsePrUrl } from "./repo.js";
@@ -48,16 +48,26 @@ export function checkTarget(target) {
         throw new RangeError(`hostname must be a bare host, got ${JSON.stringify(hostname)}`);
     }
 }
-/** `--repo [host/]owner/name` for `pr`, `issue` and `label` verbs. `repo` overrides the target's. */
-function repoArgs(target, repo) {
+/**
+ * `[host/]owner/name` for `repo` (else the target's repo), the form `--repo`
+ * and `gh repo view` take, or `undefined` when neither names one. The host is
+ * the target's, through {@link hostOf}, so a hostname of `''` is "not set".
+ * Both are checked first.
+ */
+function qualifiedRepo(target, repo) {
     checkTarget(target);
-    const slug = repo ?? target?.repo;
-    if (slug === undefined)
-        return [];
     if (repo !== undefined)
         checkTarget({ repo });
+    const slug = repo ?? target?.repo;
+    if (slug === undefined)
+        return undefined;
     const hostname = hostOf(target);
-    return ['--repo', hostname === undefined ? slug : `${hostname}/${slug}`];
+    return hostname === undefined ? slug : `${hostname}/${slug}`;
+}
+/** `--repo [host/]owner/name` for `pr`, `issue` and `label` verbs. `repo` overrides the target's. */
+function repoArgs(target, repo) {
+    const qualified = qualifiedRepo(target, repo);
+    return qualified === undefined ? [] : ['--repo', qualified];
 }
 /** `--hostname <host>` for `api` and `auth` verbs. */
 function hostArgs(target) {
@@ -144,24 +154,7 @@ function oneOrNull(r) {
  * failed. A caller must be able to tell "no PRs" from "couldn't ask".
  */
 function manyOrNull(r) {
-    if (r.exitCode !== 0)
-        return null;
-    let data;
-    try {
-        data = JSON.parse(r.stdout || '[]');
-    }
-    catch {
-        return null;
-    }
-    if (!Array.isArray(data))
-        return null;
-    const rows = [];
-    for (const item of data) {
-        const pr = parsePullRequest(item);
-        if (pr !== null)
-            rows.push(pr);
-    }
-    return rows;
+    return rowsOrNull(r, (item) => parsePullRequest(item));
 }
 /** Throw `RangeError` unless `limit` is a positive integer. */
 function checkLimit(limit) {
@@ -169,11 +162,23 @@ function checkLimit(limit) {
         throw new RangeError(`limit must be a positive integer, got ${limit}`);
     }
 }
-/** `rows` cut to `limit`, with whether there were more. Null stays null. */
-function limited(rows, limit) {
+/**
+ * The most results GitHub search returns for one query. A call that goes
+ * through search and gets this many rows may have been cut off by search,
+ * whatever the `limit`. gh uses search for `pr list` with a non-empty
+ * `--search` or with `--author`, for `issue list` with `--label`, and for
+ * `search prs`.
+ */
+const SEARCH_RESULT_CAP = 1000;
+/**
+ * `rows` cut to `limit`, with whether there were more. With `cap`, reaching
+ * it counts as more too, since the source stops there. Null stays null.
+ */
+function limited(rows, limit, cap) {
     if (rows === null)
         return null;
-    return { rows: rows.slice(0, limit), truncated: rows.length > limit };
+    const truncated = rows.length > limit || (cap !== undefined && rows.length >= cap);
+    return { rows: rows.slice(0, limit), truncated };
 }
 /** A mutation's result carries no value. */
 function nothing() { }
@@ -232,24 +237,7 @@ function oneIssueOrNull(r) {
  * on failure, as {@link manyOrNull} does for PRs.
  */
 function manyIssuesOrNull(r) {
-    if (r.exitCode !== 0)
-        return null;
-    let data;
-    try {
-        data = JSON.parse(r.stdout || '[]');
-    }
-    catch {
-        return null;
-    }
-    if (!Array.isArray(data))
-        return null;
-    const rows = [];
-    for (const item of data) {
-        const row = parseIssueRow(item);
-        if (row !== null)
-            rows.push(row);
-    }
-    return rows;
+    return rowsOrNull(r, parseIssueRow);
 }
 /** `gh pr list …`: open PRs by default. `opts.repo` overrides the target's repo. */
 export function prList(opts = {}, target) {
@@ -278,7 +266,8 @@ export function prList(opts = {}, target) {
         checked: false,
         readOnly: true,
         parse(r) {
-            const result = limited(manyOrNull(r), limit);
+            // A search stops at 1000 results, so 1000 rows may be a cut, not the end.
+            const result = limited(manyOrNull(r), limit, (opts.search ?? '') !== '' || opts.author !== undefined ? SEARCH_RESULT_CAP : undefined);
             if (result === null || head === undefined)
                 return result;
             return { ...result, rows: result.rows.filter((pr) => pr.headRefName === head) };
@@ -294,9 +283,8 @@ function withFields(fields, required) {
  * argument would read as a flag.
  */
 function notAFlag(what, value) {
-    if (value.startsWith('-')) {
-        throw new RangeError(`${what} must not start with "-", got ${JSON.stringify(value)}`);
-    }
+    const message = (v) => `${what} must not start with "-", got ${JSON.stringify(v)}`;
+    notAnOption(value, (v) => new RangeError(message(v)));
 }
 /**
  * `gh pr view <number|branch|url> --json …`: one PR, with the full field set
@@ -313,15 +301,14 @@ export function prView(ref, fields = PR_VIEW_FIELDS, target) {
     // omits it would read as "no such PR". Always ask for it, and each field once.
     const asked = withFields(fields, ['number']);
     const isUrl = typeof ref === 'string' && parsePrUrl(ref) !== null;
+    // gh reads a selector as a URL only with an http(s) scheme; a scheme-less
+    // one (`github.com/o/r/pull/7`, which parsePrUrl accepts) would be taken as
+    // a branch name.
+    const selector = typeof ref === 'string' && isUrl && !/^https?:\/\//i.test(ref.trim())
+        ? `https://${ref.trim()}`
+        : String(ref);
     return {
-        argv: [
-            'pr',
-            'view',
-            String(ref),
-            ...(isUrl ? [] : repoArgs(target)),
-            '--json',
-            asked.join(','),
-        ],
+        argv: ['pr', 'view', selector, ...(isUrl ? [] : repoArgs(target)), '--json', asked.join(',')],
         checked: false,
         readOnly: true,
         absent: noSuch('pr'),
@@ -392,6 +379,27 @@ function flattenPages(body) {
         return body;
     return body.flat();
 }
+/**
+ * True when any operation in a GraphQL document is a `mutation` or a
+ * `subscription`. Strings and comments are dropped first, and only the words
+ * outside every `{…}` and `(…)` are read, which is where an operation's
+ * keyword stands. So a leading fragment, a leading `,` (an ignored token) or a
+ * second operation after a query cannot hide one.
+ */
+function writesOrStreams(document) {
+    const code = document.replace(/"""[\s\S]*?"""|"(?:[^"\\\n]|\\.)*"|#[^\n]*/g, ' ');
+    let depth = 0;
+    for (const token of code.matchAll(/[{}()]|[_A-Za-z][_0-9A-Za-z]*/g)) {
+        const t = token[0];
+        if (t === '{' || t === '(')
+            depth += 1;
+        else if (t === '}' || t === ')')
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0 && (t === 'mutation' || t === 'subscription'))
+            return true;
+    }
+    return false;
+}
 /**
  * `gh api graphql -f query=… [--paginate --slurp]`: a GraphQL query.
  *
@@ -401,15 +409,16 @@ function flattenPages(body) {
  * 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`.
+ * target's repo, or by gh from the clone. A document holding any mutation or
+ * subscription throws `RangeError`, as does a variable named `query` or
+ * `operationName`, which gh would send as the request's own fields. This is a
+ * read, and changes go through `raw`.
  *
  * @experimental
  */
 export function graphql(query, variables = {}, opts = {}, target) {
     checkTarget(target);
-    const body = query.replace(/^(?:\s|#[^\n]*\n?)*/, '');
-    if (/^mutation\b/.test(body) || /^subscription\b/.test(body)) {
+    if (writesOrStreams(query)) {
         throw new RangeError('graphql: only queries are allowed; send a mutation through raw');
     }
     const paginate = opts.paginate === true;
@@ -421,7 +430,10 @@ export function graphql(query, variables = {}, opts = {}, target) {
         argv.push('--paginate', '--slurp');
     const [owner, name] = target?.repo?.split('/') ?? [];
     for (const [key, value] of Object.entries(variables)) {
-        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        // gh lifts `query` and `operationName` out of the variables into the
+        // request itself, so either would replace the checked document or pick
+        // another operation in it.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || key === 'query' || key === 'operationName') {
             throw new RangeError(`graphql: bad variable name ${JSON.stringify(key)}`);
         }
         if (typeof value === 'string') {
@@ -605,7 +617,14 @@ export function issueList(opts = {}, target) {
     if (opts.label !== undefined)
         argv.push('--label', opts.label);
     argv.push('--json', ISSUE_FIELDS, '--limit', String(limit + 1));
-    return { argv, checked: false, readOnly: true, parse: (r) => limited(manyIssuesOrNull(r), limit) };
+    // gh lists issues by label through search, which stops at 1000 results.
+    const cap = opts.label === undefined ? undefined : SEARCH_RESULT_CAP;
+    return {
+        argv,
+        checked: false,
+        readOnly: true,
+        parse: (r) => limited(manyIssuesOrNull(r), limit, cap),
+    };
 }
 /** `gh issue view <n> --json …`: one issue, same field set as {@link issueList}. */
 export function issueView(number, target) {
@@ -657,7 +676,9 @@ function rowsOrNull(r, parse) {
 }
 /**
  * `gh repo list <owner> --json …`: an owner's repositories. The host comes
- * from the target (`GH_HOST`). The target's repo is not used.
+ * from the target (`GH_HOST`). The target's repo is not used. Each row's
+ * `owner` is in GitHub's casing, not as passed. To build paths that match
+ * your config, use your own value.
  */
 export function repoList(owner, opts = {}, target) {
     notAFlag('repoList owner', owner);
@@ -682,17 +703,15 @@ export function repoList(owner, opts = {}, target) {
 }
 /**
  * `gh repo view [<[host/]owner/name>] --json …`: one repository. That is `repo`,
- * else the target's repo, else the clone at the client's cwd.
+ * else the target's repo, else the clone at the client's cwd. The result's
+ * `owner` and `name` are in GitHub's casing, not as passed.
  */
 export function repoView(repo, fields = REPO_FIELDS, target) {
-    checkTarget(target);
-    if (repo !== undefined)
-        checkTarget({ repo });
-    const slug = repo ?? target?.repo;
+    // The same `[host/]owner/name` rule as `--repo`.
+    const qualified = qualifiedRepo(target, repo);
     const argv = ['repo', 'view'];
-    if (slug !== undefined) {
-        argv.push(target?.hostname === undefined ? slug : `${target.hostname}/${slug}`);
-    }
+    if (qualified !== undefined)
+        argv.push(qualified);
     argv.push('--json', withFields(fields, ['nameWithOwner']).join(','));
     return {
         argv,
@@ -734,7 +753,9 @@ export function searchPrs(query, opts = {}, target) {
     else if (opts.state !== undefined)
         argv.push('--state', opts.state);
     argv.push('--json', withFields(opts.fields ?? SEARCH_PR_FIELDS, ['number']).join(','));
-    argv.push('--limit', String(limit + 1));
+    // gh refuses a search limit over 1000, so ask for at most that. 1000 rows
+    // then read as truncated: search may hold more.
+    argv.push('--limit', String(Math.min(limit + 1, SEARCH_RESULT_CAP)));
     if (query !== '')
         argv.push('--', query);
     return {
@@ -742,7 +763,7 @@ export function searchPrs(query, opts = {}, target) {
         checked: false,
         readOnly: true,
         env: hostEnv(target),
-        parse: (r) => limited(rowsOrNull(r, parsePrSearchHit), limit),
+        parse: (r) => limited(rowsOrNull(r, parsePrSearchHit), limit, SEARCH_RESULT_CAP),
     };
 }
 /**
@@ -906,6 +927,7 @@ export function prReviewThreads(number, target) {
  * and description are set to these instead of failing.
  */
 export function createLabel(opts, target) {
+    notAFlag('createLabel name', opts.name);
     const argv = [
         'label',
         'create',
@@ -921,6 +943,7 @@ export function createLabel(opts, target) {
 }
 /** `gh label edit <name>`: change the color or description. A flag not given is left out. */
 export function editLabel(name, opts, target) {
+    notAFlag('editLabel name', name);
     const argv = ['label', 'edit', name, ...repoArgs(target)];
     if (opts.color !== undefined)
         argv.push('--color', opts.color);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.9.5",
+  "version": "0.11.1",
   "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",
   "author": "sksizer",
@@ -22,8 +22,8 @@
     "LICENSE-APACHE"
   ],
   "dependencies": {
-    "@osdlc/command-seam": "^0.12.0",
-    "@osdlc/typed-git": "^0.8.1",
+    "@osdlc/command-seam": "^0.14.0",
+    "@osdlc/typed-git": "^0.10.0",
     "@osdlc/result": "^0.1.0"
   },
   "engines": {