@gitkraken/core-gitlens 0.4.0 → 0.4.100

package/dist/plus/integrations/reads/pullRequests.d.ts

@@ -0,0 +1,32 @@
+import type { PullRequestShape, PullRequestStateFilter } from '../../../git/models/pullRequest.js';
+import type { IntegrationIds } from '../constants.js';
+import { type ProviderReposInput, type PullRequestFilter } from '../providers/models.js';
+import type { ProviderPagedResult } from '../results.js';
+import type { ProviderReadContext } from './context.js';
+export declare function listPullRequestsPage(ctx: ProviderReadContext, options: {
+    providerId: IntegrationIds;
+    repos?: ProviderReposInput;
+    states?: PullRequestStateFilter[];
+    /**
+     * PR relationship filters (e.g. `[Author, Assignee, ReviewRequested]`). On repo-scoped reads members
+     * combine as provider query constraints (normally an intersection); on account-wide reads they form an
+     * exact OR union. The whole set is validated against the selected path's capability.
+     */
+    filters?: PullRequestFilter[];
+    /**
+     * Account-wide only: include review-requested PRs when the provider's native "my PRs" query omits them.
+     * This extends the provider-native result; it is not a narrowing filter.
+     */
+    includeReviewRequested?: boolean;
+    page?: number;
+    cursor?: string;
+    itemsPerPage?: number;
+    forceSync?: boolean;
+    connectionId?: string;
+    /**
+     * Explicit self-managed host domain when no configured connection supplies one. The value must come
+     * from the trusted authentication configuration, not repository or remote data.
+     */
+    domain?: string;
+}): Promise<ProviderPagedResult<PullRequestShape>>;
+//# sourceMappingURL=pullRequests.d.ts.map

package/dist/plus/integrations/reads/pullRequests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pullRequests.d.ts","sourceRoot":"","sources":["../../../../src/plus/integrations/reads/pullRequests.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAEnG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAKN,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAMzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAmBxD,wBAAsB,oBAAoB,CACzC,GAAG,EAAE,mBAAmB,EACxB,OAAO,EAAE;IACR,UAAU,EAAE,cAAc,CAAC;IAC3B,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,MAAM,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC9B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC,CAyMhD"}

package/dist/plus/integrations/reads/pullRequests.js

