@osdlc/typed-gh 0.9.6 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @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

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`
@@ -440,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
 
@@ -547,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.js

@@ -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,41 +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. Each row's `owner` is in
      * GitHub's casing, not as passed. See `Gh.repoList`.
      */
-    repoList(owner, opts = {}) {
+    async repoList(owner, opts = {}) {
         return this.read(v.repoList(owner, opts, this.target), 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`.
      */
-    repoView(repo, opts = {}) {
+    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. */
@@ -181,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. */
@@ -197,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));
     }
     /**
@@ -221,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));
     }
     /**
@@ -238,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

@@ -130,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.

package/dist/sync.js

@@ -154,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);
     }

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
  */

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) {
@@ -688,14 +707,11 @@ export function repoList(owner, opts = {}, target) {
  * `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,
@@ -737,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 {
@@ -745,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),
     };
 }
 /**
@@ -909,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',
@@ -924,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.6",
+  "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,9 +22,9 @@
     "LICENSE-APACHE"
   ],
   "dependencies": {
-    "@osdlc/command-seam": "^0.12.1",
-    "@osdlc/result": "^0.1.0",
-    "@osdlc/typed-git": "^0.8.2"
+    "@osdlc/command-seam": "^0.14.0",
+    "@osdlc/typed-git": "^0.10.0",
+    "@osdlc/result": "^0.1.0"
   },
   "engines": {
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"