@osdlc/typed-gh 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @osdlc/typed-gh
 
+## 0.13.0
+
+### Minor Changes
+
+- 5598ee8: Author logins also drop the `app/` prefix that gh's `--json` export puts on a bot author (`{"is_bot":true,"login":"app/osdlc-release"}`). So `prList`/`prView`, REST (`osdlc-release[bot]`) and GraphQL (`osdlc-release`) all give the same `login`, and the prefix marks the author as a bot. `normalizeAuthorLogin` strips it too. **Breaking:** a caller that matched `app/<name>` on `author.login` now sees `<name>`. To filter by a bot with `prList({ author })`, pass `app/<login>` or `<login>[bot]`: gh's `--author` does not match the bare form.
+- 50a340a: `Gh` and `AsyncGh` take a second constructor form, `new Gh({ repo, hostname?, runner? })`, for a client that names a repository and needs no directory. `repo` is required in that form: `new Gh({})` does not typecheck and throws `TypeError`, so clone-relative use still names its directory. Each call runs in `process.cwd()`, read when the call is made. `cwd` is now a getter that returns that directory, still typed `readonly string`. `at(cwd)` on such a client gives one rooted at `cwd`, and `withRepo` keeps the form. `new Gh(cwd, options?)` is unchanged. New types `GhRepoOptions` and `AsyncGhRepoOptions` are `GhOptions` and `AsyncGhOptions` with `repo` required.
+  
+  `gh.cwd` is now a getter on the prototype rather than an own field. Reading it is unchanged. `{ ...gh }`, `Object.keys(gh)` and `JSON.stringify(gh)` no longer include it, and a subclass cannot redeclare it as a field. On a client built from `repo` alone, `raw`, `rawChecked` and an `api` endpoint's `{branch}` still read `process.cwd()`, as documented.
+  
+  Fixed: `repoView` treats `hostname: ''` as no host, as every other verb does. Before, it sent `/owner/name`.
+- 65740a9: `prList({ headPrefix })` lists every pull request whose head branch starts with a prefix such as `task/`. It sends a `head:<prefix>` search term, groups any `search` after it in parentheses so an `OR` there cannot escape the prefix, asks for `headRefName`, and filters the rows with `startsWith`. Callers no longer write that filter themselves. Because it goes through GitHub search, which returns at most 1000 results, a `limit` over 999 throws `RangeError`. It also throws when combined with `head`, and for an empty prefix or one holding whitespace, `"`, `(` or `)`.
+
 ## 0.12.1
 
 ### Patch Changes

package/README.md

@@ -184,19 +184,39 @@ Name a repository, a host, or both, and every call targets them instead. No
 clone is needed:
 
 ```ts
-const acme = new Gh(process.cwd(), { repo: 'acme/widgets', hostname: 'github.acme.com' })
+const acme = new Gh({ repo: 'acme/widgets', hostname: 'github.acme.com' })
 
 acme.prView(42)
 acme.withRepo('acme/gadgets').prList()
 acme.api('repos/{owner}/{repo}/branches')
 ```
 
+A client has two forms. `new Gh(cwd, options?)` runs every call in `cwd`, and
+without `repo` gh reads the repository from the clone there.
+`new Gh({ repo, hostname?, runner? })` names a repository and no directory.
+`repo` is required in that form: `new Gh({})` and `new Gh({ hostname })` do
+not typecheck and throw `TypeError`, so a client that reads a clone always
+says which one. Its calls run in `process.cwd()`, read when each call is made.
+No typed verb depends on that directory, but `raw` and `rawChecked` add no
+`--repo`, and gh fills an `api` endpoint's `{branch}` from that directory's
+checkout, so add `--repo` to a raw call or use `.at(dir)`. `gh.cwd` is that
+directory, a `string` in both forms. `AsyncGh` takes the same two forms.
+
+```ts
+const local = new Gh('/path/to/clone') // reads acme/widgets from the clone's remote
+const remote = new Gh({ repo: 'acme/widgets' }) // needs no clone
+
+remote.at('/path/to/clone') // a client rooted at the clone, still naming acme/widgets
+local.searchPrs('is:open author:@me') // a host-only call works on either form
+```
+
 The target goes into the argv, so a failure's `argv` shows which repository a
 call hit. `pr`, `issue` and `label` calls get `--repo github.acme.com/acme/widgets`.
 `api` calls get `--hostname` and a filled `{owner}/{repo}`. `authStatus`
 asks about that host. `repoList` and `searchPrs` have no host flag in gh, so
 they get `GH_HOST` in the environment. `withRepo` and `at` keep the runner and
-the rest of the target.
+the rest of the target. `at` on a client with no directory gives one rooted
+at that directory. `withRepo` keeps the client's form.
 
 `hostname` is any GitHub host: `github.com`, a GitHub Enterprise Server host,
 or a `<tenant>.ghe.com` host. An empty string means no host, so a value read