@@ -0,0 +1,151 @@
+import { mergeAssessmentInto } from '../collectionMetadata.js';
+import { fromProviderPullRequest, PagingMode, providersMetadata, } from '../providers/models.js';
+import { isGitHostIntegration, isIssuesHostIntegrationId, warnOnMissingSessionForDomain, } from '../utils/integration.utils.js';
+import { getCurrentAccountId, runCaptured } from './drains.js';
+import { resolveAccountWidePullRequestFilters, resolvePullRequestFilters } from './filters.js';
+import { drainToRequestedPage, isPageNumberAdvanceable, pageToCursor, refusedPage, resolveContinuation, resolveCurrentPage, toProviderPageInfo, } from './paging.js';
+import { gitHostOnlySurfaceWarning, truncationWarning, unsupportedAccountWidePullRequestFiltersWarning, unsupportedFiltersWarning, } from './warnings.js';
+export async function listPullRequestsPage(ctx, options) {
+    const page = Math.max(1, options.page ?? 1);
+    if (isIssuesHostIntegrationId(options.providerId)) {
+        return refusedPage(page, [gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'pull request reads')], true);
+    }
+    const integration = await ctx.getIntegrationForRead(options.providerId, options.connectionId, options.domain);
+    if (integration == null) {
+        // A supplied connection or domain that no longer resolves is a broken target, not an empty account —
+        // surface a no-connection warning + fetchFailed rather than a silent empty page.
+        const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId, options.domain);
+        return refusedPage(page, early.warnings, early.fetchFailed);
+    }
+    if (!isGitHostIntegration(integration)) {
+        return refusedPage(page, [gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'pull request reads')], true);
+    }
+    await ctx.forceRefreshIfRequested(integration, options.forceSync, options.connectionId);
+    const domain = ctx.domainForRead(integration, options.providerId, options.connectionId, options.domain);
+    // With no repos this is an account-wide "my PRs" read; the repo-scoped core rejects an empty `repos`
+    // input, so route to the account-wide, inherently user-scoped core instead (see drainPullRequests).
+    // That provider-defined path takes no `pageSize`. A page-only request is handled by walking any opaque
+    // continuations it supplies below. Do NOT synthesize a page-number cursor for it: cursor-based queries
+    // (e.g. GitHub `involves:`) ignore a page number and would return their first page.
+    const accountWide = (options.repos?.length ?? 0) === 0;
+    const cursor = accountWide ? options.cursor : (options.cursor ?? pageToCursor(page));
+    const resolvedFilters = accountWide
+        ? resolveAccountWidePullRequestFilters(options.providerId, options.filters)
+        : resolvePullRequestFilters(options.providerId, options.filters);
+    if (resolvedFilters.unsupported) {
+        return refusedPage(page, [
+            accountWide
+                ? unsupportedAccountWidePullRequestFiltersWarning(options.providerId, domain, options.connectionId, options.filters ?? [])
+                : unsupportedFiltersWarning(options.providerId, domain, options.connectionId),
+        ], true);
+    }
+    const includeReviewRequested = accountWide ? (options.includeReviewRequested ?? false) : false;
+    const { value, warning } = await runCaptured(options.providerId, domain, options.connectionId, () => accountWide
+        ? integration.getMyPullRequestsForUserResult({
+            state: options.states,
+            cursor: cursor,
+            includeReviewRequested: includeReviewRequested,
+            filters: resolvedFilters.filters,
+            summary: true,
+        }, options.connectionId)
+        : integration.getMyPullRequestsForReposResult(options.repos ?? [], 
+        // Forward `page`/`pageSize` alongside the cursor so PagingMode.Repo hosts (GitLab, Bitbucket,
+        // Azure), whose per-repo cursor path ignores a synthesized page-number cursor, still honor the
+        // requested page and page size instead of always returning page 1. `filters` scopes the read to
+        // the current user (the core resolves the account for these), so it returns the user's PRs.
+        {
+            state: options.states,
+            filters: resolvedFilters.filters,
+            cursor: cursor,
+            page: options.page,
+            pageSize: options.itemsPerPage,
+        }, options.connectionId), {
+        warnOnMissingSession: warnOnMissingSessionForDomain(options.providerId, options.domain),
+    });
+    let items = value?.values ?? [];
+    // Cursor-only account-wide reads start at page 1; a page-only request is advanced through opaque
+    // continuations below. Repo-scoped reads report the requested page unless the provider reports its own.
+    let paged = toProviderPageInfo(items.length, value?.paging);
+    let allMetadata = value?.metadata;
+    // Convert the SDK collection metadata into scope-aware warnings + failure/truncation flags, appending
+    // them to any captured thrown-error warning without discarding the partial result's items.
+    const warnings = warning != null ? [warning] : [];
+    let pageFetchFailed = warning != null && value == null;
+    // Cursor-only reads ignore a synthesized page-number cursor, so a page-only request is advanced through
+    // the provider's own continuations (see drainToRequestedPage).
+    if ((accountWide || providersMetadata[options.providerId]?.pullRequestsPagingMode === PagingMode.Repos) &&
+        options.page != null &&
+        options.page > 1 &&
+        options.cursor == null &&
+        paged.page.currentPage === 1) {
+        const drained = await drainToRequestedPage({ items: items, paged: paged, metadata: allMetadata, fetchFailed: pageFetchFailed }, {
+            requestedPage: options.page,
+            itemsPerPage: options.itemsPerPage,
+            warnings: warnings,
+            readPage: (cursor) => runCaptured(options.providerId, domain, options.connectionId, () => accountWide
+                ? integration.getMyPullRequestsForUserResult({
+                    state: options.states,
+                    cursor: cursor,
+                    includeReviewRequested: includeReviewRequested,
+                    filters: resolvedFilters.filters,
+                    summary: true,
+                }, options.connectionId)
+                : integration.getMyPullRequestsForReposResult(options.repos ?? [], {
+                    state: options.states,
+                    filters: resolvedFilters.filters,
+                    cursor: cursor,
+                    pageSize: options.itemsPerPage,
+                }, options.connectionId), {
+                warnOnMissingSession: warnOnMissingSessionForDomain(options.providerId, options.domain),
+            }),
+        });
+        items = drained.items;
+        paged = drained.paged;
+        allMetadata = drained.metadata;
+        pageFetchFailed = drained.fetchFailed;
+    }
+    const assessment = mergeAssessmentInto(warnings, options.providerId, domain, options.connectionId, allMetadata);
+    // Never advertise `hasMore` without a continuation the caller can act on. The account-wide read has no
+    // page to synthesize, and neither does a host that doesn't honor a page number — see
+    // {@link IntegrationService.isPageNumberAdvanceable} for which do and why absence of a declared mode
+    // does NOT count as one.
+    const pageAdvanceable = !accountWide && isPageNumberAdvanceable(providersMetadata[options.providerId]?.pullRequestsPagingMode);
+    const continuation = resolveContinuation(paged, pageAdvanceable ? paged.page.currentPage + 1 : undefined);
+    // A single-page provider read that couldn't confirm completeness sets `paging.truncated`; surface it
+    // as a terminal `page.truncated` (not `hasMore`, which has no cursor to advance) so the caller knows
+    // the page may be incomplete. Metadata incompleteness is an independent source of the same signal.
+    const truncated = continuation.truncated || assessment.truncated;
+    if (truncated && warnings.length === 0) {
+        warnings.push(truncationWarning(options.providerId, domain, options.connectionId, 'Pull request'));
+    }
+    const currentAccountId = items.some(pr => pr.author != null)
+        ? await getCurrentAccountId(integration, options.connectionId)
+        : undefined;
+    return {
+        // Normalize the raw provider-apis PRs to the GitLens-owned shape at the surface boundary.
+        items: items.map(pr => fromProviderPullRequest(pr, integration, { currentAccountId: currentAccountId })),
+        warnings: warnings,
+        // The account-wide read can't take a page size, so don't echo the requested `itemsPerPage` as if it
+        // had been applied — report what came back.
+        page: {
+            ...paged.page,
+            // Positional, per ProviderPageInfo.currentPage: the drain (above) already advanced `paged.page`,
+            // and a caller-threaded cursor advanced the provider, so neither leaves a cursor-only read stuck
+            // reporting page 1.
+            currentPage: resolveCurrentPage({
+                providerPage: paged.page.currentPage,
+                requestedPage: page,
+                suppliedCursor: options.cursor,
+                pageAdvanceable: pageAdvanceable,
+            }),
+            itemsPerPage: accountWide ? items.length : paged.page.itemsPerPage,
+            truncated: truncated || undefined,
+        },
+        hasMore: continuation.hasMore,
+        cursor: continuation.cursor,
+        // A metadata failure means items are incomplete even when the read didn't throw; a thrown error with
+        // no recovered value is the pre-existing failure case.
+        fetchFailed: assessment.fetchFailed || pageFetchFailed || undefined,
+    };
+}
+//# sourceMappingURL=pullRequests.js.map

