@osdlc/typed-gh 0.6.0 → 0.9.0

package/dist/async.js

@@ -1,13 +1,17 @@
 /**
  * `AsyncGh` — the awaitable GitHub client, with the same methods as {@link Gh}.
  *
- * Same tri-modal contract, promised: queries resolve to parsed values and
- * never reject on a gh failure, mutations reject with `CommandFailed`, and
- * `raw`/`rawChecked` are the hatches. It is driven by the same pure verb
+ * Same three doors, promised: the plain method resolves to a value or rejects
+ * (a `FailureError` carrying the classified `GhFailure` for a failed gh or output it cannot read;
+ * a query for one thing resolves `null` when GitHub has no such thing),
+ * `try` resolves to a `Result<T, GhFailure>`, `soft` resolves `null` for a
+ * failure, and `raw`/`rawChecked` are the hatches. It is driven by the same pure verb
  * table as `Gh`, so the two cannot drift on argv or parsing. Use it where the
  * sync client would block the event loop: a fan-out of per-PR queries.
  */
-import { runCheckedAsync, resolveRunnerAsync, } from '@osdlc/command-seam';
+import { resolveRunnerAsync, } from '@osdlc/command-seam';
+import { runCheckedGhAsync, softAsync, triedAsync } from "./doors.js";
+import { runVerbAsync } from "./run.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
 import * as v from "./verbs.js";
 /** How long to wait between merge-state retries, in milliseconds. */
