@osdlc/typed-gh 0.5.0 → 0.6.0

package/dist/async.d.ts

@@ -8,13 +8,13 @@
  * sync client would block the event loop: a fan-out of per-PR queries.
  */
 import { type AsyncCommandRunner, type CommandResult } from '@osdlc/command-seam';
-import type { IssueRow, Label, OwnerRepo, PullRequest } from './types.ts';
+import type { IssueRow, Label, OwnerRepo, PrSearchHit, PullRequest, Repository } from './types.ts';
 import * as v from './verbs.ts';
-import type { ApiOptions, ApiResponse, AuthStatus, IssueListOptions, PrListOptions } from './verbs.ts';
+import type { ApiOptions, ApiResponse, AuthStatus, GhTarget, IssueListOptions, ListResult, PrListOptions } from './verbs.ts';
 /**
- * Per-call options for {@link AsyncGh}. Eleven methods accept them: `raw`, `rawChecked`,
- * `prList`, `prView`, `openPrFor`, `prViewSettled`, `prBody`, `api`, `labelList`,
- * `issueList` and `issueView`.
+ * Per-call options for {@link AsyncGh}. Sixteen methods accept them: `raw`, `rawChecked`,
+ * `prList`, `prView`, `prFind`, `openPrFor`, `prViewSettled`, `prBody`, `api`, `graphql`,
+ * `labelList`, `issueList`, `issueView`, `repoList`, `repoView` and `searchPrs`.
  */
 export interface AsyncCallOptions {
     /**
@@ -26,15 +26,25 @@ export interface AsyncCallOptions {
     /** Aborts the call; the runner stops the child. */
     signal?: AbortSignal | undefined;
 }