package/dist/plus/integrations/reads/pullRequests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pullRequests.js","sourceRoot":"","sources":["../../../../src/plus/integrations/reads/pullRequests.ts"],"names":[],"mappings":"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"}

package/dist/plus/integrations/reads/warnings.d.ts

@@ -0,0 +1,47 @@
+import type { IntegrationIds } from '../constants.js';
+import type { IssueFilter, PullRequestFilter } from '../providerFilters.js';
+import type { ProviderWarning } from '../results.js';
+/**
+ * The warnings the provider facade raises on its OWN terms, as opposed to the ones derived from a caught
+ * provider error ({@link toProviderWarning}) or from SDK collection metadata (`collectionMetadata.ts`).
+ *
+ * These are pure message builders, kept together and out of the service so a read method reads as the decision
+ * it makes ("this surface doesn't apply, refuse it") rather than as the wording of the refusal, and so the same
+ * refusal can't be phrased two ways in two reads.
+ */
+/**
+ * The single builder for a provider-neutral, non-auth warning: an unsupported capability, a
+ * contradictory/inexpressible request, or a read that couldn't confirm completeness. Every `kind: 'other'`
+ * warning the facade emits goes through here (directly, or via one of the named builders below that pin a
+ * recurring message), so the discriminant is assigned in exactly one place.
+ *
+ * The kinds that carry a programmatic remedy — `auth`, `rate-limit`, `not-found`, `no-connection` — are derived
+ * from the caught error's type instead and never come from here; see `ProviderWarningKind` and
+ * {@link noConnectionWarning}.
+ */
+export declare function otherWarning(id: IntegrationIds, domain: string | undefined, connectionId: string | undefined, message: string): ProviderWarning;
+/**
+ * Builds a `no-connection` warning for a per-connection read that resolved neither a session nor an error: the
+ * requested `connectionId` no longer resolves (deleted, or its authentication is invalid). Consumers use this
+ * to tell a truly empty account apart from a broken connection.
+ */
+export declare function noConnectionWarning(id: IntegrationIds, domain: string | undefined, connectionId?: string): ProviderWarning;
+/** Warning for an issue-tracker provider asked for a surface only a git host serves (repos, PRs, sweeps). */
+export declare function gitHostOnlySurfaceWarning(id: IntegrationIds, domain: string | undefined, connectionId: string | undefined, surface: string): ProviderWarning;
+/** Warning for a git host asked for a surface only an issue tracker serves (resource → project issue reads). */
+export declare function issueTrackerOnlySurfaceWarning(id: IntegrationIds, connectionId: string | undefined, surface: string): ProviderWarning;
+/**
+ * Builds a warning for a drain that stopped short of completeness (hit a page backstop, or a single-page read
+ * that couldn't confirm it drained everything). `truncated`/`allPages` already carry this on the result, but
+ * consumers that only inspect `warnings` would otherwise see no signal the read is partial.
+ */
+export declare function truncationWarning(id: IntegrationIds, domain: string | undefined, connectionId: string | undefined, readKind: 'Pull request' | 'Issue' | 'Repository'): ProviderWarning;
+/** Warning for an account-wide issue read whose requested filters the provider can't express server-side. */
+export declare function unsupportedAccountWideIssueFiltersWarning(id: IntegrationIds, domain: string | undefined, connectionId: string | undefined, filters: IssueFilter[]): ProviderWarning;
+/** Warning for an account-wide PR read whose requested relationship union cannot be expressed exactly. */
+export declare function unsupportedAccountWidePullRequestFiltersWarning(id: IntegrationIds, domain: string | undefined, connectionId: string | undefined, filters: PullRequestFilter[]): ProviderWarning;
+/** Warning for a repo-scoped PR read whose requested filters the provider supports none of. */
+export declare function unsupportedFiltersWarning(id: IntegrationIds, domain: string | undefined, connectionId: string | undefined): ProviderWarning;
+/** Warning for a git host that doesn't expose issues on this surface (e.g. Bitbucket, deprecated in favor of Jira). */
+export declare function issuesUnsupportedWarning(id: IntegrationIds, domain: string | undefined, connectionId: string | undefined): ProviderWarning;
+//# sourceMappingURL=warnings.d.ts.map