@@ -22,6 +26,8 @@ export class AsyncGh {
     hostname;
     target;
     runner;
+    tried;
+    softened;
     constructor(cwd, opts = {}) {
         v.checkTarget(opts);
         this.cwd = cwd;
@@ -38,35 +44,43 @@ export class AsyncGh {
     withRepo(repo) {
         return new AsyncGh(this.cwd, { runner: this.runner, repo, hostname: this.hostname });
     }
+    /**
+     * The whole surface again, resolving to a `Result<T, GhFailure>` instead of
+     * rejecting. A query for one thing that finds nothing is `ok: true` with
+     * `null`. See `Gh.try`.
+     */
+    get try() {
+        return (this.tried ??= triedAsync(this));
+    }
+    /** Each query again, resolving `null` instead of rejecting when `gh` fails. See `Gh.soft`. */
+    get soft() {
+        return (this.softened ??= softAsync(this));
+    }
     // ── escape hatches ────────────────────────────────────────────────────────
     /** Unchecked passthrough for verbs not yet lifted into the API. */
     raw(argv, opts = {}) {
         return this.runner.run(argv, { cwd: this.cwd, ...opts });
     }
-    /** Checked passthrough — rejects with `CommandFailed` on a non-zero exit. */
+    /** Checked passthrough — rejects with the classified failure on a non-zero exit. */
     rawChecked(argv, opts = {}) {
-        return runCheckedAsync(this.runner, argv, { cwd: this.cwd, ...opts });
+        return runCheckedGhAsync(this.runner, argv, { cwd: this.cwd, ...opts });
     }
     /** Run one verb from the table, honouring its checked/unchecked contract. */
     async exec(verb, call = {}) {
-        const opts = { cwd: this.cwd };
-        if (verb.input !== undefined)
-            opts.input = verb.input;
-        if (verb.env !== undefined)
-            opts.env = verb.env;
-        if (call.timeoutMs !== undefined)
-            opts.timeoutMs = call.timeoutMs;
-        if (call.signal !== undefined)
-            opts.signal = call.signal;
-        const result = verb.checked
-            ? await runCheckedAsync(this.runner, verb.argv, opts)
-            : await this.runner.run(verb.argv, opts);
-        return verb.parse(result);
+        return runVerbAsync(verb, this.runner, {
+            cwd: this.cwd,
+            timeoutMs: call.timeoutMs,
+            signal: call.signal,
+        });
+    }
+    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run rejects. */
+    async read(verb, call = {}) {
+        return (await this.exec(verb, call));
     }
     // ── queries ───────────────────────────────────────────────────────────────
-    /** Pull requests matching `opts`, or null when gh failed. */
+    /** Pull requests matching `opts`. Rejects when gh fails; `soft.prList` resolves null instead. */
     prList(opts = {}) {
-        return this.exec(v.prList(opts, this.target), 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 = {}) {
@@ -95,7 +109,7 @@ export class AsyncGh {
             timeoutMs: opts.timeoutMs,
             signal: opts.signal,
         });
-        return v.pickPrForBranch(rows?.rows ?? null, branch);
+        return v.pickPrForBranch(rows.rows, branch);
     }
     /** {@link prView}, re-asked until GitHub settles the merge state. See `Gh.prViewSettled`. */
     async prViewSettled(number, opts = {}) {
@@ -111,45 +125,45 @@ export class AsyncGh {
         }
         return last;
     }
-    /** A PR's body text, or null when gh failed. */
+    /** A PR's body text. Rejects when gh fails. */
     prBody(number, opts = {}) {
-        return this.exec(v.prBody(number, this.target), 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 = {}) {
         return this.exec(v.api(endpoint, opts, this.target), opts);
     }
     /**
-     * A GraphQL query; each page's `data`, or null. See `Gh.graphql`.
+     * A GraphQL query; each page's `data`. Rejects on a failed or partial result. See `Gh.graphql`.
      *
      * @experimental
      */
     graphql(query, variables = {}, opts = {}) {
-        return this.exec(v.graphql(query, variables, opts, this.target), opts);
+        return this.read(v.graphql(query, variables, opts, this.target), opts);
     }
-    /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
+    /** Every label on the repository (up to `opts.limit`, default 1000). Rejects when gh fails. */
     labelList(opts = {}) {
-        return this.exec(v.labelList(opts, this.target), opts);
+        return this.read(v.labelList(opts, this.target), opts);
     }
-    /** Issues matching `opts`, or null when gh failed. */
+    /** Issues matching `opts`. Rejects when gh fails. */
     issueList(opts = {}) {
-        return this.exec(v.issueList(opts, this.target), opts);
+        return this.read(v.issueList(opts, this.target), opts);
     }
-    /** One issue with its labels, or null when gh failed. */
+    /** One issue with its labels; null when there is no such issue. */
     issueView(number, opts = {}) {
         return this.exec(v.issueView(number, this.target), opts);
     }
-    /** An owner's repositories, or null when gh failed. See `Gh.repoList`. */
+    /** An owner's repositories. Rejects when gh fails. See `Gh.repoList`. */
     repoList(owner, opts = {}) {
-        return this.exec(v.repoList(owner, opts, this.target), opts);
+        return this.read(v.repoList(owner, opts, this.target), opts);
     }
-    /** One repository, or null when gh failed. See `Gh.repoView`. */
+    /** One repository; null when there is no such repository. See `Gh.repoView`. */
     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, or null. See `Gh.searchPrs`. */
+    /** Pull requests across repositories matching a search query. Rejects when gh fails. See `Gh.searchPrs`. */
     searchPrs(query, opts = {}) {
-        return this.exec(v.searchPrs(query, opts, this.target), opts);
+        return this.read(v.searchPrs(query, opts, this.target), opts);
     }
     /** True iff the `gh` binary is on PATH and runs. */
     installed() {
@@ -187,7 +201,7 @@ export class AsyncGh {
     editPrBody(number, body) {
         return this.exec(v.editPrBody(number, body, this.target));
     }
-    /** The PR's unified diff; rejects with `CommandFailed` when gh cannot produce it. */
+    /** The PR's unified diff; rejects with the classified failure when gh cannot produce it. */
     prDiff(number) {
         return this.exec(v.prDiff(number, this.target));
     }
@@ -226,7 +240,7 @@ export class AsyncGh {
     }
     /** A PR's review threads, or null when they could not be read completely. */
     prReviewThreads(number) {
-        return this.exec(v.prReviewThreads(number, this.target));
+        return this.read(v.prReviewThreads(number, this.target));
     }
     /** Create a label (or force it to `opts`'s color/description if it exists). */
     createLabel(opts) {

package/dist/doors.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The three doors, as `@osdlc/typed-git` has them: the plain verb (checked),
+ * `gh.try.*` and `gh.soft.*`.
+ *
+ *   - **Plain / checked**: a value, or a throw. A failed `gh` throws a
+ *     `FailureError` carrying the classified `GhFailure` (its `cause` is the
+ *     `CommandFailed`), so a caller that reports it, such as `runMain`, reads
+ *     "signed out" or "rate limited" and not a bare exit; output that exited 0
+ *     but could not be read throws one of kind `unreadable`. A verb that
+ *     reads one thing (`prView`, `issueView`, `repoView`) answers `null` when
+ *     GitHub says there is no such thing: absence is an answer.
+ *   - **`try`**: the same call, with the failure returned as
+ *     `Result<T, GhFailure>`. It catches a thrown failure (a `FailureError`, or a
+ *     `CommandFailed` from `raw`-level code) and nothing else: a `RangeError` for a bad argument still throws.
+ *   - **`soft`**: the same call, with `null` for a failure. Only the queries
+ *     have a soft form; no mutation does.
+ *
+ * Both are facades over the whole client, so a new method costs nothing here.
+ */
+import { type AsyncCommandRunner, type AsyncCommandRunOptions, type CommandResult, type CommandRunner, type CommandRunOptions } from '@osdlc/command-seam';
+import { type Failure, type Result } from '@osdlc/result';
+import { type GhFailure } from './failure.ts';
+import type { GhVerb } from './verbs.ts';
+/**
+ * Read the result of running `verb` as the plain door does.
+ *
+ * A checked verb has already thrown on a non-zero exit (the runner is
+ * `runChecked`), and a probe (`installed`, `authStatus`, `api`) carries its
+ * failure in its value. A read that exited non-zero throws `CommandFailed`,
+ * 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.
+ *
+ * @throws `FailureError` carrying the classified {@link GhFailure} for a failed run.
+ * @throws `FailureError` carrying an `unreadable` {@link GhFailure}.
+ */
+export declare function settle<T>(verb: GhVerb<T>, result: CommandResult, binary: string | undefined): T;
+/**
+ * The error the plain door throws for a failed run: a `FailureError` carrying
+ * the {@link GhFailure} that {@link classifyGhFailure} reads from it, with the
+ * `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. */
+export declare function runCheckedGh(runner: CommandRunner, argv: string[], opts: CommandRunOptions): CommandResult;
+/** {@link runCheckedAsync}, rejecting with {@link ghFailureError}'s classified failure. */
+export declare function runCheckedGhAsync(runner: AsyncCommandRunner, argv: string[], opts: AsyncCommandRunOptions): Promise<CommandResult>;
+/** The methods the doors leave out: the escape hatches, pure helpers and plain properties. */
+type Triable<C> = Omit<C, 'raw' | 'rawChecked' | 'at' | 'withRepo' | 'ownerRepo' | 'try' | 'soft' | 'cwd' | 'repo' | 'hostname'>;
+/** Every synchronous client method, returning a `Result<T, GhFailure>`. */
+export type TriedSync<C> = {
+    [K in keyof Triable<C>]: Triable<C>[K] extends (...a: infer A) => infer R ? (...a: A) => Result<R, GhFailure> : never;
+};
+/** Every awaitable client method, promising a `Result<T, GhFailure>`. */
+export type TriedAsync<C> = {
+    [K in keyof Triable<C>]: Triable<C>[K] extends (...a: infer A) => Promise<infer R> ? (...a: A) => Promise<Result<R, GhFailure>> : never;
+};
+/**
+ * The queries that have a soft form. A mutation has none: swallowing the failure
+ * of a write is how a caller ends up believing it worked.
+ */
+export declare const SOFT_METHODS: readonly ["prList", "prView", "prFind", "openPrFor", "prViewSettled", "prBody", "graphql", "labelList", "issueList", "issueView", "repoList", "repoView", "searchPrs", "prReviewThreads"];
+/** The name of a method with a soft form. */
+export type SoftMethod = (typeof SOFT_METHODS)[number];
+type OrNull<R> = R extends Promise<infer U> ? Promise<U | null> : R | null;
+/** Each queried method again, returning `null` instead of throwing. One type for both clients. */
+export type Soft<C> = {
+    [K in SoftMethod & keyof C]: C[K] extends (...a: infer A) => infer R ? (...a: A) => OrNull<R> : never;
+};
+/** The failure a caught `CommandFailed` or `FailureError` stands for. */
+export declare function failureOf(error: {
+    failure: Failure;
+}): GhFailure;
+/** Wrap a synchronous client so every method returns a `Result<T, GhFailure>`. */
+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>;
+/** Wrap a synchronous client so a failed query returns `null`. */
+export declare function softSync<C extends object>(client: C): Soft<C>;
+/** Wrap an awaitable client so a failed query resolves to `null`. */
+export declare function softAsync<C extends object>(client: C): Soft<C>;
+export {};

package/dist/doors.js

@@ -0,0 +1,183 @@
+/**
+ * The three doors, as `@osdlc/typed-git` has them: the plain verb (checked),
+ * `gh.try.*` and `gh.soft.*`.
+ *
+ *   - **Plain / checked**: a value, or a throw. A failed `gh` throws a
+ *     `FailureError` carrying the classified `GhFailure` (its `cause` is the
+ *     `CommandFailed`), so a caller that reports it, such as `runMain`, reads
+ *     "signed out" or "rate limited" and not a bare exit; output that exited 0
+ *     but could not be read throws one of kind `unreadable`. A verb that
+ *     reads one thing (`prView`, `issueView`, `repoView`) answers `null` when
+ *     GitHub says there is no such thing: absence is an answer.
+ *   - **`try`**: the same call, with the failure returned as
+ *     `Result<T, GhFailure>`. It catches a thrown failure (a `FailureError`, or a
+ *     `CommandFailed` from `raw`-level code) and nothing else: a `RangeError` for a bad argument still throws.
+ *   - **`soft`**: the same call, with `null` for a failure. Only the queries
+ *     have a soft form; no mutation does.
+ *
+ * Both are facades over the whole client, so a new method costs nothing here.
+ */
+import { CommandFailed, isCommandFailed, runChecked, runCheckedAsync, } from '@osdlc/command-seam';
+import { err, FailureError, isFailure, ok } from '@osdlc/result';
+import { classifyGhFailure, unreadableFailure } from "./failure.js";
+/**
+ * Read the result of running `verb` as the plain door does.
+ *
+ * A checked verb has already thrown on a non-zero exit (the runner is
+ * `runChecked`), and a probe (`installed`, `authStatus`, `api`) carries its
+ * failure in its value. A read that exited non-zero throws `CommandFailed`,
+ * 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.
+ *
+ * @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)
+        return verb.parse(result);
+    if (result.neverExited === true || result.exitCode !== 0) {
+        if (result.neverExited !== true && verb.absent?.(result) === true)
+            return verb.parse(result);
+        throw ghFailureError(new CommandFailed(verb.argv, result, binary));
+    }
+    const value = verb.parse(result);
+    if (value === null) {
+        throw new FailureError(unreadableFailure(verb.argv, result.stdout, binary));
+    }
+    return value;
+}
+/**
+ * The error the plain door throws for a failed run: a `FailureError` carrying
+ * the {@link GhFailure} that {@link classifyGhFailure} reads from it, with the
+ * `CommandFailed` as its `cause`. Anything else is returned as it is.
+ */
+export function ghFailureError(error) {
+    return isCommandFailed(error) ? new FailureError(classifyGhFailure(error)) : error;
+}
+/** {@link runChecked}, throwing {@link ghFailureError}'s classified failure. */
+export function runCheckedGh(runner, argv, opts) {
+    try {
+        return runChecked(runner, argv, opts);
+    }
+    catch (error) {
+        throw ghFailureError(error);
+    }
+}
+/** {@link runCheckedAsync}, rejecting with {@link ghFailureError}'s classified failure. */
+export async function runCheckedGhAsync(runner, argv, opts) {
+    try {
+        return await runCheckedAsync(runner, argv, opts);
+    }
+    catch (error) {
+        throw ghFailureError(error);
+    }
+}
+/**
+ * The queries that have a soft form. A mutation has none: swallowing the failure
+ * of a write is how a caller ends up believing it worked.
+ */
+export const SOFT_METHODS = [
+    'prList',
+    'prView',
+    'prFind',
+    'openPrFor',
+    'prViewSettled',
+    'prBody',
+    'graphql',
+    'labelList',
+    'issueList',
+    'issueView',
+    'repoList',
+    'repoView',
+    'searchPrs',
+    'prReviewThreads',
+];
+/**
+ * Whether `error` carries a failure to hand back rather than a bug to let
+ * through. By shape, not `instanceof`: two installed copies of command-seam or
+ * result each have their own classes.
+ */
+function isGhFailure(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        isFailure(error.failure));
+}
+/** The failure a caught `CommandFailed` or `FailureError` stands for. */
+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 rather than recursing through the facade.
+            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);
+        },
+    });
+}
+/** Wrap a synchronous client so every method returns a `Result<T, GhFailure>`. */
+export function triedSync(client) {
+    return facade(client, (call) => {
+        try {
+            return ok(call());
+        }
+        catch (error) {
+            if (isGhFailure(error))
+                return err(failureOf(error));
+            throw error;
+        }
+    });
+}
+/** 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;
+        }
+    });
+}
+function checkSoft(name) {
+    if (!SOFT_METHODS.includes(name)) {
+        throw new TypeError(`gh.soft.${name} has no soft form; call it through gh.try (or the plain method) instead`);
+    }
+}
+/** Wrap a synchronous client so a failed query returns `null`. */
+export function softSync(client) {
+    return facade(client, (call, name) => {
+        checkSoft(name);
+        try {
+            return call();
+        }
+        catch (error) {
+            if (isGhFailure(error))
+                return null;
+            throw error;
+        }
+    });
+}
+/** Wrap an awaitable client so a failed query resolves to `null`. */
+export function softAsync(client) {
+    return facade(client, async (call, name) => {
+        checkSoft(name);
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (isGhFailure(error))
+                return null;
+            throw error;
+        }
+    });
+}