@@ -234,14 +254,26 @@ after the merge still finds it.
 `task/foo-2`. Two forks can share a branch name. Ask for
 `headRepositoryOwner` to tell them apart.
 
+`prList({ headPrefix: 'task/' })` lists every PR whose head branch starts
+with `task/`. It sends a `head:task/` search term, with your own `search`
+grouped after it in parentheses, and filters the rows on `headRefName`. It
+cannot be combined with `head`. Because it goes through GitHub search, a
+just-pushed branch can take a moment to show up, and `limit` is at most 999,
+as search returns no more than 1000 results.
+
 ## Two payload differences it handles
 
-Author logins differ between GraphQL and REST. GraphQL (`gh pr view --json`)
-returns a login without a suffix (`github-actions`). REST (`gh api`) returns
-the suffixed one (`github-actions[bot]`). Comparing one with the other never
-matches, and no error shows it. Then a bot's comments are treated as human
-review feedback. Logins are cut to the form without the suffix once, when a
-payload is parsed.
+A bot's login is spelled three ways. GraphQL, and comment and review authors
+in `gh pr view --json`, give the bare login (`github-actions`). gh's `--json`
+export of a pull request's author prefixes it (`app/github-actions`). REST
+(`gh api`) and `gh search` suffix it (`github-actions[bot]`). Comparing one with another
+never matches, and no error shows it. Then a bot's comments are treated as
+human review feedback. Logins are cut to the bare form once, when a payload is
+parsed, and the prefix or suffix marks the author as a bot.
+
+gh's `--author` filter does not take the bare form of a bot's login: pass
+`app/<login>` or `<login>[bot]` to `prList({ author })` to list a bot's pull
+requests.
 
 `statusCheckRollup` holds two node types. A modern `CheckRun` carries
 `name`/`status`/`conclusion`. A legacy `StatusContext` carries
@@ -525,10 +557,12 @@ experimental.
 
 ### Clients
 
-- `Gh`: the synchronous client, bound to one working directory, and optionally a repository and
-  host.
+- `Gh`: the synchronous client, bound to one working directory or one repository, and optionally a
+  host. `new Gh(cwd, options?)` or `new Gh({ repo, hostname?, runner? })`.
 - `AsyncGh`: the awaitable client, with the same methods.
 - `GhOptions` and `AsyncGhOptions`: the runner, `repo` and `hostname` a client is built with.