package/dist/plus/integrations/reads/warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../../../../src/plus/integrations/reads/warnings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC3B,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,OAAO,EAAE,MAAM,GACb,eAAe,CASjB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,CAAC,EAAE,MAAM,GACnB,eAAe,CAYjB;AAED,6GAA6G;AAC7G,wBAAgB,yBAAyB,CACxC,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,OAAO,EAAE,MAAM,GACb,eAAe,CAOjB;AAED,gHAAgH;AAChH,wBAAgB,8BAA8B,CAC7C,EAAE,EAAE,cAAc,EAClB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,OAAO,EAAE,MAAM,GACb,eAAe,CAOjB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAChC,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,QAAQ,EAAE,cAAc,GAAG,OAAO,GAAG,YAAY,GAC/C,eAAe,CAOjB;AAED,6GAA6G;AAC7G,wBAAgB,yCAAyC,CACxD,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,OAAO,EAAE,WAAW,EAAE,GACpB,eAAe,CAQjB;AAED,0GAA0G;AAC1G,wBAAgB,+CAA+C,CAC9D,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,OAAO,EAAE,iBAAiB,EAAE,GAC1B,eAAe,CAQjB;AAED,+FAA+F;AAC/F,wBAAgB,yBAAyB,CACxC,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC9B,eAAe,CAOjB;AAED,uHAAuH;AACvH,wBAAgB,wBAAwB,CACvC,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC9B,eAAe,CAOjB"}

package/dist/plus/integrations/reads/warnings.js

