@osdlc/typed-gh 0.6.0 → 0.7.0

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,20 @@
  *   - **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 { 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,17 @@
  *   - **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 { 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

package/dist/sync.d.ts

@@ -7,11 +7,15 @@
  * REST — the credential already exists in the user's keychain, and a library
  * that reaches for `GITHUB_TOKEN` is a library that can leak one.
  *
- * Tri-modal, same as the git client: queries return parsed values and never
- * throw, mutations throw `CommandFailed`, and `raw`/`rawChecked` are the
- * escape hatches.
+ * The same three doors as the git client. The plain method returns a value
+ * or throws: a failed `gh` throws a `FailureError` carrying the classified
+ * `GhFailure`, output that cannot be read throws one of kind `unreadable`, and a query for one thing (`prView`, `issueView`,
+ * `repoView`) answers `null` when GitHub says there is no such thing.
+ * `gh.try.*` returns the failure as a `Result<T, GhFailure>`; `gh.soft.*` returns
+ * `null` for it. `raw`/`rawChecked` are the escape hatches.
  */
 import { type CommandResult, type CommandRunner } from '@osdlc/command-seam';
+import { type Soft, type TriedSync } from './doors.ts';
 import * as v from './verbs.ts';
 import type { ApiOptions, ApiResponse, AuthStatus, GhTarget, IssueListOptions, ListResult, PrListOptions } from './verbs.ts';
 import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts';
@@ -47,28 +51,49 @@ export declare class Gh {
     readonly hostname: string | undefined;
     private readonly target;
     private readonly runner;
+    private tried;
+    private softened;
     constructor(cwd: string, opts?: GhOptions);
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd: string): Gh;
     /** The same client aimed at another repository (same runner, directory and host). */
     withRepo(repo: string): Gh;
+    /**
+     * The whole surface again, returning a `Result<T, GhFailure>` instead of
+     * throwing: `gh.try.prList()` is `{ ok: true, value } | { ok: false, error }`.
+     * A query for one thing that finds nothing is `ok: true` with `null`. See
+     * `./doors.ts`.
+     *
+     * The type leaves out the escape hatches and the pure helpers; at runtime
+     * the proxy wraps `raw` and `rawChecked` too. Call those on the client itself.
+     */
+    get try(): TriedSync<Gh>;
+    /**
+     * Each query again, returning `null` instead of throwing when `gh` fails. A
+     * mutation has no soft form. Do not gate a write on a `null` from `soft`:
+     * it is the answer for "could not ask" as well as for "nothing there". Use
+     * `try` where the difference matters.
+     */
+    get soft(): Soft<Gh>;
     /** Unchecked passthrough for verbs not yet lifted into the API. */
     raw(argv: string[], opts?: {
         timeoutMs?: number | undefined;
     }): CommandResult;
-    /** Checked passthrough — throws `CommandFailed` on a non-zero exit. */
+    /** Checked passthrough — throws the classified failure on a non-zero exit. */
     rawChecked(argv: string[], opts?: {
         timeoutMs?: number | undefined;
     }): CommandResult;
     /** Run one verb from the table, honouring its checked/unchecked contract. */
     private exec;
-    /** Pull requests matching `opts`, or null when gh failed. */
+    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run throws. */
+    private read;
+    /** Pull requests matching `opts`. Throws when gh fails; `soft.prList` gives null instead. */
     prList(opts?: PrListOptions & {
         timeoutMs?: number | undefined;
-    }): ListResult<PullRequest> | null;
+    }): ListResult<PullRequest>;
     /**
-     * One PR by number, branch or URL, with the heavy fields; null when gh
-     * failed or there is no such PR.
+     * One PR by number, branch or URL, with the heavy fields; null when there is
+     * no such PR. Throws when gh fails otherwise.
      */
     prView(ref: number | string, opts?: {
         fields?: readonly string[] | undefined;
@@ -119,52 +144,52 @@ export declare class Gh {
         sleep?: ((ms: number) => void) | undefined;
         timeoutMs?: number | undefined;
     }): PullRequest | null;
-    /** A PR's body text, or null when gh failed. */
+    /** A PR's body text. Throws when gh fails. */
     prBody(number: number, opts?: {
         timeoutMs?: number | undefined;
-    }): string | null;
+    }): string;
     /**
-     * A REST GET through `gh api`. Never throws: failure is `ok: false` on the
-     * returned {@link ApiResponse}.
+     * A REST GET through `gh api`. Never throws for a failed call, in any door:
+     * failure is `ok: false` on the returned {@link ApiResponse}.
      */
     api(endpoint: string, opts?: ApiOptions & {
         timeoutMs?: number | undefined;
     }): ApiResponse;
     /**
-     * A GraphQL query; each page's `data`, or null on a failed or partial
-     * result. See the `graphql` verb.
+     * A GraphQL query; each page's `data`. Throws on a failed or partial result;
+     * `soft.graphql` gives null. See the `graphql` verb.
      *
      * @experimental
      */
     graphql(query: string, variables?: Record<string, v.GraphqlVariable>, opts?: v.GraphqlOptions & {
         timeoutMs?: number | undefined;
-    }): unknown[] | null;
-    /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
+    }): unknown[];
+    /** Every label on the repository (up to `opts.limit`, default 1000). Throws when gh fails. */
     labelList(opts?: {
         limit?: number | undefined;
         timeoutMs?: number | undefined;
-    }): ListResult<Label> | null;
-    /** Issues matching `opts` (open by default, up to 200), or null when gh failed. */
+    }): ListResult<Label>;
+    /** Issues matching `opts` (open by default, up to 200). Throws when gh fails. */
     issueList(opts?: IssueListOptions & {
         timeoutMs?: number | undefined;
-    }): ListResult<IssueRow> | null;
-    /** One issue with its labels, or null when gh failed. */
+    }): ListResult<IssueRow>;
+    /** One issue with its labels; null when there is no such issue. Throws when gh fails otherwise. */
     issueView(number: number, opts?: {
         timeoutMs?: number | undefined;
     }): IssueRow | null;