package/dist/failure.d.ts

@@ -0,0 +1,59 @@
+/**
+ * {@link GhFailure}: a failed `gh` call, classified. The `gh.try.*` door
+ * returns it as the error of a `Result`; its `cause` is the `CommandFailed`
+ * it was read from.
+ *
+ * The kinds beyond the subprocess layer's come from `gh`'s stderr, matched in
+ * English. A message that matches none stays the subprocess layer's `exit`
+ * with `gh`'s first stderr line, never a wrong kind.
+ */
+import { type CommandFailed, type CommandFailureKind } from '@osdlc/command-seam';
+import { type Failure } from '@osdlc/result';
+/**
+ * Why a `gh` call failed:
+ *
+ * - everything `@osdlc/command-seam` reports (`not-installed`, `not-executable`,
+ *   `bad-cwd`, `timeout`, `output-cap`, `signal`, `aborted`, `spawn`, `exit`);
+ * - `not-authenticated`: `gh` has no usable credentials, or GitHub refused
+ *   them ("gh auth login", "HTTP 401", "HTTP 403", "Bad credentials"). A 403 that
+ *   is a rate limit stays `rate-limited`;
+ * - `network`: GitHub could not be reached ("error connecting to
+ *   api.github.com", "Could not resolve host", "dial tcp", "i/o timeout");
+ * - `not-found`: GitHub has no such thing, or hides it ("Could not resolve to a
+ *   PullRequest", "HTTP 404", "no pull requests found for branch");
+ * - `rate-limited`: "API rate limit exceeded", "secondary rate limit", "HTTP 429";
+ * - `unreadable`: `gh` exited 0 but its output could not be read completely
+ *   (malformed JSON, a partial GraphQL answer, a review-thread list cut short).
+ */
+export type GhFailureKind = CommandFailureKind | 'not-authenticated' | 'network' | 'not-found' | 'rate-limited' | 'unreadable';
+/** A failed `gh` call. `message` is one line for a person; `detail` is `gh`'s own output. */
+export interface GhFailure extends Failure<GhFailureKind> {
+    /** The binary that ran (`gh`), when known. */
+    binary?: string | undefined;
+    /** The arguments `gh` ran with, without the binary name. */
+    argv: string[];
+    /** `gh`'s exit code; `null` when it never reported one. */
+    exitCode: number | null;
+    /** The signal that ended `gh`, when the runner knows it. */
+    signal?: NodeJS.Signals | null | undefined;
+    /** The `CommandFailed` this was classified from; absent for `unreadable`, where `gh` succeeded. */
+    cause?: CommandFailed | undefined;
+}
+/** What a verb that reads one thing asks GitHub for. */
+export type Thing = 'pr' | 'issue' | 'repo';
+/**
+ * Whether the text of a failed `gh` run (stderr then stdout, as
+ * {@link classifyGhFailure} reads it) means "there is no such `thing`", for a
+ * verb that reads one thing: an answer, not a failure.
+ *
+ * Narrower than the `not-found` failure kind on purpose. A mistyped `--repo`
+ * makes `gh pr view 7` say "Could not resolve to a Repository", which is a
+ * wrong repository rather than a missing pull request, so it is a `not-found`
+ * failure and not absence. Likewise a bare `HTTP 404` does not say which part
+ * of the request was missing.
+ */
+export declare function isAbsent(thing: Thing, text: string): boolean;
+/** The gh failure for a failed `gh` run. */
+export declare function classifyGhFailure(failed: CommandFailed): GhFailure;
+/** The failure for a run that exited 0 but whose output the verb could not read. */
+export declare function unreadableFailure(argv: readonly string[], stdout: string, binary: string | undefined): GhFailure;