+- `GhRepoOptions` and `AsyncGhRepoOptions`: the same with `repo` required, for a client built
+  without a directory.
 - `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
@@ -585,7 +619,7 @@ Each verb takes an optional `GhTarget` last. Each client method has a verb of th
 
 - `parsePullRequest`: reads a `gh --json` payload into a `PullRequest`, or `null`.
 - `anyCheckFailed`: true if any check in a list failed.
-- `normalizeAuthorLogin`: drops a `[bot]` suffix from a login.
+- `normalizeAuthorLogin`: drops a `[bot]` suffix or an `app/` prefix from a login.
 - `parseOwnerRepo`: reads a remote URL into `{ owner, repo }`, or `null`. It is
   `@osdlc/typed-git`'s `parseRemoteRepo` without the host, so any host's remote reads, not only
   GitHub's. Use `parseRemoteRepo` when you need the host too.

package/dist/async.d.ts

@@ -34,22 +34,40 @@ export interface AsyncCallOptions {
 export interface AsyncGhOptions extends GhTarget {
     runner?: AsyncCommandRunner | undefined;
 }
+/** {@link AsyncGhOptions} with `repo` required: what `new AsyncGh(options)` takes. See `GhRepoOptions`. */
+export interface AsyncGhRepoOptions extends AsyncGhOptions {
+    repo: string;
+}
 /**
- * A typed, awaitable gh client bound to one working directory, and optionally
- * to one repository and host. `repo` and `hostname` work as on `Gh`.
+ * A typed, awaitable gh client bound to one working directory or one named
+ * repository, and optionally to one host. The two constructor forms, `repo`
+ * and `hostname` work as on `Gh`: `new AsyncGh(cwd, options?)` runs in
+ * `cwd`, and `new AsyncGh({ repo, hostname?, runner? })` runs each call in
+ * `process.cwd()`, read when the call is made. As on `Gh`, `raw`,
+ * `rawChecked` and an `api` endpoint's `{branch}` still read that directory.
  */
 export declare class AsyncGh {
-    readonly cwd: string;
     readonly repo: string | undefined;
     readonly hostname: string | undefined;
+    private readonly boundCwd;
     private readonly target;
     private readonly runner;
     private tried;
     private softened;
-    constructor(cwd: string, opts?: AsyncGhOptions);
+    /** A client for the repository `options.repo`, with no working directory of its own. */
+    constructor(options: AsyncGhRepoOptions);
+    /** A client rooted at `cwd`: the clone gh reads, unless `options.repo` names another repository. */
+    constructor(cwd: string, options?: AsyncGhOptions);
+    /** Either form, for a value typed `string | AsyncGhRepoOptions`. */
+    constructor(cwdOrOptions: string | AsyncGhRepoOptions);
+    /** The directory calls run in. See `Gh.cwd`. */
+    get cwd(): string;
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd: string): AsyncGh;
-    /** The same client aimed at another repository (same runner, directory and host). */
+    /**
+     * The same client aimed at another repository (same runner, directory and
+     * host). A client built from options alone stays without a directory.
+     */
     withRepo(repo: string): AsyncGh;
     /**
      * The whole surface again, resolving to a `Result<T, GhFailure>` instead of
@@ -59,9 +77,14 @@ export declare class AsyncGh {
     get try(): TriedAsync<AsyncGh>;
     /** Each query again, resolving `null` instead of rejecting when `gh` fails. See `Gh.soft`. */
     get soft(): Soft<AsyncGh>;
-    /** Run any `gh` call and return the result, whatever the exit code. */
+    /**
+     * Run any `gh` call and return the result, whatever the exit code. It adds
+     * no `--repo`: on a client built without a directory it runs in
+     * `process.cwd()`, so gh reads that clone. Add `--repo` to `argv`, or call
+     * `.at(dir)` first.
+     */
     raw(argv: string[], opts?: AsyncCallOptions): Promise<CommandResult>;
-    /** Run any `gh` call. Rejects with the classified failure on a non-zero exit. */
+    /** Run any `gh` call. Rejects with the classified failure on a non-zero exit. Adds no `--repo`, as {@link AsyncGh.raw}. */
     rawChecked(argv: string[], opts?: AsyncCallOptions): Promise<CommandResult>;
     /** Run one verb from the table, checked or unchecked as the verb says. */
     private exec;

package/dist/async.js

@@ -18,32 +18,47 @@ import * as v from "./verbs.js";
 /** How long to wait between merge-state retries, in milliseconds. */
 const MERGE_STATE_RETRY_DELAY_MS = 1_500;
 /**
- * A typed, awaitable gh client bound to one working directory, and optionally
- * to one repository and host. `repo` and `hostname` work as on `Gh`.
+ * A typed, awaitable gh client bound to one working directory or one named
+ * repository, and optionally to one host. The two constructor forms, `repo`
+ * and `hostname` work as on `Gh`: `new AsyncGh(cwd, options?)` runs in
+ * `cwd`, and `new AsyncGh({ repo, hostname?, runner? })` runs each call in
+ * `process.cwd()`, read when the call is made. As on `Gh`, `raw`,
+ * `rawChecked` and an `api` endpoint's `{branch}` still read that directory.
  */
 export class AsyncGh {
-    cwd;
     repo;
     hostname;
+    boundCwd;
     target;
     runner;
     tried;
     softened;
-    constructor(cwd, opts = {}) {
+    constructor(cwdOrOptions, options = {}) {
+        const opts = typeof cwdOrOptions === 'string' ? options : cwdOrOptions;
+        if (typeof cwdOrOptions !== 'string')
+            v.requireRepo('AsyncGh', opts);
         v.checkTarget(opts);
-        this.cwd = cwd;
+        this.boundCwd = typeof cwdOrOptions === 'string' ? cwdOrOptions : undefined;
         this.repo = opts.repo;
         this.hostname = opts.hostname;
         this.target = { repo: opts.repo, hostname: opts.hostname };
         this.runner = opts.runner ?? spawnRunnerAsync('gh', { absolutePathOnly: true });
     }
+    /** The directory calls run in. See `Gh.cwd`. */
+    get cwd() {
+        return this.boundCwd ?? process.cwd();
+    }
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd) {
         return new AsyncGh(cwd, { runner: this.runner, repo: this.repo, hostname: this.hostname });
     }
-    /** The same client aimed at another repository (same runner, directory and host). */
+    /**
+     * The same client aimed at another repository (same runner, directory and
+     * host). A client built from options alone stays without a directory.
+     */
     withRepo(repo) {
-        return new AsyncGh(this.cwd, { runner: this.runner, repo, hostname: this.hostname });
+        const opts = { runner: this.runner, repo, hostname: this.hostname };
+        return this.boundCwd === undefined ? new AsyncGh(opts) : new AsyncGh(this.boundCwd, opts);
     }
     /**
      * The whole surface again, resolving to a `Result<T, GhFailure>` instead of
@@ -58,11 +73,16 @@ export class AsyncGh {
         return (this.softened ??= softAsync(this));
     }
     // ── raw calls ─────────────────────────────────────────────────────────────
-    /** Run any `gh` call and return the result, whatever the exit code. */
+    /**
+     * Run any `gh` call and return the result, whatever the exit code. It adds
+     * no `--repo`: on a client built without a directory it runs in
+     * `process.cwd()`, so gh reads that clone. Add `--repo` to `argv`, or call
+     * `.at(dir)` first.
+     */
     raw(argv, opts = {}) {
         return this.runner.run(argv, { cwd: this.cwd, ...opts });
     }
-    /** Run any `gh` call. Rejects with the classified failure on a non-zero exit. */
+    /** Run any `gh` call. Rejects with the classified failure on a non-zero exit. Adds no `--repo`, as {@link AsyncGh.raw}. */
     rawChecked(argv, opts = {}) {
         return runCheckedGhAsync(this.runner, argv, { cwd: this.cwd, ...opts });
     }

package/dist/index.d.ts

@@ -18,11 +18,11 @@
  *
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */
-export { AsyncGh, type AsyncCallOptions, type AsyncGhOptions } from './async.ts';
+export { AsyncGh, type AsyncCallOptions, type AsyncGhOptions, type AsyncGhRepoOptions, } 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 { Gh, defaultRunnerFactory, type GhOptions, type GhRepoOptions, 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';

package/dist/index.js

@@ -18,11 +18,11 @@
  *
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */
-export { AsyncGh } from "./async.js";
+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 { 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";
 export { ownerRepoSlug, parseOwnerRepo, parsePrRef, parsePrUrl, } from "./repo.js";

package/dist/parse.d.ts

@@ -6,13 +6,14 @@
  *
  * It handles two payload differences:
  *
- *  1. Author logins differ between GraphQL and REST. GraphQL
- *     (`gh pr view --json`) returns a login without a suffix
- *     (`github-actions`). REST (`gh api`) returns the suffixed one
- *     (`github-actions[bot]`). Comparing one with the other never matches,
- *     and no error shows it. Then a bot's comments are treated as human
- *     review feedback. Logins are normalized here, once, to the form without
- *     the suffix.
+ *  1. A bot's login is spelled three ways. GraphQL (`gh api graphql`, and a
+ *     comment's author in `gh pr view --json`) gives the bare login
+ *     (`github-actions`). gh's own `--json` export of a pull request's
+ *     author prefixes it (`app/github-actions`, with `is_bot: true`). REST
+ *     (`gh api`) suffixes it (`github-actions[bot]`). Comparing one with
+ *     another never matches, and no error shows it. Then a bot's comments
+ *     are treated as human review feedback. Logins are normalized here, once,
+ *     to the bare form.
  *  2. `statusCheckRollup` holds two node types. A modern `CheckRun` carries
  *     `name`/`status`/`conclusion`. A legacy `StatusContext` carries
  *     `context`/`state`. Both map to one verdict, so a caller never has to
@@ -20,13 +21,15 @@
  */
 import type { Actor, CheckRun, Label, PrSearchHit, PullRequest, Repository } from './types.ts';
 /**
- * Strip a single trailing `[bot]` suffix, so a REST login matches the
- * GraphQL one.
+ * The bare login: a single trailing `[bot]` (REST) or a leading `app/` (gh's
+ * `--json` export of a bot author) is stripped, so every spelling of one bot
+ * compares equal. A user login cannot hold `/` or `[`, so neither strip can
+ * change one.
  */
 export declare function normalizeAuthorLogin(login: string): string;
 /**
  * Parse an author node from GraphQL (`author`) or REST (`user`).
- * Null when there is no login, or the login is empty once `[bot]` is removed.
+ * Null when there is no login, or the login is empty once `[bot]` or `app/` is removed.
  */
 export declare function parseActor(x: unknown): Actor | null;
 /** One `statusCheckRollup` entry, whichever node type it is. */

package/dist/parse.js

@@ -6,13 +6,14 @@
  *
  * It handles two payload differences:
  *
- *  1. Author logins differ between GraphQL and REST. GraphQL
- *     (`gh pr view --json`) returns a login without a suffix
- *     (`github-actions`). REST (`gh api`) returns the suffixed one
- *     (`github-actions[bot]`). Comparing one with the other never matches,
- *     and no error shows it. Then a bot's comments are treated as human
- *     review feedback. Logins are normalized here, once, to the form without
- *     the suffix.
+ *  1. A bot's login is spelled three ways. GraphQL (`gh api graphql`, and a
+ *     comment's author in `gh pr view --json`) gives the bare login
+ *     (`github-actions`). gh's own `--json` export of a pull request's
+ *     author prefixes it (`app/github-actions`, with `is_bot: true`). REST
+ *     (`gh api`) suffixes it (`github-actions[bot]`). Comparing one with
+ *     another never matches, and no error shows it. Then a bot's comments
+ *     are treated as human review feedback. Logins are normalized here, once,
+ *     to the bare form.
  *  2. `statusCheckRollup` holds two node types. A modern `CheckRun` carries
  *     `name`/`status`/`conclusion`. A legacy `StatusContext` carries
  *     `context`/`state`. Both map to one verdict, so a caller never has to
@@ -48,15 +49,21 @@ function list(x) {
 }
 // ── actors ──────────────────────────────────────────────────────────────────
 /**
- * Strip a single trailing `[bot]` suffix, so a REST login matches the
- * GraphQL one.
+ * The bare login: a single trailing `[bot]` (REST) or a leading `app/` (gh's
+ * `--json` export of a bot author) is stripped, so every spelling of one bot
+ * compares equal. A user login cannot hold `/` or `[`, so neither strip can
+ * change one.
  */
 export function normalizeAuthorLogin(login) {
-    return login.endsWith('[bot]') ? login.slice(0, -'[bot]'.length) : login;
+    if (login.endsWith('[bot]'))
+        return login.slice(0, -'[bot]'.length);
+    if (login.startsWith('app/'))
+        return login.slice('app/'.length);
+    return login;
 }
 /**
  * Parse an author node from GraphQL (`author`) or REST (`user`).
- * Null when there is no login, or the login is empty once `[bot]` is removed.
+ * Null when there is no login, or the login is empty once `[bot]` or `app/` is removed.
  */
 export function parseActor(x) {
     if (!isRecord(x))
@@ -67,8 +74,8 @@ export function parseActor(x) {
         return null;
     return {
         login,
-        // Only some payloads carry `is_bot`. The suffix works for both.
-        isBot: bool(x['is_bot']) || raw.endsWith('[bot]'),
+        // Only some payloads carry `is_bot`. The suffix and prefix mark a bot too.
+        isBot: bool(x['is_bot']) || login !== raw,
     };
 }
 // ── checks ──────────────────────────────────────────────────────────────────

package/dist/sync.d.ts

@@ -1,6 +1,7 @@
 /**
  * `Gh`: the synchronous GitHub client, the companion of `@osdlc/typed-git`'s
- * `Git`, bound to one working directory and one {@link CommandRunner}.
+ * `Git`, bound to one {@link CommandRunner} and either one working directory
+ * or one named repository.
  *
  * `gh` handles authentication. No token is read, stored, or passed. That is
  * why this runs the CLI instead of calling the REST API. The credential is
@@ -37,31 +38,64 @@ export interface GhOptions extends GhTarget {
     runner?: CommandRunner | undefined;
 }
 /**
- * A typed gh client bound to one working directory, and optionally to one
- * repository and host.
+ * {@link GhOptions} with `repo` required: what `new Gh(options)` takes when
+ * no working directory is given. Requiring `repo` keeps clone-relative use
+ * explicit: a client that reads the repository from a clone must say which
+ * directory the clone is in.
+ */
+export interface GhRepoOptions extends GhOptions {
+    repo: string;
+}
+/**
+ * A typed gh client bound to one working directory or one named repository,
+ * and optionally to one host.
  *
- * With `repo`, every call names that repository (`--repo`, or the
- * `{owner}/{repo}` of an `api` endpoint), so no clone is needed. Without it,
- * gh uses the repository of the clone at `cwd`. With `hostname`, every call
- * goes to that GitHub host. An invalid `repo` or `hostname` throws
- * `RangeError`.
+ * `new Gh(cwd, options?)` runs every call in `cwd`. With `repo`, every call
+ * names that repository (`--repo`, or the `{owner}/{repo}` of an `api`
+ * endpoint), so no clone is needed. Without it, gh uses the repository of
+ * the clone at `cwd`.
+ *
+ * `new Gh({ repo, hostname?, runner? })` names a repository and no
+ * directory. Each call runs in `process.cwd()`, read when the call is made,
+ * because a runner needs a directory. No typed verb depends on it: each one
+ * names `repo`, and the host-only verbs (`repoList`, `searchPrs`) read no
+ * clone. Two escape hatches do: `raw` and `rawChecked` add no `--repo`, and
+ * an `api` endpoint's `{branch}` is filled by gh from the directory's
+ * checkout. `repo` is required in this form, so `new Gh({})` does not
+ * typecheck and throws `TypeError`.
+ *
+ * With `hostname`, every call goes to that GitHub host. An invalid `repo` or
+ * `hostname` throws `RangeError`.
  *
  * Every `timeoutMs` option is a hard cap on the call. An invalid value
  * throws, as in command-seam: `RangeError` for 0, a negative value or `NaN`;
  * `TypeError` for a non-number.
  */
 export declare class Gh {
-    readonly cwd: string;
     readonly repo: string | undefined;
     readonly hostname: string | undefined;
+    private readonly boundCwd;
     private readonly target;
     private readonly runner;
     private tried;
     private softened;
-    constructor(cwd: string, opts?: GhOptions);
+    /** A client for the repository `options.repo`, with no working directory of its own. */
+    constructor(options: GhRepoOptions);
+    /** A client rooted at `cwd`: the clone gh reads, unless `options.repo` names another repository. */
+    constructor(cwd: string, options?: GhOptions);
+    /** Either form, for a value typed `string | GhRepoOptions`. */
+    constructor(cwdOrOptions: string | GhRepoOptions);
+    /**
+     * The directory calls run in: the `cwd` the client was built with, or for
+     * a client built from options alone, `process.cwd()` at the time it is read.
+     */
+    get cwd(): string;
     /** 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). */
+    /**
+     * The same client aimed at another repository (same runner, directory and
+     * host). A client built from options alone stays without a directory.
+     */
     withRepo(repo: string): Gh;
     /**
      * The whole surface again, returning a `Result<T, GhFailure>` instead of
@@ -81,11 +115,16 @@ export declare class Gh {
      * `try` where the difference matters.
      */
     get soft(): Soft<Gh>;
-    /** Run any `gh` call and return the result, whatever the exit code. */
+    /**
+     * Run any `gh` call and return the result, whatever the exit code. It adds
+     * no `--repo`: on a client built without a directory it runs in
+     * `process.cwd()`, so gh reads that clone. Add `--repo` to `argv`, or call
+     * `.at(dir)` first.
+     */
     raw(argv: string[], opts?: {
         timeoutMs?: number | undefined;
     }): CommandResult;
-    /** Run any `gh` call. Throws the classified failure on a non-zero exit. */
+    /** Run any `gh` call. Throws the classified failure on a non-zero exit. Adds no `--repo`, as {@link Gh.raw}. */
     rawChecked(argv: string[], opts?: {
         timeoutMs?: number | undefined;
     }): CommandResult;

package/dist/sync.js

@@ -1,6 +1,7 @@
 /**
  * `Gh`: the synchronous GitHub client, the companion of `@osdlc/typed-git`'s
- * `Git`, bound to one working directory and one {@link CommandRunner}.
+ * `Git`, bound to one {@link CommandRunner} and either one working directory
+ * or one named repository.
  *
  * `gh` handles authentication. No token is read, stored, or passed. That is
  * why this runs the CLI instead of calling the REST API. The credential is
@@ -29,42 +30,67 @@ export const defaultRunnerFactory = (binary) => spawnRunner(binary, { absolutePa
 /** How long to wait between merge-state retries, in milliseconds. */
 const MERGE_STATE_RETRY_DELAY_MS = 1_500;
 /**
- * A typed gh client bound to one working directory, and optionally to one
- * repository and host.
+ * A typed gh client bound to one working directory or one named repository,
+ * and optionally to one host.
  *
- * With `repo`, every call names that repository (`--repo`, or the
- * `{owner}/{repo}` of an `api` endpoint), so no clone is needed. Without it,
- * gh uses the repository of the clone at `cwd`. With `hostname`, every call
- * goes to that GitHub host. An invalid `repo` or `hostname` throws
- * `RangeError`.
+ * `new Gh(cwd, options?)` runs every call in `cwd`. With `repo`, every call
+ * names that repository (`--repo`, or the `{owner}/{repo}` of an `api`
+ * endpoint), so no clone is needed. Without it, gh uses the repository of
+ * the clone at `cwd`.
+ *
+ * `new Gh({ repo, hostname?, runner? })` names a repository and no
+ * directory. Each call runs in `process.cwd()`, read when the call is made,
+ * because a runner needs a directory. No typed verb depends on it: each one
+ * names `repo`, and the host-only verbs (`repoList`, `searchPrs`) read no
+ * clone. Two escape hatches do: `raw` and `rawChecked` add no `--repo`, and
+ * an `api` endpoint's `{branch}` is filled by gh from the directory's
+ * checkout. `repo` is required in this form, so `new Gh({})` does not
+ * typecheck and throws `TypeError`.
+ *
+ * With `hostname`, every call goes to that GitHub host. An invalid `repo` or
+ * `hostname` throws `RangeError`.
  *
  * Every `timeoutMs` option is a hard cap on the call. An invalid value
  * throws, as in command-seam: `RangeError` for 0, a negative value or `NaN`;
  * `TypeError` for a non-number.
  */
 export class Gh {
-    cwd;
     repo;
     hostname;
+    boundCwd;
     target;
     runner;
     tried;
     softened;
-    constructor(cwd, opts = {}) {
+    constructor(cwdOrOptions, options = {}) {
+        const opts = typeof cwdOrOptions === 'string' ? options : cwdOrOptions;
+        if (typeof cwdOrOptions !== 'string')
+            v.requireRepo('Gh', opts);
         v.checkTarget(opts);
-        this.cwd = cwd;
+        this.boundCwd = typeof cwdOrOptions === 'string' ? cwdOrOptions : undefined;
         this.repo = opts.repo;
         this.hostname = opts.hostname;
         this.target = { repo: opts.repo, hostname: opts.hostname };
         this.runner = opts.runner ?? defaultRunnerFactory('gh');
     }
+    /**
+     * The directory calls run in: the `cwd` the client was built with, or for
+     * a client built from options alone, `process.cwd()` at the time it is read.
+     */
+    get cwd() {
+        return this.boundCwd ?? process.cwd();
+    }
     /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd) {
         return new Gh(cwd, { runner: this.runner, repo: this.repo, hostname: this.hostname });
     }
-    /** The same client aimed at another repository (same runner, directory and host). */
+    /**
+     * The same client aimed at another repository (same runner, directory and
+     * host). A client built from options alone stays without a directory.
+     */
     withRepo(repo) {
-        return new Gh(this.cwd, { runner: this.runner, repo, hostname: this.hostname });
+        const opts = { runner: this.runner, repo, hostname: this.hostname };
+        return this.boundCwd === undefined ? new Gh(opts) : new Gh(this.boundCwd, opts);
     }
     /**
      * The whole surface again, returning a `Result<T, GhFailure>` instead of
@@ -89,11 +115,16 @@ export class Gh {
         return (this.softened ??= softSync(this));
     }
     // ── raw calls ─────────────────────────────────────────────────────────────
-    /** Run any `gh` call and return the result, whatever the exit code. */
+    /**
+     * Run any `gh` call and return the result, whatever the exit code. It adds
+     * no `--repo`: on a client built without a directory it runs in
+     * `process.cwd()`, so gh reads that clone. Add `--repo` to `argv`, or call
+     * `.at(dir)` first.
+     */
     raw(argv, opts = {}) {
         return this.runner.run(argv, { cwd: this.cwd, ...opts });
     }
-    /** Run any `gh` call. Throws the classified failure on a non-zero exit. */
+    /** Run any `gh` call. Throws the classified failure on a non-zero exit. Adds no `--repo`, as {@link Gh.raw}. */
     rawChecked(argv, opts = {}) {
         return runCheckedGh(this.runner, argv, { cwd: this.cwd, ...opts });
     }

package/dist/types.d.ts

@@ -41,10 +41,10 @@ export type PullRequestState = 'OPEN' | 'CLOSED' | 'MERGED' | (string & {});
 export type ReviewDecision = 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED' | null;
 /** The state of one review. `PENDING` is a review its author has not submitted yet. */
 export type ReviewState = 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED' | 'PENDING' | (string & {});
-/** Who wrote something. `login` is normalized: a `[bot]` suffix is stripped. */
+/** Who wrote something. `login` is normalized: a `[bot]` suffix or `app/` prefix is stripped. */
 export interface Actor {
     login: string;
-    /** True when GitHub marks the account as a bot, or the login carried `[bot]`. */
+    /** True when GitHub marks the account as a bot, or the login carried `[bot]` or `app/`. */
     isBot: boolean;
 }
 /** A repository label. `color` is hex digits such as `d73a4a`. A field the payload lacks is `''`. */

package/dist/verbs.d.ts

@@ -71,6 +71,11 @@ export interface GhTarget {
  * no text can reach gh as a flag or change the endpoint a call hits.
  */
 export declare function checkTarget(target: GhTarget | undefined): void;
+/**
+ * Throws `TypeError` unless `opts.repo` is set: the options-only form names
+ * a repository, so a missing one would silently read the process's own clone.
+ */
+export declare function requireRepo(client: string, opts: GhTarget | undefined): void;
 /**
  * The smallest useful set: enough to identify a PR and nothing more.
  *
@@ -120,6 +125,24 @@ export interface PrListOptions {
      * apart.
      */
     head?: string | undefined;
+    /**
+     * Every PR whose head branch starts with this prefix, such as `task/`.
+     *
+     * Sent as a `head:<prefix>` term of a GitHub search, with any `search`
+     * grouped after it in parentheses, so an `OR` there cannot escape the
+     * prefix. The rows are filtered again on `headRefName`, since GitHub's
+     * `head:` match ignores case and git branch names do not.
+     *
+     * Going through search brings search's limits: a short index lag after a
+     * push, the search rate limit, and at most 1000 results, so a `limit` over
+     * 999 throws `RangeError`. `truncated` counts the rows gh returned before
+     * the case filter, so it can be true with fewer than `limit` rows.
+     *
+     * Passing it with `head` throws `RangeError`, as does an empty prefix or
+     * one holding whitespace, `"`, `(` or `)`, which GitHub search would read
+     * as syntax.
+     */
+    headPrefix?: string | undefined;
     /** Raw `--search` query, for anything the flags do not cover. */
     search?: string | undefined;
     author?: string | undefined;
@@ -193,7 +216,8 @@ export interface ApiOptions {
 /**
  * `gh api [-i] [-H If-None-Match: …] <endpoint>`: a GET against the REST API. `{owner}` and
  * `{repo}` placeholders in the endpoint are filled from the target's repo, or by gh from the
- * cwd's repo when the target names none.
+ * cwd's repo when the target names none. gh fills `{branch}` from the cwd's checked-out branch
+ * whatever the target, so it reads the working directory even on a client built from `repo`.
  * Unchecked. Failure is a value (`ok: false`), so a caller can tell a 304
  * from an outage.
  */

package/dist/verbs.js

@@ -48,6 +48,15 @@ export function checkTarget(target) {
         throw new RangeError(`hostname must be a bare host, got ${JSON.stringify(hostname)}`);
     }
 }
+/**
+ * Throws `TypeError` unless `opts.repo` is set: the options-only form names
+ * a repository, so a missing one would silently read the process's own clone.
+ */
+export function requireRepo(client, opts) {
+    if (typeof opts !== 'object' || opts === null || opts.repo === undefined) {
+        throw new TypeError(`new ${client}(options) needs options.repo; pass a directory, as new ${client}(cwd, options), for a clone`);
+    }
+}
 /**
  * `[host/]owner/name` for `repo` (else the target's repo), the form `--repo`
  * and `gh repo view` take, or `undefined` when neither names one. The host is
@@ -243,34 +252,55 @@ function manyIssuesOrNull(r) {
 export function prList(opts = {}, target) {
     const limit = opts.limit ?? 100;
     checkLimit(limit);
+    const { head, headPrefix } = opts;
+    if (headPrefix !== undefined) {
+        if (head !== undefined)
+            throw new RangeError('prList: pass head or headPrefix, not both');
+        if (limit > 999) {
+            throw new RangeError(`prList: headPrefix goes through GitHub search, which returns at most 1000 results; limit ${limit} is over 999`);
+        }
+        if (headPrefix === '' || /[\s"()]/.test(headPrefix)) {
+            throw new RangeError(`prList: headPrefix must be a non-empty branch prefix, got ${JSON.stringify(headPrefix)}`);
+        }
+    }
     const argv = ['pr', 'list', '--state', opts.state ?? 'open', ...repoArgs(target, opts.repo)];
     if (opts.base !== undefined)
         argv.push('--base', opts.base);
-    if (opts.head !== undefined)
-        argv.push('--head', opts.head);
-    if (opts.search !== undefined)
-        argv.push('--search', opts.search);
+    if (head !== undefined)
+        argv.push('--head', head);
+    // The caller's search is grouped so its `OR` cannot escape the prefix:
+    // GitHub search binds AND tighter than OR.
+    const own = opts.search?.trim();
+    const search = headPrefix === undefined
+        ? opts.search
+        : own === undefined || own === ''
+            ? `head:${headPrefix}`
+            : `head:${headPrefix} (${own})`;
+    if (search !== undefined)
+        argv.push('--search', search);
     if (opts.author !== undefined)
         argv.push('--author', opts.author);
     // A row without `number` does not parse and is dropped, so always ask for it.
-    // The exact-head filter below also reads `headRefName`.
+    // The head filters below also read `headRefName`.
+    const filtered = head !== undefined || headPrefix !== undefined;
     const asked = withFields(opts.fields ?? PR_LIST_FIELDS, [
         'number',
-        ...(opts.head === undefined ? [] : ['headRefName']),
+        ...(filtered ? ['headRefName'] : []),
     ]);
     argv.push('--json', asked.join(','));
     argv.push('--limit', String(limit + 1));
-    const head = opts.head;
+    const keep = (name) => head !== undefined ? name === head : headPrefix === undefined || name.startsWith(headPrefix);
     return {
         argv,
         checked: false,
         readOnly: true,
         parse(r) {
             // A search stops at 1000 results, so 1000 rows may be a cut, not the end.
-            const result = limited(manyOrNull(r), limit, (opts.search ?? '') !== '' || opts.author !== undefined ? SEARCH_RESULT_CAP : undefined);
-            if (result === null || head === undefined)
+            // `search` here is the one sent, `head:<prefix>` included.
+            const result = limited(manyOrNull(r), limit, (search ?? '') !== '' || opts.author !== undefined ? SEARCH_RESULT_CAP : undefined);
+            if (result === null || !filtered)
                 return result;
-            return { ...result, rows: result.rows.filter((pr) => pr.headRefName === head) };
+            return { ...result, rows: result.rows.filter((pr) => keep(pr.headRefName)) };
         },
     };
 }
@@ -342,7 +372,8 @@ export function prBody(number, target) {
 /**
  * `gh api [-i] [-H If-None-Match: …] <endpoint>`: a GET against the REST API. `{owner}` and
  * `{repo}` placeholders in the endpoint are filled from the target's repo, or by gh from the
- * cwd's repo when the target names none.
+ * cwd's repo when the target names none. gh fills `{branch}` from the cwd's checked-out branch
+ * whatever the target, so it reads the working directory even on a client built from `repo`.
  * Unchecked. Failure is a value (`ok: false`), so a caller can tell a 304
  * from an outage.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/typed-gh",
-  "version": "0.12.1",
+  "version": "0.13.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",
@@ -26,9 +26,9 @@
     "LICENSE-APACHE"
   ],
   "dependencies": {
-    "@osdlc/command-seam": "^0.14.0",
     "@osdlc/typed-git": "^0.11.1",
-    "@osdlc/result": "^0.1.0"
+    "@osdlc/result": "^0.1.0",
+    "@osdlc/command-seam": "^0.14.0"
   },
   "engines": {
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"