@osdlc/typed-gh 0.6.0 → 0.7.0

package/dist/sync.js

@@ -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 { runChecked, resolveRunner, spawnRunner, } from '@osdlc/command-seam';
+import { resolveRunner, spawnRunner, } from '@osdlc/command-seam';
+import { runCheckedGh, settle, softSync, triedSync } from "./doors.js";
 import * as v from "./verbs.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
 /** Default factory: real, spawnSync-backed runners. */
@@ -38,6 +42,8 @@ export class Gh {
     hostname;
     target;
     runner;
+    tried;
+    softened;
     constructor(cwd, opts = {}) {
         v.checkTarget(opts);
         this.cwd = cwd;
@@ -54,14 +60,35 @@ export class Gh {
     withRepo(repo) {
         return new Gh(this.cwd, { runner: this.runner, repo, hostname: this.hostname });
     }
+    /**
+     * 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() {
+        return (this.tried ??= triedSync(this));
+    }
+    /**
+     * 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() {
+        return (this.softened ??= softSync(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 — throws `CommandFailed` on a non-zero exit. */
+    /** Checked passthrough — throws the classified failure on a non-zero exit. */
     rawChecked(argv, opts = {}) {
-        return runChecked(this.runner, argv, { cwd: this.cwd, ...opts });
+        return runCheckedGh(this.runner, argv, { cwd: this.cwd, ...opts });
     }
     /** Run one verb from the table, honouring its checked/unchecked contract. */
     exec(verb, timeoutMs) {
@@ -73,18 +100,22 @@ export class Gh {
         if (timeoutMs !== undefined)
             opts.timeoutMs = timeoutMs;
         const result = verb.checked
-            ? runChecked(this.runner, verb.argv, opts)
+            ? runCheckedGh(this.runner, verb.argv, opts)
             : this.runner.run(verb.argv, opts);
-        return verb.parse(result);
+        return settle(verb, result, this.runner.binary);
+    }
+    /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run throws. */
+    read(verb, timeoutMs) {
+        return this.exec(verb, timeoutMs);
     }
     // ── queries ───────────────────────────────────────────────────────────────
-    /** Pull requests matching `opts`, or null when gh failed. */
+    /** Pull requests matching `opts`. Throws when gh fails; `soft.prList` gives null instead. */
     prList(opts = {}) {
-        return this.exec(v.prList(opts, this.target), opts.timeoutMs);
+        return this.read(v.prList(opts, this.target), opts.timeoutMs);
     }
     /**
-     * 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, opts = {}) {
         return this.exec(v.prView(ref, opts.fields ?? v.PR_VIEW_FIELDS, this.target), opts.timeoutMs);
@@ -128,7 +159,7 @@ export class Gh {
             limit: opts.limit ?? 5,
             fields: opts.fields ?? v.PR_REF_FIELDS,
         });
-        return v.pickPrForBranch(rows?.rows ?? null, branch);
+        return v.pickPrForBranch(rows.rows, branch);
     }
     /**
      * {@link prView}, re-asked until GitHub settles the merge state.
@@ -155,49 +186,49 @@ export class Gh {
         }
         return last;
     }
-    /** A PR's body text, or null when gh failed. */
+    /** A PR's body text. Throws when gh fails. */
     prBody(number, opts = {}) {
-        return this.exec(v.prBody(number, this.target), opts.timeoutMs);
+        return this.read(v.prBody(number, this.target), opts.timeoutMs);
     }
     /**
-     * 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, opts = {}) {
         return this.exec(v.api(endpoint, opts, this.target), opts.timeoutMs);
     }
     /**
-     * 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, variables = {}, opts = {}) {
-        return this.exec(v.graphql(query, variables, opts, this.target), opts.timeoutMs);
+        return this.read(v.graphql(query, variables, opts, this.target), opts.timeoutMs);
     }
-    /** 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). Throws when gh fails. */
     labelList(opts = {}) {
-        return this.exec(v.labelList(opts, this.target), opts.timeoutMs);
+        return this.read(v.labelList(opts, this.target), opts.timeoutMs);
     }
-    /** Issues matching `opts` (open by default, up to 200), or null when gh failed. */
+    /** Issues matching `opts` (open by default, up to 200). Throws when gh fails. */
     issueList(opts = {}) {
-        return this.exec(v.issueList(opts, this.target), opts.timeoutMs);
+        return this.read(v.issueList(opts, this.target), opts.timeoutMs);
     }
-    /** One issue with its labels, or null when gh failed. */
+    /** One issue with its labels; null when there is no such issue. Throws when gh fails otherwise. */
     issueView(number, opts = {}) {
         return this.exec(v.issueView(number, this.target), opts.timeoutMs);
     }
-    /** 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, opts = {}) {
-        return this.exec(v.repoList(owner, opts, this.target), opts.timeoutMs);
+        return this.read(v.repoList(owner, opts, this.target), opts.timeoutMs);
     }
-    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when gh failed. */
+    /** One repository: `repo`, else the client's repo, else the clone at `cwd`. Null when there is no such repository. */
     repoView(repo, opts = {}) {
         return this.exec(v.repoView(repo, opts.fields ?? v.REPO_FIELDS, this.target), opts.timeoutMs);
     }
-    /** 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, opts = {}) {
-        return this.exec(v.searchPrs(query, opts, this.target), opts.timeoutMs);
+        return this.read(v.searchPrs(query, opts, this.target), opts.timeoutMs);
     }
     /** True iff the `gh` binary is on PATH and runs. */
     installed() {
@@ -242,7 +273,7 @@ export class Gh {
     editPr(number, opts) {
         this.exec(v.editPr(number, opts, this.target));
     }
-    /** 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) {
         return this.exec(v.prDiff(number, this.target));
     }
@@ -282,9 +313,9 @@ export class Gh {
     prMerge(number, opts) {
         this.exec(v.prMerge(number, opts, this.target));
     }
-    /** A PR's review threads, or null when they could not be read completely. */
+    /** A PR's review threads. Throws 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 already exists). */
     createLabel(opts) {

package/dist/types.d.ts

@@ -186,4 +186,3 @@ export interface PrSearchHit {
     updatedAt: string | null;
     closedAt: string | null;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/verbs.d.ts

@@ -7,9 +7,12 @@
  * asynchronous fan-out drive the same definitions without either duplicating
  * the other's parsing.
  *
- * `checked` marks a verb whose failure is thrown with stderr: every mutation,
- * and `prDiff`, which is a read. Other queries are unchecked and fold failure
- * into an absence value.
+ * `checked` marks a verb the runner throws for on a non-zero exit, with
+ * stderr: every mutation, and `prDiff`, which is a read. Other queries are run
+ * unchecked and `parse` folds a failure into `null`, which is the verb's
+ * *soft* reading. The clients' plain door reads them through `settle` (see
+ * `doors.ts`) instead: a failure throws, except where the verb declares
+ * `absent` or is a `probe`.
  */
 import { type CommandResult } from '@osdlc/command-seam';
 import type { IssueRow, Label, PrSearchHit, PullRequest, Repository } from './types.ts';
@@ -31,6 +34,19 @@ export interface GhVerb<T> {
      * on `gh search` and `gh repo list`.
      */
     env?: Record<string, string> | undefined;
+    /**
+     * True for a read whose failure is part of its answer: `installed`,
+     * `authStatus` and `api` return what `parse` makes of any result, in every
+     * door. Other reads fail the plain door when gh exits non-zero.
+     */
+    probe?: boolean | undefined;
+    /**
+     * For a read of one thing: whether a non-zero result means GitHub has no such
+     * thing (`prView`, `issueView`, `repoView`). The plain door then returns what
+     * `parse` makes of it, `null`, because absence is an answer. Other non-zero
+     * results fail the call.
+     */
+    absent?: ((result: CommandResult) => boolean) | undefined;
     parse(result: CommandResult): T;
 }
 /**
@@ -461,4 +477,3 @@ export declare function branchPrFields(fields: readonly string[]): string[];
  * slow, so re-ask a few times before believing it.
  */
 export declare function needsMergeStateRetry(pr: PullRequest): boolean;
-//# sourceMappingURL=verbs.d.ts.map

package/dist/verbs.js

@@ -7,13 +7,21 @@
  * asynchronous fan-out drive the same definitions without either duplicating
  * the other's parsing.
  *
- * `checked` marks a verb whose failure is thrown with stderr: every mutation,
- * and `prDiff`, which is a read. Other queries are unchecked and fold failure
- * into an absence value.
+ * `checked` marks a verb the runner throws for on a non-zero exit, with
+ * stderr: every mutation, and `prDiff`, which is a read. Other queries are run
+ * unchecked and `parse` folds a failure into `null`, which is the verb's
+ * *soft* reading. The clients' plain door reads them through `settle` (see
+ * `doors.ts`) instead: a failure throws, except where the verb declares
+ * `absent` or is a `probe`.
  */
 import { stderrOrError } from '@osdlc/command-seam';
 import { parseLabels, parsePrSearchHit, parsePullRequest, parseRepository } from "./parse.js";
+import { isAbsent } from "./failure.js";
 import { isRepoSlug, parsePrUrl } from "./repo.js";
+/** Whether a failed run says GitHub has no such `thing`: read from the same text the classifier reads. */
+function noSuch(thing) {
+    return (r) => isAbsent(thing, `${r.stderr}\n${r.stdout}`);
+}
 const HOSTNAME = /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?(?::\d+)?$/;
 /**
  * Throw `RangeError` unless `target.repo` is `owner/name` and
@@ -300,6 +308,7 @@ export function prView(ref, fields = PR_VIEW_FIELDS, target) {
         ],
         checked: false,
         readOnly: true,
+        absent: noSuch('pr'),
         parse: oneOrNull,
     };
 }
@@ -354,6 +363,7 @@ export function api(endpoint, opts = {}, target) {
         argv,
         checked: false,
         readOnly: true,
+        probe: true,
         parse(r) {
             const response = parseApi(r, withHeaders);
             return paginate ? { ...response, body: flattenPages(response.body) } : response;
@@ -527,7 +537,13 @@ function parseApi(r, withHeaders) {
 }
 /** `gh --version` — the install probe. True when `gh` runs. */
 export function installed() {
-    return { argv: ['--version'], checked: false, readOnly: true, parse: (r) => r.exitCode === 0 };
+    return {
+        argv: ['--version'],
+        checked: false,
+        readOnly: true,
+        probe: true,
+        parse: (r) => r.exitCode === 0,
+    };
 }
 /** `gh auth status [--hostname <host>]` — the credential probe, for one host when the target names it. */
 export function authStatus(target) {
@@ -535,6 +551,7 @@ export function authStatus(target) {
         argv: ['auth', 'status', ...hostArgs(target)],
         checked: false,
         readOnly: true,
+        probe: true,
         parse: (r) => ({ ok: r.exitCode === 0, detail: stderrOrError(r) || r.stdout.trim() }),
     };
 }
@@ -576,6 +593,7 @@ export function issueView(number, target) {
         argv: ['issue', 'view', String(number), ...repoArgs(target), '--json', ISSUE_FIELDS],
         checked: false,
         readOnly: true,
+        absent: noSuch('issue'),
         parse: oneIssueOrNull,
     };
 }
@@ -660,6 +678,7 @@ export function repoView(repo, fields = REPO_FIELDS, target) {
         argv,
         checked: false,
         readOnly: true,
+        absent: noSuch('repo'),
         parse(r) {
             if (r.exitCode !== 0)
                 return null;

package/package.json

@@ -1,26 +1,19 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "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",
   "type": "module",
   "sideEffects": false,
   "exports": {
     ".": {
-      "bun": "./index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }
   },
   "files": [
     "dist/",
-    "index.ts",
-    "sync.ts",
-    "async.ts",
-    "verbs.ts",
-    "parse.ts",
-    "repo.ts",
-    "types.ts",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",
@@ -29,11 +22,12 @@
     "LICENSE-APACHE"
   ],
   "dependencies": {
-    "@osdlc/typed-git": "^0.5.3",
-    "@osdlc/command-seam": "^0.8.0"
+    "@osdlc/command-seam": "^0.9.0",
+    "@osdlc/typed-git": "^0.6.0",
+    "@osdlc/result": "^0.1.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -54,22 +48,24 @@
     "dependency-injection"
   ],
   "devDependencies": {
-    "@types/bun": "^1.1.14",
     "@types/node": "^26.1.0",
+    "@vitest/coverage-v8": "^5.0.5",
     "oxlint": "^1.65.0",
     "prettier": "3.9.6",
     "typescript": "~6.0.3",
-    "@osdlc/prettier-config": "^0.3.0",
-    "@osdlc/tsconfig": "^0.4.0"
+    "vitest": "^5.0.5",
+    "@osdlc/prettier-config": "^0.3.1",
+    "@osdlc/tsconfig": "^0.4.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "test": "bun test",
+    "test": "vitest run",
     "smoke": "node tests/smoke.mjs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "oxlint .",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit"
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit",
+    "coverage": "vitest run --coverage"
   }
 }