@@ -0,0 +1,81 @@
+import { providersMetadata } from '../providers/models.js';
+/**
+ * The warnings the provider facade raises on its OWN terms, as opposed to the ones derived from a caught
+ * provider error ({@link toProviderWarning}) or from SDK collection metadata (`collectionMetadata.ts`).
+ *
+ * These are pure message builders, kept together and out of the service so a read method reads as the decision
+ * it makes ("this surface doesn't apply, refuse it") rather than as the wording of the refusal, and so the same
+ * refusal can't be phrased two ways in two reads.
+ */
+/**
+ * The single builder for a provider-neutral, non-auth warning: an unsupported capability, a
+ * contradictory/inexpressible request, or a read that couldn't confirm completeness. Every `kind: 'other'`
+ * warning the facade emits goes through here (directly, or via one of the named builders below that pin a
+ * recurring message), so the discriminant is assigned in exactly one place.
+ *
+ * The kinds that carry a programmatic remedy — `auth`, `rate-limit`, `not-found`, `no-connection` — are derived
+ * from the caught error's type instead and never come from here; see `ProviderWarningKind` and
+ * {@link noConnectionWarning}.
+ */
+export function otherWarning(id, domain, connectionId, message) {
+    return {
+        providerId: id,
+        domain: domain,
+        connectionId: connectionId,
+        message: message,
+        kind: 'other',
+        isAuth: false,
+    };
+}
+/**
+ * Builds a `no-connection` warning for a per-connection read that resolved neither a session nor an error: the
+ * requested `connectionId` no longer resolves (deleted, or its authentication is invalid). Consumers use this
+ * to tell a truly empty account apart from a broken connection.
+ */
+export function noConnectionWarning(id, domain, connectionId) {
+    return {
+        providerId: id,
+        domain: domain,
+        connectionId: connectionId,
+        message: connectionId != null
+            ? `Connection '${connectionId}' for '${id}' could not be resolved (deleted or invalid authentication).`
+            : `No active connection for '${id}' could be resolved.`,
+        kind: 'no-connection',
+        isAuth: false,
+    };
+}
+/** Warning for an issue-tracker provider asked for a surface only a git host serves (repos, PRs, sweeps). */
+export function gitHostOnlySurfaceWarning(id, domain, connectionId, surface) {
+    return otherWarning(id, domain, connectionId, `${surface} is not supported by '${id}'; use a git-host integration instead.`);
+}
+/** Warning for a git host asked for a surface only an issue tracker serves (resource → project issue reads). */
+export function issueTrackerOnlySurfaceWarning(id, connectionId, surface) {
+    return otherWarning(id, undefined, connectionId, `${surface} is not supported by '${id}'; use an issue-tracker integration instead.`);
+}
+/**
+ * Builds a warning for a drain that stopped short of completeness (hit a page backstop, or a single-page read
+ * that couldn't confirm it drained everything). `truncated`/`allPages` already carry this on the result, but
+ * consumers that only inspect `warnings` would otherwise see no signal the read is partial.
+ */
+export function truncationWarning(id, domain, connectionId, readKind) {
+    return otherWarning(id, domain, connectionId, `${readKind} read for '${id}' was truncated (a page backstop was reached); results may be incomplete.`);
+}
+/** Warning for an account-wide issue read whose requested filters the provider can't express server-side. */
+export function unsupportedAccountWideIssueFiltersWarning(id, domain, connectionId, filters) {
+    const supported = providersMetadata[id]?.supportedAccountWideIssueFilters ?? [];
+    return otherWarning(id, domain, connectionId, `The requested account-wide issue filters (${filters.join(', ')}) are not supported by '${id}'${supported.length ? ` (supported: ${supported.join(', ')})` : ''}; skipped to avoid returning a wider result than requested.`);
+}
+/** Warning for an account-wide PR read whose requested relationship union cannot be expressed exactly. */
+export function unsupportedAccountWidePullRequestFiltersWarning(id, domain, connectionId, filters) {
+    const supported = providersMetadata[id]?.supportedAccountWidePullRequestFilters ?? [];
+    return otherWarning(id, domain, connectionId, `The requested account-wide pull request filters (${filters.join(', ')}) are not supported by '${id}'${supported.length ? ` (supported: ${supported.join(', ')})` : ''}; skipped to avoid returning a wider result than requested.`);
+}
+/** Warning for a repo-scoped PR read whose requested filters the provider supports none of. */
+export function unsupportedFiltersWarning(id, domain, connectionId) {
+    return otherWarning(id, domain, connectionId, `The requested pull request filters are not supported by '${id}'; skipped to avoid returning unfiltered results.`);
+}
+/** Warning for a git host that doesn't expose issues on this surface (e.g. Bitbucket, deprecated in favor of Jira). */
+export function issuesUnsupportedWarning(id, domain, connectionId) {
+    return otherWarning(id, domain, connectionId, `Issues are not supported by '${id}'; use a dedicated issue integration (e.g. Jira) instead.`);
+}
+//# sourceMappingURL=warnings.js.map

package/dist/plus/integrations/reads/warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.js","sourceRoot":"","sources":["../../../../src/plus/integrations/reads/warnings.ts"],"names":[],"mappings":"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"}

package/dist/plus/integrations/results.d.ts