-/** A typed, awaitable gh client bound to one working directory. */
+/** What an {@link AsyncGh} is built with: the runner, and the repository and host it talks to. */
+export interface AsyncGhOptions extends GhTarget {
+    runner?: AsyncCommandRunner | undefined;
+}
+/**
+ * A typed, awaitable gh client bound to one working directory, and optionally
+ * to one repository and host. `repo` and `hostname` work as on `Gh`.
+ */
 export declare class AsyncGh {
     readonly cwd: string;
+    readonly repo: string | undefined;
+    readonly hostname: string | undefined;
+    private readonly target;
     private readonly runner;
-    constructor(cwd: string, opts?: {
-        runner?: AsyncCommandRunner | undefined;
-    });
-    /** The same client rooted at a different directory (same runner). */
+    constructor(cwd: string, opts?: AsyncGhOptions);
+    /** 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). */
+    withRepo(repo: string): AsyncGh;
     /** Unchecked passthrough for verbs not yet lifted into the API. */
     raw(argv: string[], opts?: AsyncCallOptions): Promise<CommandResult>;
     /** Checked passthrough — rejects with `CommandFailed` on a non-zero exit. */
@@ -42,9 +52,13 @@ export declare class AsyncGh {
     /** Run one verb from the table, honouring its checked/unchecked contract. */
     private exec;
     /** Pull requests matching `opts`, or null when gh failed. */
-    prList(opts?: PrListOptions & AsyncCallOptions): Promise<PullRequest[] | null>;
-    /** One PR with the heavy fields, or null when gh failed. */
-    prView(number: number, opts?: {
+    prList(opts?: PrListOptions & AsyncCallOptions): Promise<ListResult<PullRequest> | null>;
+    /** One PR by number, branch or URL, with the heavy fields, or null. See `Gh.prView`. */
+    prView(ref: number | string, opts?: {
+        fields?: readonly string[] | undefined;
+    } & AsyncCallOptions): Promise<PullRequest | null>;
+    /** The one PR that `input` names, or null. See `Gh.prFind`. */
+    prFind(input: string, opts?: {
         fields?: readonly string[] | undefined;
     } & AsyncCallOptions): Promise<PullRequest | null>;
     /** The open PR whose head exactly equals `branch`, or null. See `Gh.openPrFor`. */
@@ -62,14 +76,28 @@ export declare class AsyncGh {
     prBody(number: number, opts?: AsyncCallOptions): Promise<string | null>;
     /** A REST GET through `gh api`; failure is `ok: false`, never a rejection. */
     api(endpoint: string, opts?: ApiOptions & AsyncCallOptions): Promise<ApiResponse>;
+    /**
+     * A GraphQL query; each page's `data`, or null. See `Gh.graphql`.
+     *
+     * @experimental
+     */
+    graphql(query: string, variables?: Record<string, v.GraphqlVariable>, opts?: v.GraphqlOptions & AsyncCallOptions): Promise<unknown[] | null>;
     /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
     labelList(opts?: {
         limit?: number | undefined;
-    } & AsyncCallOptions): Promise<Label[] | null>;
+    } & AsyncCallOptions): Promise<ListResult<Label> | null>;
     /** Issues matching `opts`, or null when gh failed. */
-    issueList(opts?: IssueListOptions & AsyncCallOptions): Promise<IssueRow[] | null>;
+    issueList(opts?: IssueListOptions & AsyncCallOptions): Promise<ListResult<IssueRow> | null>;
     /** One issue with its labels, or null when gh failed. */
     issueView(number: number, opts?: AsyncCallOptions): Promise<IssueRow | null>;
+    /** An owner's repositories, or null when gh failed. See `Gh.repoList`. */
+    repoList(owner: string, opts?: v.RepoListOptions & AsyncCallOptions): Promise<ListResult<Repository> | null>;
+    /** One repository, or null when gh failed. See `Gh.repoView`. */
+    repoView(repo?: string | undefined, opts?: {
+        fields?: readonly string[] | undefined;
+    } & AsyncCallOptions): Promise<Repository | null>;
+    /** Pull requests across repositories matching a search query, or null. See `Gh.searchPrs`. */
+    searchPrs(query: string, opts?: v.SearchPrsOptions & AsyncCallOptions): Promise<ListResult<PrSearchHit> | null>;
     /** True iff the `gh` binary is on PATH and runs. */
     installed(): Promise<boolean>;
     /** True iff `gh` holds credentials. */

package/dist/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../async.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAGL,KAAK,kBAAkB,EAEvB,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAA;AAG5B,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACzE,OAAO,KAAK,CAAC,MAAM,YAAY,CAAA;AAC/B,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,UAAU,EAEV,gBAAgB,EAChB,aAAa,EACd,MAAM,YAAY,CAAA;AAEnB;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,mDAAmD;IACnD,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CACjC;AAKD,mEAAmE;AACnE,qBAAa,OAAO;IAClB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAE/B,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;KAAO;IAK/E,qEAAqE;IACrE,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAMxB,mEAAmE;IACnE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC;IAIxE,6EAA6E;IAC7E,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC;IAI/E,6EAA6E;YAC/D,IAAI;IAalB,6DAA6D;IAC7D,MAAM,CAAC,IAAI,GAAE,aAAa,GAAG,gBAAqB,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC;IAIlF,4DAA4D;IAC5D,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;KAAE,GAAG,gBAAqB,GACvE,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAI9B,mFAAmF;IAC7E,SAAS,CACb,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;QACJ,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAC1B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;KACvC,GAAG,gBAAqB,GACxB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAW9B,6FAA6F;IACvF,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;QACJ,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAC7B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;QACtC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAA;KACpD,GAAG,gBAAqB,GACxB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAY9B,gDAAgD;IAChD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI3E,8EAA8E;IAC9E,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,UAAU,GAAG,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;IAIrF,gGAAgG;IAChG,SAAS,CAAC,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,gBAAqB,GAAG,OAAO,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC;IAIhG,sDAAsD;IACtD,SAAS,CAAC,IAAI,GAAE,gBAAgB,GAAG,gBAAqB,GAAG,OAAO,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC;IAIrF,yDAAyD;IACzD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAIhF,oDAAoD;IACpD,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7B,uCAAuC;IACjC,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAIvC,qDAAqD;IACrD,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC;IAIjC,oEAAoE;IAC9D,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAMrD,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAIlD,oCAAoC;IACpC,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAC9D,OAAO,CAAC,IAAI,CAAC;IAIhB,gCAAgC;IAChC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,qFAAqF;IACrF,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvC,0FAA0F;IAC1F,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIxD;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1E,yDAAyD;IACzD,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,OAAO,GAAG,QAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlF,4FAA4F;IAC5F,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;;;OAIG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtE,4EAA4E;IAC5E,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,CAAC,CAAC,aAAa,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1F,6EAA6E;IAC7E,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;IAIjE,+EAA+E;IAC/E,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD,mDAAmD;IACnD,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GACrE,OAAO,CAAC,IAAI,CAAC;IAIhB,8DAA8D;IAC9D,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG5F"}
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../async.ts"],"names":[],"mappings":"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"}

package/dist/async.js

@@ -8,21 +8,35 @@
  * sync client would block the event loop: a fan-out of per-PR queries.
  */
 import { runCheckedAsync, resolveRunnerAsync, } from '@osdlc/command-seam';
-import { parseOwnerRepo } from "./repo.js";
+import { ownerRepoSlug, parseOwnerRepo, parsePrRef } from "./repo.js";
 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. */
+/**
+ * A typed, awaitable gh client bound to one working directory, and optionally
+ * to one repository and host. `repo` and `hostname` work as on `Gh`.
+ */
 export class AsyncGh {
     cwd;
+    repo;
+    hostname;
+    target;
     runner;
     constructor(cwd, opts = {}) {
+        v.checkTarget(opts);
         this.cwd = cwd;
+        this.repo = opts.repo;
+        this.hostname = opts.hostname;
+        this.target = { repo: opts.repo, hostname: opts.hostname };
         this.runner = resolveRunnerAsync('gh', opts.runner);
     }
-    /** The same client rooted at a different directory (same runner). */
+    /** The same client rooted at a different directory (same runner, repo and host). */
     at(cwd) {
-        return new AsyncGh(cwd, { runner: this.runner });
+        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). */
+    withRepo(repo) {
+        return new AsyncGh(this.cwd, { runner: this.runner, repo, hostname: this.hostname });
     }
     // ── escape hatches ────────────────────────────────────────────────────────
     /** Unchecked passthrough for verbs not yet lifted into the API. */
@@ -38,6 +52,8 @@ export class AsyncGh {
         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)
@@ -50,11 +66,25 @@ export class AsyncGh {
     // ── queries ───────────────────────────────────────────────────────────────
     /** Pull requests matching `opts`, or null when gh failed. */
     prList(opts = {}) {
-        return this.exec(v.prList(opts), opts);
-    }
-    /** One PR with the heavy fields, or null when gh failed. */
-    prView(number, opts = {}) {
-        return this.exec(v.prView(number, opts.fields ?? v.PR_VIEW_FIELDS), opts);
+        return this.exec(v.prList(opts, this.target), opts);
+    }
+    /** One PR by number, branch or URL, with the heavy fields, or null. See `Gh.prView`. */
+    prView(ref, opts = {}) {
+        return this.exec(v.prView(ref, opts.fields ?? v.PR_VIEW_FIELDS, this.target), opts);
+    }
+    /** The one PR that `input` names, or null. See `Gh.prFind`. */
+    async prFind(input, opts = {}) {
+        const ref = parsePrRef(input);
+        if (ref === null)
+            return null;
+        const call = { ...opts, fields: opts.fields ?? v.PR_LIST_FIELDS };
+        if (ref.kind === 'url')
+            return this.prView(ref.url, call);
+        if (ref.kind === 'branch')
+            return prForBranchOn(this, ref.name, call);
+        const client = ref.repo === null ? this : this.withRepo(ownerRepoSlug(ref.repo));
+        const pr = await client.prView(ref.number, call);
+        return pr !== null || ref.orBranch === null ? pr : prForBranchOn(this, ref.orBranch, call);
     }
     /** The open PR whose head exactly equals `branch`, or null. See `Gh.openPrFor`. */
     async openPrFor(branch, opts = {}) {
@@ -65,7 +95,7 @@ export class AsyncGh {
             timeoutMs: opts.timeoutMs,
             signal: opts.signal,
         });
-        return v.pickPrForBranch(rows, branch);
+        return v.pickPrForBranch(rows?.rows ?? null, branch);
     }
     /** {@link prView}, re-asked until GitHub settles the merge state. See `Gh.prViewSettled`. */
     async prViewSettled(number, opts = {}) {
@@ -83,23 +113,43 @@ export class AsyncGh {
     }
     /** A PR's body text, or null when gh failed. */
     prBody(number, opts = {}) {
-        return this.exec(v.prBody(number), opts);
+        return this.exec(v.prBody(number, this.target), opts);
     }
     /** A REST GET through `gh api`; failure is `ok: false`, never a rejection. */
     api(endpoint, opts = {}) {
-        return this.exec(v.api(endpoint, opts), opts);
+        return this.exec(v.api(endpoint, opts, this.target), opts);
+    }
+    /**
+     * A GraphQL query; each page's `data`, or null. See `Gh.graphql`.
+     *
+     * @experimental
+     */
+    graphql(query, variables = {}, opts = {}) {
+        return this.exec(v.graphql(query, variables, opts, this.target), opts);
     }
     /** Every label on the repository (up to `opts.limit`, default 1000), or null when gh failed. */
     labelList(opts = {}) {
-        return this.exec(v.labelList(opts), opts);
+        return this.exec(v.labelList(opts, this.target), opts);
     }
     /** Issues matching `opts`, or null when gh failed. */
     issueList(opts = {}) {
-        return this.exec(v.issueList(opts), opts);
+        return this.exec(v.issueList(opts, this.target), opts);
     }
     /** One issue with its labels, or null when gh failed. */
     issueView(number, opts = {}) {
-        return this.exec(v.issueView(number), opts);
+        return this.exec(v.issueView(number, this.target), opts);
+    }
+    /** An owner's repositories, or null when gh failed. See `Gh.repoList`. */
+    repoList(owner, opts = {}) {
+        return this.exec(v.repoList(owner, opts, this.target), opts);
+    }
+    /** One repository, or null when gh failed. See `Gh.repoView`. */
+    repoView(repo, opts = {}) {
+        return this.exec(v.repoView(repo, opts.fields ?? v.REPO_FIELDS, this.target), opts);
+    }
+    /** Pull requests across repositories matching a search query, or null. See `Gh.searchPrs`. */
+    searchPrs(query, opts = {}) {
+        return this.exec(v.searchPrs(query, opts, this.target), opts);
     }
     /** True iff the `gh` binary is on PATH and runs. */
     installed() {
@@ -111,7 +161,7 @@ export class AsyncGh {
     }
     /** Login state and what `gh auth status` printed. */
     authStatus() {
-        return this.exec(v.authStatus());
+        return this.exec(v.authStatus(this.target));
     }
     /** True iff `gh` is installed AND authenticated; short-circuits. */
     async ready() {
@@ -127,23 +177,23 @@ export class AsyncGh {
     // ── mutations (checked) ───────────────────────────────────────────────────
     /** Open a PR and resolve to its URL ('' if gh printed none). */
     createPr(opts) {
-        return this.exec(v.createPr(opts));
+        return this.exec(v.createPr(opts, this.target));
     }
     /** Retitle or rewrite a PR body. */
     editPr(number, opts) {
-        return this.exec(v.editPr(number, opts));
+        return this.exec(v.editPr(number, opts, this.target));
     }
     /** Rewrite just a PR's body. */
     editPrBody(number, body) {
-        return this.exec(v.editPrBody(number, body));
+        return this.exec(v.editPrBody(number, body, this.target));
     }
     /** The PR's unified diff; rejects with `CommandFailed` when gh cannot produce it. */
     prDiff(number) {
-        return this.exec(v.prDiff(number));
+        return this.exec(v.prDiff(number, this.target));
     }
     /** Post one conversation comment on a PR; resolves to its URL ('' if gh printed none). */
     prComment(number, body) {
-        return this.exec(v.prComment(number, body));
+        return this.exec(v.prComment(number, body, this.target));
     }
     /**
      * Create a `COMMENT` review with inline comments; resolves to the review's URL ('' if none came back).
@@ -151,15 +201,15 @@ export class AsyncGh {
      * @experimental
      */
     createReview(number, opts) {
-        return this.exec(v.createReview(number, opts));
+        return this.exec(v.createReview(number, opts, this.target));
     }
     /** Bring a PR's head branch up to date with its base. */
     prUpdateBranch(number, style = 'merge') {
-        return this.exec(v.prUpdateBranch(number, style));
+        return this.exec(v.prUpdateBranch(number, style, this.target));
     }
     /** Mark a PR ready for review (`draft: false`) or convert it to a draft (`draft: true`). */
     prSetDraft(number, draft) {
-        return this.exec(v.prSetDraft(number, draft));
+        return this.exec(v.prSetDraft(number, draft, this.target));
     }
     /**
      * Rewrite one PR conversation comment's body. `commentId` is the numeric REST id; anything else rejects with `RangeError`.
@@ -168,29 +218,41 @@ export class AsyncGh {
      */
     async issueCommentEdit(commentId, body) {
         // async, so a bad id rejects the Promise instead of throwing at the call.
-        return this.exec(v.issueCommentEdit(commentId, body));
+        return this.exec(v.issueCommentEdit(commentId, body, this.target));
     }
     /** Merge a PR; GitHub refuses when its head is no longer `opts.headSha`. */
     prMerge(number, opts) {
-        return this.exec(v.prMerge(number, opts));
+        return this.exec(v.prMerge(number, opts, this.target));
     }
     /** A PR's review threads, or null when they could not be read completely. */
     prReviewThreads(number) {
-        return this.exec(v.prReviewThreads(number));
+        return this.exec(v.prReviewThreads(number, this.target));
     }
     /** Create a label (or force it to `opts`'s color/description if it exists). */
     createLabel(opts) {
-        return this.exec(v.createLabel(opts));
+        return this.exec(v.createLabel(opts, this.target));
     }
     /** Recolor and/or redescribe an existing label. */
     editLabel(name, opts) {
-        return this.exec(v.editLabel(name, opts));
+        return this.exec(v.editLabel(name, opts, this.target));
     }
     /** Swap an issue's label in a single `gh issue edit` call. */
     setIssueLabel(number, currentLabel, newLabel) {
-        return this.exec(v.setIssueLabel(number, currentLabel, newLabel));
+        return this.exec(v.setIssueLabel(number, currentLabel, newLabel, this.target));
     }
 }
+/** The open PR for `branch`, else its newest closed or merged one. */
+async function prForBranchOn(gh, branch, call) {
+    const rows = await gh.prList({
+        head: branch,
+        state: 'all',
+        limit: 20,
+        fields: v.branchPrFields(call.fields),
+        timeoutMs: call.timeoutMs,
+        signal: call.signal,
+    });
+    return v.branchPr(rows);
+}
 function sleepAsync(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/index.d.ts

@@ -16,11 +16,11 @@
  *
  * Authentication is `gh`'s. No token is read, stored, or forwarded.
  */
-export { AsyncGh, type AsyncCallOptions } from './async.ts';
-export { Gh, defaultRunnerFactory, type RunnerFactory } from './sync.ts';
-export { api, authStatus, createPr, editPr, editPrBody, createLabel, createReview, editLabel, installed, issueList, issueView, labelList, openPrsForBranch, pickPrForBranch, prBody, prComment, prSetDraft, issueCommentEdit, prDiff, prList, prMerge, prReviewThreads, prUpdateBranch, prView, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, type ApiOptions, type ApiResponse, type AuthStatus, type CreateLabelOptions, type CreatePrOptions, type CreateReviewOptions, type GhVerb, type IssueListOptions, type PrListOptions, type PrMergeMethod, type ReviewComment, type ReviewThread, } from './verbs.ts';
+export { AsyncGh, type AsyncCallOptions, type AsyncGhOptions } from './async.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, parsePrUrl, type PullRequestRef } from './repo.ts';
-export type { Actor, CheckConclusion, CheckRun, Comment, IssueRow, Label, MergeableState, MergeStateStatus, OwnerRepo, PullRequest, PullRequestState, Review, ReviewDecision, ReviewState, } from './types.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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE3D,OAAO,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAExE,OAAO,EACL,GAAG,EACH,UAAU,EACV,QAAQ,EACR,MAAM,EACN,UAAU,EACV,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,MAAM,EACN,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,MAAM,EACN,MAAM,EACN,OAAO,EACP,eAAe,EACf,cAAc,EACd,MAAM,EACN,aAAa,EACb,cAAc,EACd,aAAa,EACb,cAAc,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEnF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAA;AAE1F,YAAY,EACV,KAAK,EACL,eAAe,EACf,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,KAAK,EACL,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,MAAM,EACN,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAA;AAKnB,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhF,OAAO,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAExF,OAAO,EACL,GAAG,EACH,UAAU,EACV,QAAQ,EACR,MAAM,EACN,UAAU,EACV,OAAO,EACP,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,OAAO,EACP,gBAAgB,EAChB,eAAe,EACf,MAAM,EACN,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,MAAM,EACN,MAAM,EACN,OAAO,EACP,eAAe,EACf,cAAc,EACd,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,aAAa,EACb,cAAc,EACd,aAAa,EACb,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEnF,OAAO,EACL,aAAa,EACb,cAAc,EACd,UAAU,EACV,UAAU,EACV,KAAK,KAAK,EACV,KAAK,cAAc,GACpB,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,KAAK,EACL,eAAe,EACf,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,KAAK,EACL,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,oBAAoB,EACpB,MAAM,EACN,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAA;AAKnB,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAA"}

package/dist/index.js

@@ -18,9 +18,9 @@
  */
 export { AsyncGh } from "./async.js";
 export { Gh, defaultRunnerFactory } from "./sync.js";
-export { api, authStatus, createPr, editPr, editPrBody, createLabel, createReview, editLabel, installed, issueList, issueView, labelList, openPrsForBranch, pickPrForBranch, prBody, prComment, prSetDraft, issueCommentEdit, prDiff, prList, prMerge, prReviewThreads, prUpdateBranch, prView, setIssueLabel, PR_LIST_FIELDS, PR_REF_FIELDS, PR_VIEW_FIELDS, } from "./verbs.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, parsePrUrl } from "./repo.js";
+export { ownerRepoSlug, parseOwnerRepo, parsePrRef, parsePrUrl, } from "./repo.js";
 // The seam's error and runner types appear in this package's signatures, so
 // they are re-exported. Its functions are not: import them from
 // `@osdlc/command-seam`.

package/dist/parse.d.ts

@@ -17,7 +17,7 @@
  *     `StatusContext` carries `context`/`state`. They are folded onto one
  *     verdict axis so a caller never has to know which it got.
  */
-import type { Actor, CheckRun, Label, PullRequest } from './types.ts';
+import type { Actor, CheckRun, Label, PrSearchHit, PullRequest, Repository } from './types.ts';
 /**
  * Strip a single trailing `[bot]` suffix — REST shape folded to GraphQL shape.
  *
@@ -43,4 +43,8 @@ export declare function parseLabels(x: unknown): Label[];
  * any field subset.
  */
 export declare function parsePullRequest(raw: unknown): PullRequest | null;
+/** A `gh repo list`/`view --json` row as a {@link Repository}, or null without `nameWithOwner`. */
+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/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,KAAK,EAEL,QAAQ,EAER,KAAK,EAEL,WAAW,EAGZ,MAAM,YAAY,CAAA;AAqCnB;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAUnD;AAiBD,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAuCzD;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAEnE;AAID,6OAA6O;AAC7O,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,EAAE,CAS/C;AA4CD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAkCjE"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,KAAK,EAEL,QAAQ,EAER,KAAK,EAEL,WAAW,EACX,WAAW,EACX,UAAU,EAGX,MAAM,YAAY,CAAA;AAqCnB;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAUnD;AAiBD,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAuCzD;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAEnE;AAID,6OAA6O;AAC7O,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,EAAE,CAS/C;AA4CD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAkCjE;AAID,mGAAmG;AACnG,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAgB/D;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAwBjE"}

package/dist/parse.js

@@ -223,3 +223,51 @@ export function parsePullRequest(raw) {
         updatedAt: strOrNull(raw['updatedAt'] ?? raw['updated_at']),
     };
 }
+// ── repositories and search ─────────────────────────────────────────────────
+/** A `gh repo list`/`view --json` row as a {@link Repository}, or null without `nameWithOwner`. */
+export function parseRepository(raw) {
+    if (!isRecord(raw))
+        return null;
+    const nameWithOwner = str(raw['nameWithOwner']);
+    const slash = nameWithOwner.indexOf('/');
+    if (slash <= 0 || slash === nameWithOwner.length - 1)
+        return null;
+    const branch = raw['defaultBranchRef'];
+    return {
+        nameWithOwner,
+        owner: nameWithOwner.slice(0, slash),
+        name: nameWithOwner.slice(slash + 1),
+        description: str(raw['description']),
+        defaultBranch: isRecord(branch) ? strOrNull(branch['name']) : null,
+        visibility: strOrNull(raw['visibility']),
+        isArchived: bool(raw['isArchived']),
+        url: str(raw['url']),
+    };
+}
+/** A `gh search prs --json` row as a {@link PrSearchHit}, or null without a `number`. */
+export function parsePrSearchHit(raw) {
+    if (!isRecord(raw))
+        return null;
+    const number = raw['number'];
+    if (typeof number !== 'number')
+        return null;
+    const repo = raw['repository'];
+    const slug = isRecord(repo) ? str(repo['nameWithOwner']) : '';
+    const slash = slug.indexOf('/');
+    return {
+        number,
+        title: str(raw['title']),
+        // Search answers in lower case; `PullRequest.state` is upper case.
+        state: str(raw['state']).toUpperCase(),
+        url: str(raw['url']),
+        isDraft: bool(raw['isDraft']),
+        repository: slash > 0 && slash < slug.length - 1
+            ? { owner: slug.slice(0, slash), repo: slug.slice(slash + 1) }
+            : null,
+        author: parseActor(raw['author']),
+        labels: parseLabels(raw['labels']),
+        createdAt: strOrNull(raw['createdAt']),
+        updatedAt: strOrNull(raw['updatedAt']),
+        closedAt: strOrNull(raw['closedAt']),
+    };
+}

package/dist/repo.d.ts

@@ -15,22 +15,54 @@ import type { OwnerRepo } from './types.ts';
 export declare function parseOwnerRepo(remoteUrl: string): OwnerRepo | null;
 /** `owner/repo`, the form `gh api` paths and `--repo` both take. */
 export declare function ownerRepoSlug(r: OwnerRepo): string;
-/** A pull request coordinate: the repository and the PR's number within it. */
+/** A pull request coordinate: the host, the repository and the PR's number within it. */
 export interface PullRequestRef extends OwnerRepo {
+    /** The GitHub host, lower-cased: `github.com`, or an Enterprise host. */
+    hostname: string;
     number: number;
 }
 /**
- * The `{owner, repo, number}` a GitHub pull-request URL names, or null when
- * `url` is not one.
+ * The `{hostname, owner, repo, number}` a GitHub pull-request URL names, or
+ * null when `url` is not one.
  *
- * Accepts `https://github.com/<owner>/<repo>/pull/<n>` with or without a
- * scheme, a `www.` prefix, a trailing slash, a sub-page (`/files`,
- * `/commits`), a query string or a fragment — every shape a browser's address
- * bar hands over. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
+ * Accepts `https://<host>/<owner>/<repo>/pull/<n>` with or without a scheme,
+ * a trailing slash, a sub-page (`/files`, `/commits`), a query string or a
+ * fragment — every shape a browser's address bar hands over. The host is
+ * `github.com` (a `www.` prefix is dropped) or a GitHub Enterprise host such
+ * as `github.acme.com` or `acme.ghe.com`; without a scheme the host must
+ * contain a dot. `parseGitUrl` is the wrong tool here: it reads `/pull/<n>`
  * as part of the project path.
- *
- * GitHub.com only. A GitHub Enterprise host is a different coordinate space
- * (the `gh` CLI needs `--hostname`), so it is not silently accepted.
  */
 export declare function parsePrUrl(url: string): PullRequestRef | null;
+/**
+ * What a person typed to name a pull request, read by {@link parsePrRef}.
+ *
+ * - `number`: `42`, `#42`, or `owner/name#42` (then `repo` is set). For bare
+ *   digits, `orBranch` holds the same text, since a branch can be named `42`.
+ * - `url`: a pull request URL, with what {@link parsePrUrl} read from it.
+ * - `branch`: any other text that is a valid branch name.
+ */
+export type PrRef = {
+    kind: 'number';
+    number: number;
+    repo: OwnerRepo | null;
+    orBranch: string | null;
+} | ({
+    kind: 'url';
+    url: string;
+} & PullRequestRef) | {
+    kind: 'branch';
+    name: string;
+};
+/**
+ * Read what a person typed to name a pull request: a number, `#42`,
+ * `owner/name#42`, a URL, or a branch name. Null when it is none of these.
+ *
+ * Pure: it starts no process. Digits are read as a number first, the way
+ * `gh pr view 42` reads them; `orBranch` keeps the branch reading. The
+ * clients' `prFind` tries both.
+ */
+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/repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../repo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMlE;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAElD;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAS7D"}
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../repo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMlE;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAElD;AAED,yFAAyF;AACzF,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAgB7D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,KAAK,GACb;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACnF,CAAC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAAC,GAC/C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpC;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAwBtD;AAED,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD"}