@osdlc/typed-gh 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @osdlc/typed-gh
 
+## 0.9.0
+
+### Minor Changes
+
+- cc2abe4: `api` now keeps GitHub's error body when a request fails. `body` is parsed even when gh exits with an error, and a new `message` field holds `body.message`. `ApiResponse` gains this `message` field as required. `malformed` is now also set when a failed call prints something that is not JSON. The docs now say that `status` is only filled in when headers were requested.
+
+### Patch Changes
+
+- 72f5049: `prList` always requests the `number` field. Before, a `fields` list without `number` returned no rows.
+- Updated dependencies [b5aac07]
+- Updated dependencies [41ef520]
+  - @osdlc/typed-git@0.7.0
+
+## 0.8.0
+
+### Minor Changes
+
+- ae400e5: Added `runVerb` and `runVerbAsync`, with `RunVerbOptions` and `RunVerbAsyncOptions`. They run one verb through a runner the caller owns and apply what the verb carries: `env` (the target host, as `GH_HOST`, for `repoList` and `searchPrs`), `input` (the payload `createReview` sends on stdin), `timeoutMs` and the checked contract. Running `verb.parse(await run(verb.argv))` yourself dropped `env` and `input` without an error. `Gh` and `AsyncGh` now call them, so there is one copy of that logic.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -357,6 +357,25 @@ const result = await runner.run(verb.argv, { cwd: '/repo', timeoutMs: 5_000 })
 const prs = verb.parse(result)
 ```
 
+That is only safe for a verb with no `env` or `input`. `repoList` and `searchPrs` send the target
+host as `GH_HOST` (`env`), and `createReview` sends its payload on stdin (`input`); a runner call
+that passes only `verb.argv` drops both, silently: the query goes to github.com, and the review is
+never sent. `runVerb` (and `runVerbAsync`, for an `AsyncCommandRunner`) run a verb the way `Gh` and
+`AsyncGh` do, with `cwd`, `env`, `input`, `timeoutMs` and the checked contract applied, and return
+the parsed value or throw the classified failure:
+
+```ts
+import { repoList, runVerbAsync } from '@osdlc/typed-gh'
+
+const repos = await runVerbAsync(repoList('acme', {}, { hostname: 'ghe.example.com' }), runner, {
+  cwd: '/repo',
+  timeoutMs: 5_000,
+})
+```
+
+They take a `CommandRunner`. A plain `(binary, argv, opts) => result` function is wrapped as
+`{ run: (argv, opts) => fn('gh', argv, opts) }`.
+
 ## `AsyncGh`
 
 The awaitable form of `Gh`, with the same methods, for a fan-out that must not block the event loop.
@@ -382,7 +401,8 @@ These methods take `AsyncCallOptions`: `raw`, `rawChecked`, `prList`, `prView`,
 `signal`.
 
 `api(endpoint, opts)` (on `Gh` and `AsyncGh`) is a REST GET through `gh api`.
-It never throws; the result is `{ ok, status, etag, body, malformed, stderr, error? }`.
+It never throws; the result is `{ ok, status, etag, body, message, malformed, stderr, error? }`.
+On failure `body` still carries GitHub's error object and `message` its text; `status` is only observed when headers were requested (`etag` or `includeHeaders`).
 `stderr` is gh's own; `error` holds the runner's message when gh never ran or
 was stopped (a missing binary, a timeout).
 Pass `etag` for a conditional request (`If-None-Match`; a 304 comes back as
@@ -462,6 +482,8 @@ experimental.
 - `GhOptions` and `AsyncGhOptions`: the runner, `repo` and `hostname` a client is built with.
 - `AsyncCallOptions`: `timeoutMs` and `signal`, accepted by sixteen methods of `AsyncGh`.
 - `defaultRunnerFactory` and `RunnerFactory`: how a client makes its default runner for `gh`.
+- `runVerb` and `runVerbAsync`, with `RunVerbOptions` and `RunVerbAsyncOptions`: run one verb through
+  a runner you own, with its `env`, `input`, timeout and checked contract applied.
 
 Methods on both clients:
 

package/dist/async.js

@@ -10,7 +10,8 @@
  * sync client would block the event loop: a fan-out of per-PR queries.
  */
 import { resolveRunnerAsync, } from '@osdlc/command-seam';
-import { runCheckedGhAsync, settle, softAsync, triedAsync, } from "./doors.js";
+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. */
@@ -66,19 +67,11 @@ export class AsyncGh {
     }
     /** 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 runCheckedGhAsync(this.runner, verb.argv, opts)
-            : await this.runner.run(verb.argv, opts);
-        return settle(verb, result, this.runner.binary);
+        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 = {}) {

package/dist/index.d.ts

@@ -22,6 +22,7 @@
 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';

package/dist/index.js

@@ -22,6 +22,7 @@
 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/run.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `runVerb` and `runVerbAsync` — run one {@link GhVerb} through a runner the
+ * caller owns, with everything the verb asks for applied.
+ *
+ * A verb carries more than `argv`: `input` (a payload on stdin), `env` (the
+ * target host as `GH_HOST`), and `checked` (whether a non-zero exit throws).
+ * `verb.parse(await runner.run(verb.argv))` drops the first two without a
+ * word, so a query goes to github.com and a review is never sent. These two
+ * apply all of it, as `Gh` and `AsyncGh` do; both clients call them.
+ */
+import type { AsyncCommandRunner, CommandRunner } from '@osdlc/command-seam';
+import type { GhVerb } from './verbs.ts';
+/** What a verb run is given besides the verb: the directory and the cap on the call. */
+export interface RunVerbOptions {
+    cwd: string;
+    /** Hard cap on the call, as in command-seam. */
+    timeoutMs?: number | undefined;
+}
+/** {@link RunVerbOptions} for {@link runVerbAsync}, with the abort signal. */
+export interface RunVerbAsyncOptions extends RunVerbOptions {
+    /** Aborts the call; the runner stops the child. */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Run `verb` through `runner` and return its parsed value, honouring the
+ * verb's `input`, `env`, `timeoutMs` and `checked`, and its checked or
+ * unchecked contract: 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 answers `null` when GitHub says
+ * there is no such thing.
+ *
+ * A plain `(binary, argv, opts) => result` function is not a runner: wrap it
+ * as `{ run: (argv, opts) => fn('gh', argv, opts) }`.
+ */
+export declare function runVerb<T>(verb: GhVerb<T>, runner: CommandRunner, opts: RunVerbOptions): T;
+/** {@link runVerb} for an `AsyncCommandRunner`; rejects where that throws. */
+export declare function runVerbAsync<T>(verb: GhVerb<T>, runner: AsyncCommandRunner, opts: RunVerbAsyncOptions): Promise<T>;

package/dist/run.js

@@ -0,0 +1,49 @@
+/**
+ * `runVerb` and `runVerbAsync` — run one {@link GhVerb} through a runner the
+ * caller owns, with everything the verb asks for applied.
+ *
+ * A verb carries more than `argv`: `input` (a payload on stdin), `env` (the
+ * target host as `GH_HOST`), and `checked` (whether a non-zero exit throws).
+ * `verb.parse(await runner.run(verb.argv))` drops the first two without a
+ * word, so a query goes to github.com and a review is never sent. These two
+ * apply all of it, as `Gh` and `AsyncGh` do; both clients call them.
+ */
+import { runCheckedGh, runCheckedGhAsync, settle } from "./doors.js";
+/**
+ * Run `verb` through `runner` and return its parsed value, honouring the
+ * verb's `input`, `env`, `timeoutMs` and `checked`, and its checked or
+ * unchecked contract: 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 answers `null` when GitHub says
+ * there is no such thing.
+ *
+ * A plain `(binary, argv, opts) => result` function is not a runner: wrap it
+ * as `{ run: (argv, opts) => fn('gh', argv, opts) }`.
+ */
+export function runVerb(verb, runner, opts) {
+    const run = { cwd: opts.cwd };
+    if (verb.input !== undefined)
+        run.input = verb.input;
+    if (verb.env !== undefined)
+        run.env = verb.env;
+    if (opts.timeoutMs !== undefined)
+        run.timeoutMs = opts.timeoutMs;
+    const result = verb.checked ? runCheckedGh(runner, verb.argv, run) : runner.run(verb.argv, run);
+    return settle(verb, result, runner.binary);
+}
+/** {@link runVerb} for an `AsyncCommandRunner`; rejects where that throws. */
+export async function runVerbAsync(verb, runner, opts) {
+    const run = { cwd: opts.cwd };
+    if (verb.input !== undefined)
+        run.input = verb.input;
+    if (verb.env !== undefined)
+        run.env = verb.env;
+    if (opts.timeoutMs !== undefined)
+        run.timeoutMs = opts.timeoutMs;
+    if (opts.signal !== undefined)
+        run.signal = opts.signal;
+    const result = verb.checked
+        ? await runCheckedGhAsync(runner, verb.argv, run)
+        : await runner.run(verb.argv, run);
+    return settle(verb, result, runner.binary);
+}

package/dist/sync.js

@@ -15,7 +15,8 @@
  * `null` for it. `raw`/`rawChecked` are the escape hatches.
  */
 import { resolveRunner, spawnRunner, } from '@osdlc/command-seam';
-import { runCheckedGh, settle, softSync, triedSync } from "./doors.js";
+import { runCheckedGh, softSync, triedSync } from "./doors.js";
+import { runVerb } from "./run.js";
 import * as v from "./verbs.js";
 import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
 /** Default factory: real, spawnSync-backed runners. */
@@ -92,17 +93,7 @@ export class Gh {
     }
     /** Run one verb from the table, honouring its checked/unchecked contract. */
     exec(verb, timeoutMs) {
-        const opts = { cwd: this.cwd };
-        if (verb.input !== undefined)
-            opts.input = verb.input;
-        if (verb.env !== undefined)
-            opts.env = verb.env;
-        if (timeoutMs !== undefined)
-            opts.timeoutMs = timeoutMs;
-        const result = verb.checked
-            ? runCheckedGh(this.runner, verb.argv, opts)
-            : this.runner.run(verb.argv, opts);
-        return settle(verb, result, this.runner.binary);
+        return runVerb(verb, this.runner, { cwd: this.cwd, timeoutMs });
     }
     /** {@link exec} for a verb that never answers `null` as a value: a failed or unreadable run throws. */
     read(verb, timeoutMs) {

package/dist/verbs.d.ts

@@ -120,7 +120,7 @@ export interface PrListOptions {
     search?: string | undefined;
     author?: string | undefined;
     limit?: number | undefined;
-    /** Field subset; defaults to {@link PR_LIST_FIELDS}. */
+    /** Field subset; defaults to {@link PR_LIST_FIELDS}. `number` is always requested. */
     fields?: readonly string[] | undefined;
 }
 /** `gh pr list …` — open PRs by default. `opts.repo` overrides the target's repo. */
@@ -153,13 +153,15 @@ export declare function prBody(number: number, target?: GhTarget): GhVerb<string
 export interface ApiResponse {
     /** True iff gh exited 0 and the status is below 400 (2xx, or a 304 on a conditional GET). */
     ok: boolean;
-    /** HTTP status; read off the header block under `-i`. Without `-i` it is synthesized (200 on exit 0, 0 on failure), not observed. */
+    /** HTTP status; set only when headers were requested (`-i`, `etag` or `includeHeaders`). Without them it is synthesized (200 on exit 0, 0 on failure), not observed. */
     status: number;
     /** The response `ETag`, when headers were requested and one came back. */
     etag: string | null;
-    /** The decoded JSON body; null when empty (e.g. a 304), unparseable, or the call failed. */
+    /** The decoded JSON body, whatever gh's exit code (on failure, GitHub's error object); null when empty (e.g. a 304) or unparseable. */
     body: unknown;
-    /** True when a non-empty body arrived but was not valid JSON (`body` is then null). */
+    /** `body.message` when the body is an object with a string `message` (GitHub's error text), else null. */
+    message: string | null;
+    /** True when a non-empty body arrived but was not valid JSON (`body` is then null); also true on a failed call with a non-JSON body. */
     malformed: boolean;
     /** gh's stderr, trimmed. */
     stderr: string;

package/dist/verbs.js

@@ -251,9 +251,12 @@ export function prList(opts = {}, target) {
         argv.push('--search', opts.search);
     if (opts.author !== undefined)
         argv.push('--author', opts.author);
-    // The exact-head filter below reads `headRefName`, so ask for it.
-    const fields = opts.fields ?? PR_LIST_FIELDS;
-    const asked = opts.head === undefined ? fields : withFields(fields, ['headRefName']);
+    // A row without `number` does not parse and is dropped, so always ask for it;
+    // the exact-head filter below also reads `headRefName`.
+    const asked = withFields(opts.fields ?? PR_LIST_FIELDS, [
+        'number',
+        ...(opts.head === undefined ? [] : ['headRefName']),
+    ]);
     argv.push('--json', asked.join(','));
     argv.push('--limit', String(limit + 1));
     const head = opts.head;
@@ -516,7 +519,7 @@ function parseApi(r, withHeaders) {
     }
     let body = null;
     let malformed = false;
-    if (r.exitCode === 0 && bodyText.trim() !== '') {
+    if (bodyText.trim() !== '') {
         try {
             body = JSON.parse(bodyText);
         }
@@ -525,11 +528,15 @@ function parseApi(r, withHeaders) {
         }
     }
     const ok = r.exitCode === 0 && status >= 200 && status < 400;
+    const rawMessage = body !== null && typeof body === 'object' && !Array.isArray(body)
+        ? body['message']
+        : undefined;
     return {
         ok,
         status,
         etag,
         body,
+        message: typeof rawMessage === 'string' ? rawMessage : null,
         malformed,
         stderr: r.stderr.trim(),
         ...(r.error === undefined ? {} : { error: r.error }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.7.0",
+  "version": "0.9.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",
@@ -22,8 +22,8 @@
     "LICENSE-APACHE"
   ],
   "dependencies": {
-    "@osdlc/command-seam": "^0.9.0",
-    "@osdlc/typed-git": "^0.6.0",
+    "@osdlc/command-seam": "^0.9.1",
+    "@osdlc/typed-git": "^0.7.0",
     "@osdlc/result": "^0.1.0"
   },
   "engines": {