@@ -0,0 +1,189 @@
+import type { IntegrationIds } from './constants.js';
+export interface ConnectionStateChangeEvent {
+    key: string;
+    reason: 'connected' | 'disconnected';
+}
+/**
+ * A per-provider, per-connection warning surfaced alongside (partial) read results. Consumers use
+ * these to drive auth recovery, retry, or truncation messaging without the read itself throwing.
+ *
+ * `kind` is the programmatic discriminant (a rate-limit is retryable, a 404 is not, an auth failure
+ * needs re-connection); `isAuth` is retained as a convenience mirror of `kind === 'auth'`.
+ */
+export type ProviderWarningKind = 'auth' | 'rate-limit' | 'not-found' | 'no-connection' | 'other';
+export interface ProviderWarning {
+    providerId: IntegrationIds;
+    /** Disambiguates connections on self-managed hosts (where one provider id spans multiple domains). */
+    domain?: string;
+    /** The specific token/connection the read was pinned to, when a `connectionId` was supplied. */
+    connectionId?: string;
+    message: string;
+    kind: ProviderWarningKind;
+    /** Convenience mirror of `kind === 'auth'`. */
+    isAuth: boolean;
+}
+export interface ProviderPageInfo {
+    /**
+     * The 1-based POSITION of the returned page. One convention across every paged read, page-number and
+     * cursor paging alike, so a `getNextPageParam`-style consumer can key off it uniformly:
+     * - the page number the provider itself reported, when it reports one (authoritative);
+     * - else the position the caller addressed: the page encoded in a threaded page cursor, or the `page`
+     *   supplied alongside an opaque cursor (1 when the caller supplied no `page`);
+     * - else, for a read that can be advanced by page number, the requested `page` — the provider either
+     *   honored it or the internal drain reached it (see the paging contract on `IntegrationManager`);
+     * - else 1: a cursor-only read with no cursor threaded back ignores a requested page number and answers
+     *   with its first page, so echoing the request would mislabel page 1 as page N.
+     *
+     * A page past the provider's terminal cursor still reports the requested `page` with empty `items` — an
+     * empty page N, never page N-1 relabeled.
+     *
+     * Continue a cursor-paged read from `cursor`, NOT from `currentPage + 1`: a cursor-only host can't be
+     * addressed by number, so this is a position label and not always a resumable request parameter.
+     */
+    currentPage: number;
+    /**
+     * The page size IN EFFECT, which is not always the one requested — it is whichever of these the read can
+     * actually vouch for:
+     * - the size the provider reported for the page it served (numbered-page hosts), else
+     * - the `itemsPerPage` that was applied to the request (repo-scoped reads, which forward it), else
+     * - `items.length`, for a read that takes no page size at all: the account-wide PR/issue reads, `listRepos`
+     *   (cursor-only), and `listIssueTrackerIssuesPage`, whose `itemsPerPage` counts PROJECTS rather than issues.
+     *
+     * So it is a description of the page, not an echo of the request: don't derive a total from
+     * `currentPage * itemsPerPage`, and don't read `items.length < itemsPerPage` as "last page" — `hasMore` /
+     * `cursor` are the only continuation signals.
+     */
+    itemsPerPage: number;
+    /**
+     * A COMPLETENESS assertion, not a mode flag: `true` only when a sweep drained every page of every target
+     * without truncating or failing (`!truncated && !fetchFailed`). Set exclusively by `sweepPullRequests` /
+     * `sweepClosedPullRequests` and absent on every paged read, so `allPages !== true` does NOT by itself mean
+     * "this was a single page".
+     *
+     * This is the signal to gate on before caching a sweep as authoritative: unlike `truncated` it is `false`
+     * for BOTH kinds of incompleteness, so it can't be misread as a benign cap.
+     */
+    allPages?: boolean;
+    /**
+     * True when the read stopped before it could confirm it had everything. Deliberately does NOT distinguish
+     * WHY, and a consumer must not assume it means a provider ceiling — a sweep sets it from three different
+     * origins:
+     * - a provider-side ceiling or per-scope backstop propagated from below (e.g. GitHub Search's 1000-result
+     *   cap): the missing items are NOT reachable, so this really is "complete to the provider's limit";
+     * - the sweep's OWN `maxPages` cap (default 100) with a usable cursor still in hand: the missing items ARE
+     *   reachable and were simply not fetched — raise `maxPages` to get them;
+     * - the provider reporting another page but handing back no usable cursor: not reachable.
+     *
+     * Only the second is recoverable, and a sweep exposes no continuation cursor, so treating a truncated sweep
+     * as a complete set silently drops reachable data in that case. Prefer `allPages` for the cache decision.
+     */
+    truncated?: boolean;
+}
+export interface ProviderResult<T> {
+    items: T[];
+    warnings: ProviderWarning[];
+    /**
+     * True when `items` is incomplete — distinguishes a failed or truncated flat read from a genuinely empty
+     * result. Paged results additionally use `page.truncated` when a completed page could not confirm it
+     * drained everything.
+     */
+    fetchFailed?: boolean;
+}
+export interface ProviderPagedResult<T> extends ProviderResult<T> {
+    page: ProviderPageInfo;
+    hasMore: boolean;
+    /**
+     * Opaque cursor for cursor-based paging (GraphQL, per-repo/per-project cursors, etc.). For hosts that
+     * require the previous page's cursor, consumers should pass this value back to the next `cursor` option.
+     * A retry-only cursor may remain when `hasMore` is false: `hasMore` means automatic forward progress,
+     * while explicitly reusing such a cursor retries failed work without creating an infinite paging loop.
+     */
+    cursor?: string;
+}
+export interface ProviderSweepResult<T> extends ProviderResult<T> {
+    page: ProviderPageInfo;
+    hasMore: boolean;
+    /**
+     * Providers whose top-level read failed before returning any usable page. Partial per-scope failures stay
+     * represented by `warnings` + `fetchFailed` and are intentionally excluded.
+     */
+    failedProviderIds: IntegrationIds[];
+    /**
+     * Providers whose read started successfully but could not produce an authoritative complete slice (for
+     * example, a later page failed, collection metadata reported a partial scope, or a paging backstop was hit).
+     * Kept separate from
+     * `failedProviderIds` so consumers can accept healthy sibling providers while preserving an older snapshot
+     * for a provider whose returned slice has a gap.
+     */
+    incompleteProviderIds: IntegrationIds[];
+}
+export interface ProviderBroadenResult<T> extends ProviderPagedResult<T> {
+    broadenedProviderIds: IntegrationIds[];
+    /** Providers for which no requested org produced a usable issue result. */
+    failedProviderIds: IntegrationIds[];
+    /** Providers with both a usable org result and at least one failed or truncated org slice. */
+    incompleteProviderIds: IntegrationIds[];
+    fanOutCount: number;
+}
+export type RepositoryResolutionStatus = 'resolved' | 'not-found' | 'unauthorized' | 'unsupported-provider' | 'invalid-remote-url' | 'host-mismatch' | 'undetermined';
+export interface RepositoryIdentity {
+    providerId: IntegrationIds;
+    domain: string;
+    /** The provider's canonical owner/namespace (follows renames), falling back to the parsed remote when omitted. */
+    owner: string;
+    /** The provider's canonical repo name (follows renames), falling back to the parsed remote when omitted. */
+    name: string;
+    project?: string;
+    /** The original input remote URL, so the caller can key the resolution back to the remote it asked about. */
+    remoteUrl: string;
+    /**
+     * True when the provider's canonical owner/name differ from what the input remote URL carried — i.e. the
+     * repo was renamed/moved host-side and the local remote is stale. Case-insensitive, mirroring gkcli's
+     * `EqualFold` compare so hosts that echo the input casing (e.g. Bitbucket Server/Azure) aren't flagged.
+     */
+    renamed: boolean;
+}
+export interface RepositoryResolution {
+    status: RepositoryResolutionStatus;
+    identity?: RepositoryIdentity;
+    warning?: ProviderWarning;
+}
+export interface ResolveRepositoryResult {
+    resolution: RepositoryResolution;
+}
+/**
+ * Normalized org/workspace/group shape returned by the provider facade.
+ * `name` is the provider identifier to pass to follow-up reads, while `org` is an optional display label.
+ */
+export interface ProviderOrganization {
+    id: string;
+    providerId: IntegrationIds;
+    name: string;
+    org?: string;
+    url: string;
+}
+/** Normalized repository shape returned by the provider facade. */
+export interface ProviderRepositoryShape {
+    id: string;
+    namespace: string;
+    name: string;
+    /** Azure DevOps project; `undefined` for hosts without a project layer. */
+    project?: string;
+    /** Web (browser) URL, when the provider exposes it. */
+    url?: string;
+    /** HTTPS clone URL, when available. */
+    cloneUrlHttps?: string;
+    /** SSH clone URL, when available. */
+    cloneUrlSsh?: string;
+    /** Default branch name, when the provider reports it. */
+    defaultBranch?: string;
+}
+/**
+ * Classifies a caught provider exception into a neutral {@link ProviderWarning}. Ordering matters:
+ * `instanceof` is checked most-specific-first so a rate-limit isn't mislabeled as a generic error and
+ * a 404 isn't mislabeled as auth.
+ */
+export declare function toProviderWarning(providerId: IntegrationIds, domain: string | undefined, connectionId: string | undefined, ex: unknown): ProviderWarning;
+/** Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message) is absent. */
+export declare function appendDedupedWarning(into: ProviderWarning[], warning: ProviderWarning): void;
+//# sourceMappingURL=results.d.ts.map

