@gitkraken/core-gitlens 0.4.0 → 0.4.100

package/docs/integrations.md

@@ -0,0 +1,372 @@
+# Consuming `@gitkraken/core-gitlens` integrations
+
+How to read provider data (pull requests, issues, orgs, projects, repos, repository identity) from
+`@gitkraken/core-gitlens` as an external consumer — the surface Kepler migrates onto in
+[kepler#1322](https://github.com/gitkraken/kepler/issues/1322).
+
+Scope: the **provider-neutral facade** (`plus/integrations/index.js`). It hands back GitLens-owned shapes and
+never leaks `@gitkraken/provider-apis` types, so a consumer depends on this package alone.
+
+- Read-API parity decisions and the provider-apis-level contract: [`kepler-read-api-parity.md`](./kepler-read-api-parity.md)
+- `@gitlens/git` service wiring (a separate boundary):
+  [`library-architecture.md`](https://github.com/gitkraken/vscode-gitlens/blob/core/docs/library-architecture.md)
+
+---
+
+## 1. Entry points
+
+| Subpath                                              | Use it for                                                                         |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `@gitkraken/core-gitlens/plus/integrations/index.js` | The session-managed facade: manager factory, public types, and connection helpers. |
+| `@gitkraken/core-gitlens/plus/integrations/lite.js`  | Stateless, token-scoped single reads (no storage/auth lifecycle). See §10.         |
+| `@gitkraken/core-gitlens/git/models/*.js`            | The returned models (`PullRequestShape`, `IssueShape`, …).                         |
+
+Everything else under `plus/integrations/**` is internal. `IntegrationService`, the `GitHostIntegration`
+models, and the provider clients are deliberately **not** on the facade: they change without a semver bump.
+`manager.js` / `results.js` are not published subpaths either — their types are re-exported through
+`index.js`, so import them from there.
+
+> If a type you need to name isn't exported from `index.js`, that's a bug in this package — file it rather
+> than re-declaring the shape downstream, which silently drifts.
+
+## 2. Building the runtime
+
+`createIntegrationManager(ctx)` takes one argument: an `IntegrationManagerContext`. It is the **single**
+cross-boundary contract — the package never imports `vscode` and has no ambient globals. The extension host's
+broader `IntegrationServiceContext` is internal and is not part of the published facade.
+
+| Provider       | Required | What it must do                                                                                                                                                                                  |
+| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `storage`      | yes      | Global + workspace key/value, plus a secret store (tokens land here).                                                                                                                            |
+| `account`      | yes      | The GitKraken account and the GK-cloud connect/manage round-trips. Return `undefined` from `getAccount` if you don't use GK cloud (see below).                                                   |
+| `config`       | yes      | `getRemoteConfigs()` (self-managed hosts, SSL/protocol overrides), launchpad knobs, a change event.                                                                                              |
+| `http`         | yes      | `fetch` + `wrapForForcedInsecureSSL` + `isWeb` + a User-Agent string.                                                                                                                            |
+| `cache`        | no       | `IntegrationManagerCacheProvider`, whose only method is `getCurrentAccount`. Omit it for correct uncached reads; implement it for a long-lived manager to deduplicate provider identity lookups. |
+| `repositories` | yes      | `getOpenRemotes()`; used only by the "across open repos" helpers. `async () => []` is fine.                                                                                                      |
+| `hooks`        | no       | Auth strategy override, reauth/disconnect prompts, outbound behavioral events.                                                                                                                   |
+
+A complete, type-checked, dependency-free example (including the optional-cache path) lives in
+[`tests/fixtures/integrations-consumer/src/consumer.test.ts`](https://github.com/gitkraken/vscode-gitlens/blob/core/tests/fixtures/integrations-consumer/src/consumer.test.ts).
+It runs against the packed artifact in CI, so it catches missing exports as well as source-level mistakes:
+use that file's `buildRuntime()` as your starting point.
+
+The cache callback receives only `{ id, domain }`, a loader, and cache controls (`connectionId`, `etag`,
+expiry). It never exposes GitLens' internal `IntegrationBase` / `GitHostIntegration` classes or requires
+stubs for unrelated repository, pull-request, or issue caches. The fixture uses the package's public
+`PromiseCache` utility, but any cache with the same behavior is valid.
+
+### Authentication
+
+Two strategies, both through the same context:
+
+1. **GK cloud (what GitLens does).** Implement `account.connect` / `openManagement` / `fetchGkApi`; the
+   package syncs connections, stores per-connection sessions, tracks primaries, and reconciles multi-account
+   state on check-in. `refreshConnections()` forces that sync on demand.
+2. **Your own tokens.** Return a provider from the `hooks.createAuthenticationProvider` hook.
+   `createManualTokenAuthProvider({ id, token, account, domain? })` wraps a static token; for refreshable
+   tokens implement `IntegrationAuthenticationProvider` directly. A manual-token session never expires and
+   returns `undefined` on `forceNewSession`, so a reauth-on-failure loop terminates.
+
+### Lifecycle
+
+```ts
+const manager = createIntegrationManager(runtime);
+try {
+	/* reads */
+} finally {
+	manager.dispose(); // tears down cached integrations, auth providers, and every host subscription
+}
+```
+
+`onDidChange` fires when the configured-connection set changes; `onDidChangeConnectionState` when a
+provider connects/disconnects. Both are safe to drive cache invalidation from.
+
+`refreshConnections()` is an authoritative foreground refresh: it rejects if the GK backend connection list
+cannot be read and leaves the last known configuration intact. Background check-in remains best-effort.
+
+## 3. Multi-account and self-managed hosts
+
+Three knobs, in precedence order, select **which account and which host** a read runs against:
+
+| Option         | Meaning                                                                                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `connectionId` | A specific connection from `getConfigured()`. Wins over everything. An unresolvable one is a `no-connection` warning + `fetchFailed`, never an empty result. |
+| `domain`       | Fallback host for a self-managed provider with no configured connection (manual-token/external auth).                                                        |
+| neither        | The provider's primary connection; for a self-managed provider, the primary configured host.                                                                 |
+
+An explicitly supplied `connectionId` or `domain` must be non-empty; whitespace does not fall back to the
+primary account. For `listOrgs` and `listProjects`, either selector also requires `providerId` because it
+cannot be applied unambiguously to a cross-provider fan-out.
+
+`domain` **must** come from your trusted authentication configuration, never from repository or remote data:
+it selects which credentials a read uses, and `resolveRepository` deliberately refuses to resolve a
+self-managed remote against a host the user hasn't authenticated (`host-mismatch`).
+Use the facade's `hostFromDomain()` when comparing a stored URL-shaped domain with a remote host; this is the
+same normalization used internally for connection selection.
+
+Use `getConfigured(id?, { cloud?, domain? })` to enumerate connections, `setPrimaryConnection` /
+`deleteConnection` to manage them. Both mutations validate that `connectionId` belongs to the requested
+provider before calling the token backend; never reuse an id discovered under a different provider.
+
+## 4. The reads
+
+Every read returns `ProviderResult<T>` (`items` + `warnings` + `fetchFailed?`), and every paged read extends
+it with `page` + `hasMore` + `cursor?`. **No read throws for a provider-side failure** — see §6.
+
+| Method                       | Returns                   | Scope                                                                                 |
+| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------- |
+| `listOrgs`                   | `ProviderOrganization`    | Orgs / workspaces / groups; issue-tracker resources (Jira sites, …).                  |
+| `listProjects`               | `ProviderOrganization`    | The project tier: Azure DevOps, and issue-tracker projects.                           |
+| `listRepos`                  | `ProviderRepositoryShape` | Repos of an `org`, or account-wide user-affiliated repos when `org` is omitted.       |
+| `listPullRequestsPage`       | `PullRequestShape`        | With `repos`: those repos' PRs. Without: the user's PRs account-wide.                 |
+| `listIssuesPage`             | `IssueShape`              | Same split, for a **git host**'s issues.                                              |
+| `listIssueTrackerIssuesPage` | `IssueShape`              | Jira / Linear / Trello (issues live under resource → project).                        |
+| `sweepPullRequests`          | `ProviderSweepResult`     | Drains **every** page across providers (`maxPages`, default 100).                     |
+| `sweepClosedPullRequests`    | `ProviderSweepResult`     | Same, pinned to `['closed','merged']`.                                                |
+| `broadenIssues`              | `ProviderBroadenResult`   | Per-org fan-out: list the org's repos, then read their issues unfiltered by assignee. |
+| `resolveRepository`          | `ResolveRepositoryResult` | Remote URL → canonical provider identity (the `gk repo resolve` equivalent).          |
+| `getSupportedFilters`        | filter capability table   | Static, connection-free. See §7.                                                      |
+
+A provider that cannot serve a surface says so explicitly — a warning explaining that the operation is
+unsupported plus `fetchFailed`, never a silent empty page. That distinction is the whole point of the result
+shape: an empty `items` with no warning means "this account genuinely has nothing".
+
+## 5. Paging
+
+Two mechanisms live behind one shape, and they are **not** interchangeable:
+
+- **`cursor`** — an opaque continuation. Threading it back guarantees **one upstream request per scope**.
+- **`page`** (1-based) — a position. On a cursor-driven read (GitHub's searches and the broaden fan-out,
+  plus provider account-wide reads that return continuations), asking for page N _without_ a cursor makes the
+  facade drain pages 1..N internally and
+  return only page N: correct, but **O(N) upstream requests**. That drain is the supported fallback for a
+  consumer that persisted only a page number (e.g. the first read after a restart).
+
+Pass **both**: `page` labels the position in `page.currentPage`, the cursor is what actually advances.
+
+```ts
+let cursor: string | undefined;
+for (let page = 1; ; page++) {
+	const result = await manager.listPullRequestsPage({ providerId, page, cursor });
+	consume(result.items, result.warnings);
+	if (!result.hasMore) break; // `hasMore` is never true without a usable `cursor`
+	cursor = result.cursor;
+}
+```
+
+Invariants worth relying on:
+
+- `hasMore: true` **always** comes with a `cursor` you can act on. A provider that claims another page but
+  hands back no continuation is reported as terminal-but-incomplete: `hasMore: false` + `page.truncated`.
+  So `while (hasMore)` cannot spin.
+- `page.currentPage` is **positional**, uniform across every paged read. Continue from `cursor`, not from
+  `currentPage + 1` — a cursor-only host can't be addressed by number.
+- A page past the provider's last one is an **empty page N**, never page N−1 relabeled.
+- `page.itemsPerPage` describes the page that came back; don't infer totals or "last page" from it.
+- Composite fan-out cursors retain each scope's exact continuation or retry position. Round-trip the cursor
+  even after a partial result: healthy scopes advance while a failed scope retries the page it missed.
+- Sweeps drain internally and expose **no** cursor: `hasMore` is always `false`. Gate "this is the complete
+  set" on `page.allPages === true`, which is false for _both_ truncation and failure — unlike
+  `page.truncated`, which can be misread as a benign cap.
+
+## 6. Failures: warnings, `fetchFailed`, `truncated`
+
+A per-provider (or per-connection, or per-scope) failure degrades to a **warning attached to a partial
+result** instead of rejecting the call. One provider's expired token never blanks the other providers' data.
+
+`ProviderWarning.kind` (also exported as `ProviderWarningKind`) carries the classifications the facade can
+prove from structured errors:
+
+| `kind`          | Meaning                                                                                       | Reasonable response                                                                         |
+| --------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `auth`          | Token rejected (401/403 that isn't a throttle).                                               | Prompt to reconnect that connection.                                                        |
+| `rate-limit`    | Throttled (429, or a 403 whose body says so).                                                 | Back off and retry; keep the last snapshot.                                                 |
+| `not-found`     | 404/410/422 on the requested scope.                                                           | Drop that scope; don't reconnect.                                                           |
+| `no-connection` | The requested `connectionId`/`domain` doesn't resolve.                                        | Re-resolve the target or re-authenticate.                                                   |
+| `other`         | Catch-all: unsupported input, truncation, upstream/network failure, or an unclassified error. | Preserve the warning and use the result flags; do not assume it is benign or non-retryable. |
+
+`isAuth` is a convenience mirror of `kind === 'auth'`. **Collapsing `kind` into that boolean loses the
+rate-limit and not-found distinctions**, which then have to be re-derived from raw provider prose.
+Conversely, `other` is intentionally not a complete failure taxonomy. Treat `message` as display/diagnostic
+text rather than a stable protocol; use `fetchFailed`, `page.truncated`, and `page.allPages` for completeness
+and keep unknown failures conservative.
+
+| Flag                    | Says                                                                                                                                          |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fetchFailed`           | `items` is incomplete because a scope failed, or because a flat hierarchy read was truncated. Distinguishes this from a genuine empty result. |
+| `page.truncated`        | The read completed but couldn't confirm it had everything (provider cap, `maxPages` backstop, or a missing continuation).                     |
+| `page.allPages`         | Sweeps only: `true` iff every page of every target drained cleanly.                                                                           |
+| `failedProviderIds`     | Sweeps/broadens: providers whose requested scopes produced no usable result.                                                                  |
+| `incompleteProviderIds` | Sweeps/broadens: providers with a usable result plus a failed, partial, or truncated sibling scope.                                           |
+
+`resolveRepository` reports through `resolution.status` instead: `resolved` · `not-found` · `unauthorized` ·
+`unsupported-provider` · `invalid-remote-url` · `host-mismatch` · `undetermined`. A `resolved` identity
+carries the provider's **canonical** owner/name plus `renamed: true` when the local remote is stale.
+
+## 7. Filters are all-or-nothing
+
+`filters` (`PullRequestFilter` / `IssueFilter`) narrows repo-scoped reads and account-wide PR/issue reads to
+the current user's relationship with the item. A set containing even **one** filter the provider can't
+express is **refused whole** —
+empty `items` + warning + `fetchFailed` — because falling through unfiltered would return _every_ PR
+instead of the user's.
+
+So intersect against the capability table first:
+
+```ts
+const supported = manager.getSupportedFilters(providerId); // static, no connection needed
+const capability = repos.length === 0 ? (supported.pullRequestsAccountWide ?? []) : supported.pullRequests;
+const filters = wanted.filter(f => capability.includes(f));
+```
+
+- `pullRequests` — the repo-scoped PR read.
+- `pullRequestsAccountWide` — the optional account-wide PR capability. Treat a missing field as empty.
+- `issues` — the **repo-scoped** git-host read, **and** the issue-tracker read
+  (`listIssueTrackerIssuesPage` validates against this field).
+- `issuesAccountWide` — the account-wide git-host read only. Usually narrower (GitLab can express
+  `Assignee` and `Author`, but not `Mention`), and empty for issue trackers.
+
+It's a _capability_ table, not a recommendation: passing fewer filters than listed is fine.
+
+PR filter composition depends on the read:
+
+- **Repo-scoped** members are combined as provider query constraints (normally an intersection). To build
+  `Author ∪ Assignee ∪ ReviewRequested`, issue one paged read per facet and union the results.
+- **Account-wide** members are an exact OR union. The facade fans out or post-filters provider-native
+  relationship slices as required, preserving one composite cursor where the provider pages. A sweep target's
+  `filters` overrides the sweep-level set, which lets a cross-provider caller request each provider's exact
+  supported subset without leaking provider query syntax.
+
+On the account-wide issue read, `filters` **replaces** the provider's own definition of "my issues"
+(GitHub authored ∪ assigned ∪ mentioned; Azure assigned ∪ authored; GitLab assigned-to-me), so
+`[Assignee]` means `assignee:@me` wherever it's expressible. `includeAllAssignees`
+does the opposite (drops the user scope); passing both on that account-wide read is refused as contradictory.
+
+`includeReviewRequested` is a legacy account-wide breadth option used only when no explicit `filters` are
+supplied. It remains useful for Bitbucket Cloud, where the reviewer slice requires an expensive
+O(workspaces × repos) fan-out; prefer `filters: [ReviewRequested]` when an exact relationship is required.
+
+Aggregate account-wide PR reads use a lightweight list shape. Stable list fields, body, and branch refs are
+preserved; optional enrichments such as reviews, checks, and stats may be absent.
+
+## 8. Provider capability matrix
+
+Derived from the provider models and `providersMetadata`. ✓ supported · ✗ reported unsupported
+(warning + `fetchFailed`) · — not applicable. Self-managed variants inherit their cloud family's hooks.
+
+| Surface                      | GitHub / GHE | GitLab / self-hosted | Bitbucket | Bitbucket DC | Azure DevOps (+ Server) | Jira | Linear | Trello |
+| ---------------------------- | :----------: | :------------------: | :-------: | :----------: | :---------------------: | :--: | :----: | :----: |
+| `listOrgs`                   |      ✓       |          ✓           |     ✓     |      ✗       |            ✓            |  ✓   |   ✓    |   ✓    |
+| `listProjects`               |      —       |          —           |     —     |      —       |            ✓            |  ✓   |   ✓    |   ✓    |
+| `listRepos` (`org`)          |      ✓       |          ✓           |     ✓     |      ✗       |            ✓            |  ✗   |   ✗    |   ✗    |
+| `listRepos` (account-wide)   |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |  ✗   |   ✗    |   ✗    |
+| PRs, repo-scoped             |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |  ✗   |   ✗    |   ✗    |
+| PRs, account-wide            |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |  ✗   |   ✗    |   ✗    |
+| PR `states` account-wide     |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |  —   |   —    |   —    |
+| Issues, repo-scoped          |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |  —   |   —    |   —    |
+| Issues, account-wide         |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |  —   |   —    |   —    |
+| Issues by `org`/`project`    |      ✗       |          ✗           |     ✗     |      ✗       |            ✓            |  ✓   |   ✓    |   ✓    |
+| `listIssueTrackerIssuesPage` |      —       |          —           |     —     |      —       |            —            |  ✓   |   ✓    |   ✓    |
+| `broadenIssues`              |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |  ✗   |   ✗    |   ✗    |
+| `resolveRepository`          |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |  ✗   |   ✗    |   ✗    |
+
+Repo-scoped PR filters: GitHub/GHE `Author, Assignee, ReviewRequested, Mention` · GitLab `Author, Assignee,
+ReviewRequested` · Bitbucket + Bitbucket DC `Author, ReviewRequested` · Azure `Author, Assignee,
+ReviewRequested`.
+Account-wide PR filters: GitHub/GHE `Author, Assignee, ReviewRequested, Mention` · GitLab
+`Author, Assignee, ReviewRequested` · Bitbucket + Bitbucket DC `Author, ReviewRequested` · Azure
+`Author, Assignee, ReviewRequested`.
+Issue filters: GitHub/GHE + Azure + Jira `Author, Assignee, Mention` · GitLab `Author, Assignee` ·
+Linear + Trello `Assignee` · Bitbucket family none.
+Account-wide issue filters: GitHub/GHE `Author, Assignee, Mention` · Azure `Author, Assignee` · GitLab
+`Assignee, Author` · everything else none.
+
+> `supportedCloudIntegrationDescriptors.supports` (in `constants.ts`) describes what GitLens _advertises in
+> its connect UI_, including enrichment-only capabilities. It is **not** the read-capability answer — use
+> `getSupportedFilters` and this matrix.
+
+## 9. Per-provider behavior worth designing around
+
+- **GitHub / GHE** — cursor-only everywhere. The account-wide issue read is three searches (`author:@me`,
+  `assignee:@me`, `mentions:@me`) behind one composite cursor; a filtered account-wide PR read is one search
+  per state × relationship facet behind a composite cursor that resumes only active facets. Each search caps
+  at GitHub's own result ceiling, surfaced as `page.truncated`. `includeAllAssignees` is refused account-wide
+  (scope to repos instead).
+- **GitLab / self-hosted** — numbered per-repo cursors for repo-scoped reads. Account-wide PR state selection
+  is forwarded to each relationship query. Account-wide issues can independently narrow to assignee or author;
+  the unfiltered read unions both.
+- **Bitbucket Cloud** — no issues at all on this surface (tracker deprecated; use Jira). No account-wide
+  repo walk (list per workspace). The account-wide PR read drains every workspace and returns **one
+  aggregate page** (no cross-workspace cursor), so `itemsPerPage` doesn't apply. The review-requested slice
+  is opt-in via `includeReviewRequested: true`, because it costs an O(workspaces × repos) fan-out.
+- **Bitbucket Data Center** — no org discovery, no repo discovery, no issues. `provider-apis` converts the
+  public 1-based page number to the REST `start` offset and normalizes `nextPageStart` back to a page number;
+  the facade carries that number inside its opaque cursor.
+- **Azure DevOps** — org + project scoped. Repo-scoped reads accept one org per call. Account-wide reads
+  drain every project of every org and return one aggregate page; a failed project becomes a scoped warning
+  while its siblings survive. Only Azure can narrow an account-wide issue read by `org`/`project`.
+  `resolveRepository` needs a project in the remote URL. Azure DevOps Server uses the trusted connection's
+  domain/protocol as `baseUrl`; the remote host must match that configured connection.
+- **Jira / Linear / Trello** — paged by **project**, not by issue: `itemsPerPage` counts projects (default
+  20), each drained in full. Passing none of `page`/`cursor`/`itemsPerPage` aggregates every matched project
+  in one page. A single project exceeding its internal drain backstop shows up as `page.truncated`.
+  Trello's issue `id` is the card's `idShort` — unique per board only, so correlate across boards by
+  `nodeId`. For Trello, boards are both the resource and the project, so `listOrgs` and `listProjects`
+  return the same set; Linear's resource is the organization and its projects are teams.
+  Thread the returned cursor verbatim: it can combine the next untouched project window with discovery/project
+  retries, preserve a caller's aggregate-all mode, and suppress projects already emitted before discovery
+  recovered. `hasMore` reports only untouched forward progress. A cursor can therefore remain with
+  `hasMore: false`; reusing it is an explicit manual retry of failed work, not a normal paging loop.
+
+The same warning holds for `IssueShape.id` generally: it's the provider's **display** number/key (rendered
+as `#{id}`, used for branch names). `nodeId` is the stable provider-native id, but its uniqueness scope is
+provider-specific (Azure work-item ids are organization-scoped). For cross-scope correlation, key by
+provider/domain plus repository or project identity and `nodeId`; `url` is also unique for the provider reads
+that require one.
+
+## 10. Token-scoped reads (`lite.js`)
+
+For a consumer that already holds a provider token and wants one stateless read — no storage, no session
+lifecycle, no OAuth:
+
+```ts
+import { createTokenScopedGitHostIntegration } from '@gitkraken/core-gitlens/plus/integrations/lite.js';
+
+const api = createTokenScopedGitHostIntegration(
+	GitCloudHostIntegrationId.GitHub,
+	{ accessToken: token },
+	{ fetch: fetch },
+);
+const metadata = await api.getRepositoryMetadata('gitkraken', 'vscode-gitlens');
+```
+
+Supports `getRepositoryMetadata` + `getDefaultBranch` for GitHub/GHE, GitLab/self-hosted, Bitbucket Cloud,
+and Azure DevOps (+ Server). **Not** Bitbucket Data Center. A self-managed id requires `token.domain`
+(it throws otherwise, rather than building a malformed base URL). Azure encodes the repo as
+`"{project}/_git/{repoName}"`.
+
+## 11. Checklist for a new consumer
+
+1. Start from `buildRuntime()` in the consumer fixture; implement `storage` for real. Add
+   `cache.getCurrentAccount` when the manager is long-lived or provider identity reads are frequent.
+2. Pick an auth strategy (§2) and verify `getConfigured()` reflects your connections.
+3. Thread `connectionId` through every read if you support multiple accounts per provider.
+4. Persist the **opaque `cursor`**, not just a page number (§5).
+5. Branch on specific `warning.kind` values, handle `other` conservatively, and gate caching on
+   `fetchFailed` / `page.allPages` (§6).
+6. Intersect repo-scoped and account-wide `filters` against their distinct `getSupportedFilters` fields (§7).
+7. Treat "unsupported" as a first-class outcome per provider (§8) — don't render it as an error.
+8. `dispose()` the manager with the owning scope.
+
+## 12. Development and publication prerequisite
+
+The current `core` branch depends on the provider fixes used by this facade: GitLab author filtering and PR
+state forwarding, GitHub search-completeness metadata, Bitbucket Data Center page normalization, and
+self-managed Azure project-scoped repository lookup. During coordinated development, a local
+`provider-apis` worktree/link may temporarily supply those fixes; that link is a test setup, not a publishable
+dependency contract.
+
+Before publication, replace any local link with the released `@gitkraken/provider-apis` version containing
+the verified fixes and regenerate the workspace catalog/lockfile. Do not publish or bump
+`@gitkraken/core-gitlens` until that dependency is released and the Kepler migration has been verified end to
+end against the packed artifact.

package/docs/kepler-read-api-parity.md

@@ -0,0 +1,112 @@
+# Kepler read-API parity
+
+Authoritative decision record for the read-API parity gaps tracked in
+[#5435](https://github.com/gitkraken/vscode-gitlens/issues/5435) (follow-up to #5430), so Kepler
+([gitkraken/kepler#1325](https://github.com/gitkraken/kepler/issues/1325), epic
+[#1322](https://github.com/gitkraken/kepler/issues/1322)) can migrate its provider reads off the `gk` CLI
+onto `@gitkraken/core-gitlens` with a clear contract.
+
+The baseline provider-side prerequisites landed in `@gitkraken/provider-apis` **0.50.0** (GKDEV-3535,
+GKDEV-3536, GKDEV-3537, GKDEV-3538). The current `core` branch additionally requires the unreleased
+provider changes described in [`integrations.md` §12](./integrations.md#12-development-and-publication-prerequisite).
+
+Verdict legend: **first-class** (honored) · **best-effort** (honored where the provider exposes it cheaply,
+otherwise `undefined`) · **n/a** (provider has no such concept).
+
+For how to actually consume the resulting facade — runtime wiring, the paging/warning contracts, and the
+per-provider capability matrix — see [`integrations.md`](./integrations.md). This
+document stays the decision record for the parity gaps themselves.
+
+## 1. Per-connection reads
+
+`getMyIssuesForRepos` / `getMyPullRequestsForRepos` accept an optional trailing `connectionId` and read with
+that connection's token (mirroring the `connectionId` added to the session-based `searchMy*` reads in #5430).
+Omitting it preserves the provider's primary-connection behavior. The `providersApi` token path
+(`TokenOptInfo` → `getProviderToken` → `getSession`) resolves the requested connection's cloud session; an
+unresolvable or locally-disconnected connection degrades to "no results" without calling the provider.
+
+## 2. Pagination
+
+`PagedResult.paging` now carries `page` / `pageSize` / `nextPage` / `totalPages` / `totalCount` alongside the
+existing `cursor` / `more`. Reads accept `page` / `pageSize`.
+
+| Provider         | Paging   | `hasMore`   | `currentPage` / `totalPages` / `totalCount` | `pageSize` honored  |
+| ---------------- | -------- | ----------- | ------------------------------------------- | ------------------- |
+| GitHub           | cursor   | first-class | `undefined` (cursor)                        | yes (`maxPageSize`) |
+| GitLab           | cursor   | first-class | `undefined` (cursor)                        | yes (`first`)       |
+| Jira             | cursor   | first-class | `undefined` (cursor)                        | yes (`maxResults`)  |
+| Bitbucket        | numbered | first-class | first-class                                 | yes                 |
+| Bitbucket Server | numbered | first-class | first-class                                 | yes                 |
+| Azure DevOps     | numbered | first-class | first-class                                 | yes                 |
+
+**Kepler mapping:** cursor providers can't report a page number; consume `hasMore` for "next page exists" and
+carry the opaque `cursor` forward. For numbered providers, `currentPage` + `totalPages`/`totalCount` map
+directly to Kepler's `{ currentPage, itemsPerPage }`.
+
+**Multi-repo caveat:** the repo-mode providers (GitLab, Bitbucket, Bitbucket Server, Azure) fan a
+`getMy*ForRepos` call out across repos and aggregate the results under a single composite cursor. There the
+numbered metadata (`currentPage`/`totalPages`/`totalCount`) is not aggregated — pagination continues via
+that composite cursor plus `hasMore`. An explicit `page` applies only to the first request per repo; on
+continuation the per-repo cursor takes over (it is not clobbered). The numbered metadata is surfaced on the
+direct single-call read path.
+
+## 3. PR state selector (open / closed / merged)
+
+`getMyPullRequestsForRepos` and `searchMyPullRequests` accept a `PullRequestStateFilter`
+(`open`|`closed`|`merged`|`all`); issue reads accept an `IssueStateFilter` (`open`|`closed`|`all`). Omitted =
+open-only (unchanged). All providers honor it (providers that can't express an arbitrary combination in one
+query filter the normalized results).
+
+| Provider         | Paginated (`getMy*ForRepos`) | Search (`searchMyPullRequests`)                                          |
+| ---------------- | ---------------------------- | ------------------------------------------------------------------------ |
+| GitHub           | first-class (SDK `states`)   | first-class (search query `is:open`/`is:closed is:unmerged`/`is:merged`) |
+| GitLab           | first-class                  | first-class (SDK `states`)                                               |
+| Bitbucket        | first-class                  | first-class (BBQL state clause + authored `states`)                      |
+| Bitbucket Server | first-class                  | first-class (SDK `states`)                                               |
+| Azure DevOps     | first-class                  | first-class (SDK `states`)                                               |
+| Jira (issues)    | first-class                  | n/a (Jira has no PRs)                                                    |
+
+## 4. Assignee / reviewer filters
+
+- **`includeAllAssignees` (issues):** `getMyIssuesForRepos` option; when `true` it drops the current-user
+  assignee constraint (returns all-assignee issues). First-class for all issue providers (it is an omission).
+- **Reviewer inclusion (PRs):** the `ReviewRequested` filter routes to the field each provider reads.
+
+| Provider         | Reviewer filter                                      | Keyed by   |
+| ---------------- | ---------------------------------------------------- | ---------- |
+| GitHub           | `reviewRequestedLogin`                               | login      |
+| GitLab           | `reviewRequestedLogin` (multi-assignee also honored) | login      |
+| Bitbucket        | `reviewerId`                                         | account id |
+| Bitbucket Server | `reviewerLogin`                                      | login      |
+| Azure DevOps     | `reviewerId`                                         | account id |
+
+**Caveat:** the reviewer key differs (login vs account id); `getMyPullRequestsForRepos` picks the right one
+per provider from the resolved current user, so callers don't special-case it.
+
+## 5. Clone URLs + fork / cross-repository
+
+`PullRequestRef` carries optional `cloneHttps` / `cloneSsh` / `isFork`; `PullRequest.refs.isCrossRepository`
+is always present.
+
+| Provider         | Clone URLs                               | `isCrossRepository` | `isFork`                   |
+| ---------------- | ---------------------------------------- | ------------------- | -------------------------- |
+| GitHub           | first-class                              | first-class         | best-effort                |
+| GitLab           | first-class                              | first-class         | `undefined`                |
+| Bitbucket        | first-class                              | first-class         | `undefined`                |
+| Bitbucket Server | first-class                              | first-class         | `undefined`                |
+| Azure DevOps     | first-class **with `includeRemoteInfo`** | first-class         | best-effort (`forkSource`) |
+
+**Caveats:** Azure clone URLs require an opt-in extra lookup; `getMyPullRequestsForRepos` requests
+`includeRemoteInfo` for Azure automatically. Where clone URLs are unavailable the fields are `undefined`;
+reconstruct from the repository `webUrl`. Prefer `isCrossRepository` (always present) over `isFork`
+(best-effort, provider-dependent).
+
+## 6. Org / project scoping
+
+`ProviderScope { org?, project?, resourceId?, repos? }` is a single normalized scope. `resolveProviderScope`
+dispatches on the provider's `PagingMode` to the provider-appropriate inputs (project inputs for
+Azure-issues/Jira; repo inputs for the rest). The underlying `ProviderReposInput` / `PagingMode` are
+unchanged.
+
+**Caveat:** Azure DevOps is scoped within a single organization; multi-org scoping remains unsupported (the
+existing single-org guard stands).