package/dist/failure.js

@@ -0,0 +1,93 @@
+/**
+ * {@link GhFailure}: a failed `gh` call, classified. The `gh.try.*` door
+ * returns it as the error of a `Result`; its `cause` is the `CommandFailed`
+ * it was read from.
+ *
+ * The kinds beyond the subprocess layer's come from `gh`'s stderr, matched 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 {} 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;
+const NOT_AUTHENTICATED = /gh auth login|HTTP 401|HTTP 403|Bad credentials|authentication required|not logged in/i;
+const NETWORK = /error connecting to|Could not resolve host|no such host|dial tcp|i\/o timeout|network is unreachable|connection refused/i;
+const NOT_FOUND = /Could not resolve to an? [A-Za-z]+|HTTP 404|no pull requests found for branch|\(HTTP 404\)|Not Found/;
+const ABSENT = {
+    pr: /Could not resolve to a PullRequest|no pull requests found for branch/,
+    issue: /Could not resolve to an Issue/,
+    repo: /Could not resolve to a Repository/,
+};
+/**
+ * Whether the text of a failed `gh` run (stderr then stdout, as
+ * {@link classifyGhFailure} reads it) means "there is no such `thing`", for a
+ * verb that reads one thing: an answer, not a failure.
+ *
+ * Narrower than the `not-found` failure kind on purpose. A mistyped `--repo`
+ * makes `gh pr view 7` say "Could not resolve to a Repository", which is a
+ * wrong repository rather than a missing pull request, so it is a `not-found`
+ * failure and not absence. Likewise a bare `HTTP 404` does not say which part
+ * of the request was missing.
+ */
+export function isAbsent(thing, text) {
+    return ABSENT[thing].test(text);
+}
+/** The gh failure for a failed `gh` run. */
+export function classifyGhFailure(failed) {
+    // The client's runner may not name its binary; this 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')
+        return base;
+    const text = `${failed.result.stderr}\n${failed.result.stdout}`;
+    if (RATE_LIMITED.test(text)) {
+        return {
+            ...base,
+            kind: 'rate-limited',
+            message: "GitHub's API rate limit was reached.",
+            hint: 'Wait a few minutes and try again.',
+        };
+    }
+    if (NOT_AUTHENTICATED.test(text)) {
+        return {
+            ...base,
+            kind: 'not-authenticated',
+            message: 'gh is not signed in to GitHub.',
+            hint: 'Run `gh auth login`.',
+        };
+    }
+    if (NETWORK.test(text)) {
+        return {
+            ...base,
+            kind: 'network',
+            message: 'GitHub could not be reached.',
+            hint: 'Check your network connection.',
+        };
+    }
+    if (NOT_FOUND.test(text)) {
+        return {
+            ...base,
+            kind: 'not-found',
+            message: 'GitHub has no such pull request, issue or repository, or you cannot see it.',
+            hint: 'Check the number or name, and that your account can see the repository.',
+        };
+    }
+    return base;
+}
+/** The failure for a run that exited 0 but whose output the verb could not read. */
+export function unreadableFailure(argv, stdout, binary) {
+    return {
+        kind: 'unreadable',
+        message: 'gh answered, but its output could not be read completely.',
+        ...(stdout.trim() === '' ? {} : { detail: stdout.trim().slice(0, 2000) }),
+        binary: binary ?? 'gh',
+        argv: [...argv],
+        exitCode: 0,
+    };
+}