package/dist/plus/integrations/results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/plus/integrations/results.ts"],"names":[],"mappings":"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"}

package/dist/plus/integrations/results.js

@@ -0,0 +1,62 @@
+import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
+const maxProviderWarningMessageLength = 500;
+function providerWarningMessage(ex) {
+    const raw = (ex instanceof Error ? ex.message : String(ex)).trim();
+    const carrier = ex;
+    const status = typeof carrier?.status === 'number'
+        ? carrier.status
+        : typeof carrier?.response?.status === 'number'
+            ? carrier.response.status
+            : undefined;
+    // Gateways commonly answer API requests with a complete HTML error page. That payload is neither actionable
+    // nor suitable for a warning DTO consumed by UIs and logs; preserve the status without leaking the document.
+    if (/<(?:!doctype\s+html|html|head|body)\b/i.test(raw)) {
+        return status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';
+    }
+    if (!raw) {
+        return status != null ? `Provider request failed with status ${status}.` : 'Provider request failed.';
+    }
+    return raw.length > maxProviderWarningMessageLength
+        ? `${raw.slice(0, maxProviderWarningMessageLength - 3)}...`
+        : raw;
+}
+/**
+ * Classifies a caught provider exception into a neutral {@link ProviderWarning}. Ordering matters:
+ * `instanceof` is checked most-specific-first so a rate-limit isn't mislabeled as a generic error and
+ * a 404 isn't mislabeled as auth.
+ */
+export function toProviderWarning(providerId, domain, connectionId, ex) {
+    let kind;
+    if (ex instanceof AuthenticationError) {
+        kind = 'auth';
+    }
+    else if (ex instanceof RequestRateLimitError) {
+        kind = 'rate-limit';
+    }
+    else if (ex instanceof RequestNotFoundError) {
+        kind = 'not-found';
+    }
+    else {
+        kind = 'other';
+    }
+    return {
+        providerId: providerId,
+        domain: domain,
+        connectionId: connectionId,
+        message: providerWarningMessage(ex),
+        kind: kind,
+        isAuth: kind === 'auth',
+    };
+}
+/** A stable key for deduplicating warnings accumulated across drained pages / fan-out scopes. */
+function providerWarningKey(warning) {
+    return [warning.providerId, warning.connectionId ?? '', warning.domain ?? '', warning.kind, warning.message].join(' ');
+}
+/** Appends `warning` to `into` only when an equal warning (by provider/connection/domain/kind/message) is absent. */
+export function appendDedupedWarning(into, warning) {
+    const key = providerWarningKey(warning);
+    if (into.some(existing => providerWarningKey(existing) === key))
+        return;
+    into.push(warning);
+}
+//# sourceMappingURL=results.js.map