-    /** An owner's repositories (up to `opts.limit`, default 100), or null when gh failed. */
+    /** An owner's repositories (up to `opts.limit`, default 100). Throws when gh fails. */
     repoList(owner: string, opts?: v.RepoListOptions & {
         timeoutMs?: number | undefined;
-    }): ListResult<Repository> | null;
-    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when gh failed. */
+    }): ListResult<Repository>;
+    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when there is no such repository. */
     repoView(repo?: string | undefined, opts?: {
         fields?: readonly string[] | undefined;
         timeoutMs?: number | undefined;
     }): Repository | null;
-    /** Pull requests across repositories matching a search query, or null when gh failed. */
+    /** Pull requests across repositories matching a search query. Throws when gh fails. */
     searchPrs(query: string, opts?: v.SearchPrsOptions & {
         timeoutMs?: number | undefined;
-    }): ListResult<PrSearchHit> | null;
+    }): ListResult<PrSearchHit>;
     /** True iff the `gh` binary is on PATH and runs. */
     installed(): boolean;
     /**
@@ -196,7 +221,7 @@ export declare class Gh {
         title?: string | undefined;
         body?: string | undefined;
     }): void;
-    /** The PR's unified diff; throws `CommandFailed` when gh cannot produce it. */
+    /** The PR's unified diff; throws the classified failure when gh cannot produce it. */
     prDiff(number: number): string;
     /** Post one conversation comment on a PR; returns its URL ('' if gh printed none). */
     prComment(number: number, body: string): string;
@@ -223,8 +248,8 @@ export declare class Gh {
         method: v.PrMergeMethod;
         headSha: string;
     }): void;
-    /** A PR's review threads, or null when they could not be read completely. */
-    prReviewThreads(number: number): v.ReviewThread[] | null;
+    /** A PR's review threads. Throws when they could not be read completely. */
+    prReviewThreads(number: number): v.ReviewThread[];
     /** Create a label (or force it to `opts`'s color/description if it already exists). */
     createLabel(opts: v.CreateLabelOptions): void;
     /** Recolor and/or redescribe an existing label. */
@@ -239,4 +264,3 @@ export declare class Gh {
      */
     setIssueLabel(number: number, currentLabel: string | null, newLabel: string): void;
 }
-//# sourceMappingURL=sync.d.ts.map