package/dist/index.d.ts

@@ -11,16 +11,21 @@
  *   - **Pure argv builders and parsers.** The verb table and `parse.ts` never
  *     spawn anything, so an async fan-out drives them through its own runner
  *     without duplicating a line of parsing.
- *   - **A client.** `Gh`, tri-modal like `Git`: queries return parsed values
- *     and never throw, mutations throw `CommandFailed`, `raw` is the hatch.
+ *   - **A client.** `Gh`, with `Git`'s three doors: the plain method returns a
+ *     value or throws a `FailureError` carrying the classified
+ *     `GhFailure`; `gh.try.*` returns a
+ *     `Result<T, GhFailure>`; `gh.soft.*` returns `null` for a failed query.
+ *     `raw` is the hatch.
  *
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */
 export { AsyncGh, type AsyncCallOptions, type AsyncGhOptions } from './async.ts';
+export { classifyGhFailure, type GhFailure, type GhFailureKind } from './failure.ts';
+export { type Soft, type TriedAsync, type TriedSync } from './doors.ts';
+export { runVerb, runVerbAsync, type RunVerbAsyncOptions, type RunVerbOptions } from './run.ts';
 export { Gh, defaultRunnerFactory, type GhOptions, type RunnerFactory } from './sync.ts';
 export { api, authStatus, createPr, editPr, editPrBody, graphql, createLabel, createReview, editLabel, installed, issueList, issueView, labelList, nodesAt, openPrsForBranch, pickPrForBranch, prBody, prComment, prSetDraft, issueCommentEdit, prDiff, prList, prMerge, prReviewThreads, prUpdateBranch, prView, repoList, repoView, searchPrs, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, REPO_FIELDS, SEARCH_PR_FIELDS, type ApiOptions, type ApiResponse, type AuthStatus, type CreateLabelOptions, type CreatePrOptions, type CreateReviewOptions, type GhTarget, type GraphqlOptions, type GraphqlVariable, type GhVerb, type IssueListOptions, type ListResult, type PrListOptions, type PrMergeMethod, type RepoListOptions, type ReviewComment, type ReviewThread, type SearchPrsOptions, } from './verbs.ts';
 export { anyCheckFailed, normalizeAuthorLogin, parsePullRequest } from './parse.ts';
 export { ownerRepoSlug, parseOwnerRepo, parsePrRef, parsePrUrl, type PrRef, type PullRequestRef, } from './repo.ts';
 export type { Actor, CheckConclusion, CheckRun, Comment, IssueRow, Label, MergeableState, MergeStateStatus, OwnerRepo, PullRequest, PrSearchHit, PullRequestState, Repository, RepositoryVisibility, Review, ReviewDecision, ReviewState, } from './types.ts';
 export { CommandFailed, type AsyncCommandRunner, type CommandResult, type CommandRunner, type CommandRunOptions, } from '@osdlc/command-seam';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -11,12 +11,18 @@
  *   - **Pure argv builders and parsers.** The verb table and `parse.ts` never
  *     spawn anything, so an async fan-out drives them through its own runner
  *     without duplicating a line of parsing.