package/dist/plus/integrations/results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../../../src/plus/integrations/results.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AA8K1G,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAE5C,SAAS,sBAAsB,CAAC,EAAW;IAC1C,MAAM,GAAG,GAAG,CAAC,EAAE,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,MAAM,OAAO,GAAG,EAA8E,CAAC;IAC/F,MAAM,MAAM,GACX,OAAO,OAAO,EAAE,MAAM,KAAK,QAAQ;QAClC,CAAC,CAAC,OAAO,CAAC,MAAM;QAChB,CAAC,CAAC,OAAO,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,QAAQ;YAC9C,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM;YACzB,CAAC,CAAC,SAAS,CAAC;IAEf,4GAA4G;IAC5G,6GAA6G;IAC7G,IAAI,wCAAwC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,uCAAuC,MAAM,GAAG,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACvG,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,uCAAuC,MAAM,GAAG,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACvG,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,GAAG,+BAA+B;QAClD,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,+BAA+B,GAAG,CAAC,CAAC,KAAK;QAC3D,CAAC,CAAC,GAAG,CAAC;AACR,CAAC;AA+BD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAChC,UAA0B,EAC1B,MAA0B,EAC1B,YAAgC,EAChC,EAAW;IAEX,IAAI,IAA6B,CAAC;IAClC,IAAI,EAAE,YAAY,mBAAmB,EAAE,CAAC;QACvC,IAAI,GAAG,MAAM,CAAC;IACf,CAAC;SAAM,IAAI,EAAE,YAAY,qBAAqB,EAAE,CAAC;QAChD,IAAI,GAAG,YAAY,CAAC;IACrB,CAAC;SAAM,IAAI,EAAE,YAAY,oBAAoB,EAAE,CAAC;QAC/C,IAAI,GAAG,WAAW,CAAC;IACpB,CAAC;SAAM,CAAC;QACP,IAAI,GAAG,OAAO,CAAC;IAChB,CAAC;IAED,OAAO;QACN,UAAU,EAAE,UAAU;QACtB,MAAM,EAAE,MAAM;QACd,YAAY,EAAE,YAAY;QAC1B,OAAO,EAAE,sBAAsB,CAAC,EAAE,CAAC;QACnC,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,IAAI,KAAK,MAAM;KACvB,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,SAAS,kBAAkB,CAAC,OAAwB;IACnD,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAChH,GAAG,CACH,CAAC;AACH,CAAC;AAED,qHAAqH;AACrH,MAAM,UAAU,oBAAoB,CAAC,IAAuB,EAAE,OAAwB;IACrF,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,kBAAkB,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC;QAAE,OAAO;IAExE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACpB,CAAC"}

package/dist/plus/integrations/utils/domain.utils.d.ts

@@ -0,0 +1,5 @@
+/** Extracts the host from a domain expressed as either a URL or a bare host. */
+export declare function hostFromDomain(domain: string | undefined): string | undefined;
+/** Whether two URL-or-host domain values identify the same normalized host and port. */
+export declare function areDomainsOnSameHost(first: string | undefined, second: string | undefined): boolean;
+//# sourceMappingURL=domain.utils.d.ts.map

package/dist/plus/integrations/utils/domain.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.utils.d.ts","sourceRoot":"","sources":["../../../../src/plus/integrations/utils/domain.utils.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAiB7E;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAInG"}