- *   - **A client.** `Gh`, tri-modal like `Git`: queries return parsed values
- *     and never throw, mutations throw `CommandFailed`, `raw` is the hatch.
+ *   - **A client.** `Gh`, with `Git`'s three doors: the plain method returns a
+ *     value or throws a `FailureError` carrying the classified
+ *     `GhFailure`; `gh.try.*` returns a
+ *     `Result<T, GhFailure>`; `gh.soft.*` returns `null` for a failed query.
+ *     `raw` is the hatch.
  *
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */
 export { AsyncGh } from "./async.js";
+export { classifyGhFailure } from "./failure.js";
+export {} from "./doors.js";
+export { runVerb, runVerbAsync } from "./run.js";
 export { Gh, defaultRunnerFactory } from "./sync.js";
 export { api, authStatus, createPr, editPr, editPrBody, graphql, createLabel, createReview, editLabel, installed, issueList, issueView, labelList, nodesAt, openPrsForBranch, pickPrForBranch, prBody, prComment, prSetDraft, issueCommentEdit, prDiff, prList, prMerge, prReviewThreads, prUpdateBranch, prView, repoList, repoView, searchPrs, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, REPO_FIELDS, SEARCH_PR_FIELDS, } from "./verbs.js";
 export { anyCheckFailed, normalizeAuthorLogin, parsePullRequest } from "./parse.js";

package/dist/parse.d.ts

@@ -47,4 +47,3 @@ export declare function parsePullRequest(raw: unknown): PullRequest | null;
 export declare function parseRepository(raw: unknown): Repository | null;
 /** A `gh search prs --json` row as a {@link PrSearchHit}, or null without a `number`. */
 export declare function parsePrSearchHit(raw: unknown): PrSearchHit | null;
-//# sourceMappingURL=parse.d.ts.map

package/dist/repo.d.ts

@@ -65,4 +65,3 @@ export type PrRef = {
 export declare function parsePrRef(input: string): PrRef | null;
 /** True for `owner/name` as GitHub spells it. */
 export declare function isRepoSlug(text: string): boolean;
-//# sourceMappingURL=repo.d.ts.map