@gitkraken/core-gitlens 0.5.103 → 0.5.105

package/src/plus/git-github/api/issueSearchQuery.ts

@@ -0,0 +1,165 @@
+import type { IssueSearchCriteria, IssueSearchRelationship } from '../../../git/models/issue.js';
+
+/**
+ * Translation of the provider-neutral issue-search criteria into GitHub search qualifiers, and the sanitizing
+ * that keeps user input from becoming one.
+ *
+ * A module of its own because it is pure string building with no client, no token and no network — the part of the
+ * search that is worth reading, testing and reasoning about on its own, and the part where a mistake is a
+ * SECURITY mistake rather than a failed request: an unsanitized value that escapes its qualifier re-scopes
+ * someone's search. Keeping it out of the 4000-line API client is what makes that reviewable.
+ */
+
+/**
+ * Neutralizes everything in a user-supplied value that could break out of the qualifier it lands in: the double
+ * quote that would close its own `"…"`, and the control characters that cannot appear in a GitHub search query
+ * and exist here only as a smuggling vector.
+ *
+ * Not a general escape — GitHub search has no escape syntax — so the only safe transformation is removal. But a
+ * control character is REPLACED WITH A SPACE rather than deleted, because deleting it FUSES the words it separated:
+ * a pasted or multi-line `graph\nperformance` became the single token `graphperformance`, which matches nothing —
+ * turning a search that had results into a silent zero (measured: 2 results vs 0). Quotes are still deleted
+ * outright; they separate nothing, so a space there would only pad the value.
+ *
+ * Runs of whitespace are collapsed afterwards so the emitted qualifier stays canonical — a doubled space inside
+ * `label:"a  b"` would not match the label `a b`.
+ */
+export function sanitizeGitHubQualifierValue(value: string): string {
+	return (
+		value
+			.replace(/"/g, '')
+			// eslint-disable-next-line no-control-regex
+			.replace(/[\u0000-\u001f\u007f]/g, ' ')
+			.replace(/\s+/g, ' ')
+			.trim()
+	);
+}
+
+/**
+ * Sanitizes free text, which is a different problem from a qualifier value: bare words are the POINT here, so it
+ * can't just be quoted. What must not survive is anything that would read as a qualifier — GitHub parses any
+ * whitespace-delimited `key:value` token as one, so a user typing `foo org:someone-else` would otherwise re-scope
+ * the search to another org.
+ *
+ * Tokens containing `:` are dropped whole rather than having the colon removed: the remainder would silently
+ * change what the user searched for, and a dropped token at least matches nothing extra. The structured criteria
+ * are the qualifier channel.
+ */
+export function sanitizeGitHubSearchText(text: string): string {
+	return sanitizeGitHubQualifierValue(text)
+		.split(/\s+/)
+		.filter(token => token.length > 0 && !token.includes(':'))
+		.join(' ');
+}
+
+/**
+ * How each relationship is expressed: its GitHub search qualifier (`@me` binds to the token's own user), and the
+ * GraphQL alias its search runs under.
+ *
+ * The aliases are LITERALS rather than derived from the relationship name, for two reasons: `any-assignee` is not
+ * a valid GraphQL name, and an alias is also a persisted cursor key (see {@link GitHubApi.searchIssuesByAlias}),
+ * so it must be stable across releases — spelling them out makes that immovability visible instead of an
+ * emergent property of a transform. Being a `Record` over the union, the type fails the build if a relationship
+ * is added without both, rather than silently emitting an unconstrained search.
+ */
+export const gitHubIssueSearchRelationships: Record<IssueSearchRelationship, { qualifier: string; alias: string }> = {
+	authored: { qualifier: 'author:@me', alias: 'authored' },
+	assigned: { qualifier: 'assignee:@me', alias: 'assigned' },
+	mentioned: { qualifier: 'mentions:@me', alias: 'mentioned' },
+	'any-assignee': { qualifier: 'assignee:*', alias: 'anyAssignee' },
+	unassigned: { qualifier: 'no:assignee', alias: 'unassigned' },
+};
+
+/**
+ * The scope half of an issue search query: `org:` plus one `repo:` per repository.
+ *
+ * Shared by the search and the count probe rather than written twice, because the count is only meaningful if it
+ * applies EXACTLY the qualifiers the search would — a count under different constraints is a wrong number, not a
+ * missing one. A value emptied by sanitizing is dropped rather than emitted as a bare `org:`/`repo:`, which
+ * GitHub rejects; that is the same rule {@link toGitHubIssueSearchQualifiers} applies to its own values.
+ */
+export function toGitHubIssueSearchScopeQualifiers(
+	org: string | undefined,
+	repos: readonly string[] | undefined,
+): string[] {
+	const qualifiers: string[] = [];
+
+	if (org != null) {
+		const value = sanitizeGitHubQualifierValue(org);
+		if (value.length > 0) {
+			qualifiers.push(`org:${value}`);
+		}
+	}
+
+	for (const repo of repos ?? []) {
+		const value = sanitizeGitHubQualifierValue(repo);
+		if (value.length > 0) {
+			qualifiers.push(`repo:${value}`);
+		}
+	}
+
+	return qualifiers;
+}
+
+/**
+ * Translates the provider-neutral criteria into GitHub search qualifiers, EXCLUDING the relationship (which
+ * becomes its own aliased search, since GitHub AND-s qualifiers and relationships are OR-ed) and excluding the
+ * repository/org scope (which {@link toGitHubIssueSearchScopeQualifiers} owns).
+ *
+ * `sort:updated` is always emitted: the read's contract is most-recently-updated-first, so a consumer's "show the
+ * N most recent" policy at the result ceiling is correct. Free-form values go through the sanitizers above, and
+ * one emptied by sanitizing is dropped rather than emitted as an empty qualifier.
+ */
+export function toGitHubIssueSearchQualifiers(criteria: IssueSearchCriteria | undefined): string[] {
+	const qualifiers = ['type:issue'];
+
+	switch (criteria?.state) {
+		case 'closed':
+			qualifiers.push('is:closed');
+			break;
+		// Every state — no qualifier constrains it.
+		case 'all':
+			break;
+		default:
+			qualifiers.push('is:open');
+			break;
+	}
+
+	if (criteria?.includeArchived !== true) {
+		qualifiers.push('archived:false');
+	}
+
+	// One place to keep the "a value emptied by sanitizing is DROPPED, never emitted as an empty qualifier" rule,
+	// so a criterion added later can't skip it — a bare `milestone:""` is rejected by GitHub outright.
+	const pushSanitized = (value: string | undefined, toQualifier: (sanitized: string) => string): void => {
+		if (value == null) return;
+
+		const sanitized = sanitizeGitHubQualifierValue(value);
+		if (sanitized.length > 0) {
+			qualifiers.push(toQualifier(sanitized));
+		}
+	};
+
+	for (const label of criteria?.labels ?? []) {
+		pushSanitized(label, v => `label:"${v}"`);
+	}
+	pushSanitized(criteria?.milestone, v => `milestone:"${v}"`);
+	pushSanitized(criteria?.updatedAfter, v => `updated:>=${v}`);
+	pushSanitized(criteria?.createdAfter, v => `created:>=${v}`);
+
+	if (criteria?.withoutLinkedPullRequest === true) {
+		qualifiers.push('-linked:pr');
+	}
+
+	if (criteria?.text != null) {
+		const text = sanitizeGitHubSearchText(criteria.text);
+		if (text.length > 0) {
+			qualifiers.push(text);
+		}
+	}
+
+	// Contract, not an option: see `GitHubApi.searchIssuesPage`.
+	qualifiers.push('sort:updated');
+
+	return qualifiers;
+}

package/src/plus/integrations/authentication/configuredIntegrationService.ts

@@ -40,6 +40,7 @@ export interface ConfiguredIntegrationsChangeEvent {
 
 export class ConfiguredIntegrationService implements Disposable {
 	private readonly _onDidChange = new Emitter<ConfiguredIntegrationsChangeEvent>();
+	private storeConfiguredQueue: Promise<void> = Promise.resolve();
 	get onDidChange(): Event<ConfiguredIntegrationsChangeEvent> {
 		return this._onDidChange.event;
 	}
@@ -129,7 +130,11 @@ export class ConfiguredIntegrationService implements Disposable {
 			}));
 		}
 
-		await this.ctx.storage.store('integrations:configured', configured);
+		const pending = this.storeConfiguredQueue.then(() =>
+			this.ctx.storage.store('integrations:configured', configured),
+		);
+		this.storeConfiguredQueue = pending.catch(() => {});
+		await pending;
 	}
 
 	private async addOrUpdateConfigured(descriptor: ConfiguredIntegrationDescriptor): Promise<void> {

package/src/plus/integrations/index.ts

@@ -215,6 +215,11 @@ export type {
 } from './results.js';
 // Runtime enums — re-exported as values (not `export type`) so consumers can read their members.
 export { IssueFilter, PullRequestFilter } from './providerFilters.js';
+// The filtered issue search's criteria model and the capability table that says which of it a provider honors.
+// String unions and plain interfaces, so a consumer builds criteria without importing an internal subpath.
+export type { IssueSearchCapabilities, IssueSearchCriteria, IssueSearchRelationship } from './providerFilters.js';
+// The count-only issue probe's input and result shapes.
+export type { IssueCountResult, IssueCountScope } from './reads/counts.js';
 // Cross-provider PR/issue state filters (string unions in the git models).
 export type { PullRequestStateFilter } from '../../git/models/pullRequest.js';
 export type { IssueStateFilter } from '../../git/models/issue.js';

package/src/plus/integrations/integrationService.ts

@@ -1,5 +1,5 @@
 import type { Account } from '../../git/models/author.js';
-import type { IssueShape } from '../../git/models/issue.js';
+import type { IssueSearchCriteria, IssueShape } from '../../git/models/issue.js';
 import type { PullRequest, PullRequestShape, PullRequestStateFilter } from '../../git/models/pullRequest.js';
 import type { GitRemote } from '../../git/models/remote.js';
 import type { RemoteProviderId } from '../../git/models/remoteProvider.js';
@@ -62,6 +62,7 @@ import { createApiClients } from './providers/apiClients.js';
 import type { GitHubApi } from './providers/github/github.js';
 import type {
 	IssueFilter,
+	IssueSearchCapabilities,
 	ProviderOrganization,
 	ProviderReposInput,
 	ProviderRepositoryShape,
@@ -71,12 +72,15 @@ import { providersMetadata } from './providers/models.js';
 import type { ProvidersApi } from './providers/providersApi.js';
 import { broadenIssues } from './reads/broaden.js';
 import type { RepositoryResolutionContext } from './reads/context.js';
+import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
+import { countIssues } from './reads/counts.js';
 import { getSupportedFilters } from './reads/filters.js';
 import { listOrgs, listProjects, listRepos } from './reads/hierarchy.js';
 import { listIssuesPage } from './reads/issues.js';
 import { listIssueTrackerIssuesPage } from './reads/issueTracker.js';
 import { listPullRequestsPage } from './reads/pullRequests.js';
 import { resolveRepository } from './reads/resolveRepository.js';
+import { searchIssuesPage } from './reads/searchIssues.js';
 import { sweepClosedPullRequests, sweepPullRequests } from './reads/sweeps.js';
 import { noConnectionWarning } from './reads/warnings.js';
 import type {
@@ -531,6 +535,7 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		pullRequestsAccountWide: PullRequestFilter[];
 		issues: IssueFilter[];
 		issuesAccountWide: IssueFilter[];
+		issueSearch: IssueSearchCapabilities;
 	} {
 		return getSupportedFilters(providerId);
 	}
@@ -1077,6 +1082,47 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		return listIssuesPage(this, options);
 	}
 
+	/**
+	 * Issues matching structured criteria over a repository/org scope, with no forced relationship to the current
+	 * user — see {@link IntegrationManager.searchIssuesPage} for the contract (mandatory scope, guaranteed
+	 * most-recently-updated-first ordering, and the result-ceiling omission that carries the total match count).
+	 */
+	async searchIssuesPage(options: {
+		providerId: IntegrationIds;
+		repos?: ProviderReposInput;
+		org?: string;
+		criteria?: IssueSearchCriteria;
+		page?: number;
+		cursor?: string;
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+		 * it must come from the trusted authentication configuration, not repository or remote data.
+		 */
+		domain?: string;
+	}): Promise<ProviderPagedResult<IssueShape>> {
+		return searchIssuesPage(this, options);
+	}
+
+	/**
+	 * How many issues match each scope, without fetching any — see {@link IntegrationManager.countIssues} for the
+	 * cost model, the per-scope isolation rules, and why `count: undefined` must not be rendered as zero.
+	 */
+	async countIssues(options: {
+		providerId: IntegrationIds;
+		scopes: readonly IssueCountScope[];
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+		 * it must come from the trusted authentication configuration, not repository or remote data.
+		 */
+		domain?: string;
+	}): Promise<ProviderResult<IssueCountResult>> {
+		return countIssues(this, options);
+	}
+
 	/**
 	 * Reads the user's issues from an issue-tracker provider (Jira/Linear/Trello), whose issues live under
 	 * resource → project (not repos), so they can't go through {@link listIssuesPage} (git-host, repo-scoped).
@@ -1513,9 +1559,11 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 
 		// Persist every account when the backend advertises per-connection identity (multi-account). This
 		// is a strict no-op for backends that return a single, id-less connection per provider.
-		for (const [integrationId, connections] of connectionsById) {
-			await this.reconcileCloudConnections(integrationId, connections, forceConnect);
-		}
+		await Promise.all(
+			Array.from(connectionsById, ([integrationId, connections]) =>
+				this.reconcileCloudConnections(integrationId, connections, forceConnect),
+			),
+		);
 
 		this.ctx.hooks?.connection?.onConnectedChanged?.({
 			integrationIds: [...connectedIntegrations.values()],
@@ -1566,79 +1614,91 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		const existingById = new Map(
 			this.configuredIntegrationService.getConfigured(id, { cloud: true }).map(c => [c.id, c]),
 		);
-		for (const connection of identified) {
-			// The wire `domain` is usually a full URL, though cloud providers can return a bare host.
-			// Self-managed integrations are keyed/constructed by host.
-			const host = hostFromDomain(connection.domain);
-
-			// Self-managed connections are keyed by host, so an unparseable/empty domain would store the
-			// session and descriptor under an empty host — producing ambiguous keys (`connected:<id>:`) that
-			// break later resolution and local-disconnect checks. Skip such a connection rather than corrupt
-			// state; cloud providers key off their canonical domain and are unaffected.
-			if (isGitSelfManagedHostIntegrationId(id) && !host) {
-				scope?.warn(`Skipping connection '${connection.id}' for ${id}: unresolved host from domain`);
-				continue;
-			}
+		const preparedConnections = await Promise.all(
+			identified.map(async connection => {
+				// The wire `domain` is usually a full URL, though cloud providers can return a bare host.
+				// Self-managed integrations are keyed/constructed by host.
+				const host = hostFromDomain(connection.domain);
+
+				// Self-managed connections are keyed by host, so an unparseable/empty domain would store the
+				// session and descriptor under an empty host — producing ambiguous keys (`connected:<id>:`) that
+				// break later resolution and local-disconnect checks. Skip such a connection rather than corrupt
+				// state; cloud providers key off their canonical domain and are unaffected.
+				if (isGitSelfManagedHostIntegrationId(id) && !host) {
+					scope?.warn(`Skipping connection '${connection.id}' for ${id}: unresolved host from domain`);
+					return undefined;
+				}
 
-			// Don't resurrect a connection the user disconnected locally: a host "disconnect" only clears
-			// local state (the backend still lists the token), so without this the next non-forced sync would
-			// re-store the secret/config. A forced reconnect clears this flag (in the sync loop above) before
-			// reconcile runs, so it proceeds normally.
-			if (this.isLocallyDisconnected(id, host)) continue;
-
-			syncEligibleIds.add(connection.id);
-
-			// On a routine (non-forced) check-in, skip the token fetch + secret write for a connection we
-			// already have stored and that hasn't expired: nothing to refresh, so avoid the extra GK API
-			// traffic and secret churn. Still treat it as synced (so it doesn't trip the prune guard) and
-			// record its primary below. Forced syncs, new connections, and expired tokens fall through and
-			// fetch as before.
-			const cached = existingById.get(connection.id);
-			if (!forceConnect && cached != null && !isDescriptorExpired(cached)) {
-				syncedIds.add(connection.id);
-				if (connection.primary) {
-					const domain = isGitSelfManagedHostIntegrationId(id) ? host : undefined;
-					if (!syncedPrimaryIdsByDomain.has(domain)) {
-						syncedPrimaryIdsByDomain.set(domain, connection.id);
-					}
+				// Don't resurrect a connection the user disconnected locally: a host "disconnect" only clears
+				// local state (the backend still lists the token), so without this the next non-forced sync would
+				// re-store the secret/config. A forced reconnect clears this flag (in the sync loop above) before
+				// reconcile runs, so it proceeds normally.
+				if (this.isLocallyDisconnected(id, host)) return undefined;
+
+				syncEligibleIds.add(connection.id);
+
+				// On a routine (non-forced) check-in, skip the token fetch + secret write for a connection we
+				// already have stored and that hasn't expired: nothing to refresh, so avoid the extra GK API
+				// traffic and secret churn. Still treat it as synced (so it doesn't trip the prune guard) and
+				// record its primary below. Forced syncs, new connections, and expired tokens fall through and
+				// fetch as before.
+				const cached = existingById.get(connection.id);
+				if (!forceConnect && cached != null && !isDescriptorExpired(cached)) {
+					return { kind: 'cached' as const, connection: connection, host: host };
 				}
-				continue;
-			}
 
-			try {
-				const session = await cloudIntegrations.getConnectionSession(id, undefined, connection.id);
-				if (session == null) continue;
-
-				let providerSession = toProviderSession(id, connection, session, host);
-
-				// Resolve a human-readable account handle with the same precedence as the gk CLI:
-				// (1) the value the backend put on the connection, (2) a previously-resolved name cached in
-				// our configured store (keyed by connection id), (3) a live provider-API lookup. This keeps
-				// provider round-trips to the first sight of a connection; degrade to undefined on failure.
-				const existing = existingById.get(connection.id);
-				const accountName =
-					normalizeAccountName(connection.accountName) ??
-					normalizeAccountName(existing?.accountName) ??
-					(await this.resolveAccountName(id, host, providerSession));
-				if (accountName != null) {
-					providerSession = {
-						...providerSession,
-						account: { ...providerSession.account, label: accountName },
+				try {
+					const session = await cloudIntegrations.getConnectionSession(id, undefined, connection.id);
+					if (session == null) return undefined;
+
+					let providerSession = toProviderSession(id, connection, session, host);
+
+					// Resolve a human-readable account handle with the same precedence as the gk CLI:
+					// (1) the value the backend put on the connection, (2) a previously-resolved name cached in
+					// our configured store (keyed by connection id), (3) a live provider-API lookup. This keeps
+					// provider round-trips to the first sight of a connection; degrade to undefined on failure.
+					const existing = existingById.get(connection.id);
+					const accountName =
+						normalizeAccountName(connection.accountName) ??
+						normalizeAccountName(existing?.accountName) ??
+						(await this.resolveAccountName(id, host, providerSession));
+					if (accountName != null) {
+						providerSession = {
+							...providerSession,
+							account: { ...providerSession.account, label: accountName },
+						};
+					}
+
+					return {
+						kind: 'fetched' as const,
+						connection: connection,
+						host: host,
+						providerSession: providerSession,
 					};
+				} catch (ex) {
+					scope?.warn(
+						`Failed to sync connection '${connection.id}' for ${id}: ${ex instanceof Error ? ex.message : String(ex)}`,
+					);
+					return undefined;
 				}
+			}),
+		);
 
-				await this.configuredIntegrationService.storeSession(id, providerSession);
-				syncedIds.add(connection.id);
-				if (connection.primary) {
-					const domain = isGitSelfManagedHostIntegrationId(id) ? host : undefined;
-					if (!syncedPrimaryIdsByDomain.has(domain)) {
-						syncedPrimaryIdsByDomain.set(domain, connection.id);
-					}
+		// The remote work above is independent, but session persistence remains ordered because storage
+		// implementations may update a shared configured-connections collection with read-modify-write.
+		for (const prepared of preparedConnections) {
+			if (prepared == null) continue;
+
+			if (prepared.kind === 'fetched') {
+				await this.configuredIntegrationService.storeSession(id, prepared.providerSession);
+			}
+
+			syncedIds.add(prepared.connection.id);
+			if (prepared.connection.primary) {
+				const domain = isGitSelfManagedHostIntegrationId(id) ? prepared.host : undefined;
+				if (!syncedPrimaryIdsByDomain.has(domain)) {
+					syncedPrimaryIdsByDomain.set(domain, prepared.connection.id);
 				}
-			} catch (ex) {
-				scope?.warn(
-					`Failed to sync connection '${connection.id}' for ${id}: ${ex instanceof Error ? ex.message : String(ex)}`,
-				);
 			}
 		}
 

package/src/plus/integrations/manager.ts

@@ -1,10 +1,11 @@
-import type { IssueShape } from '../../git/models/issue.js';
+import type { IssueSearchCriteria, IssueShape } from '../../git/models/issue.js';
 import type { PullRequestShape, PullRequestStateFilter } from '../../git/models/pullRequest.js';
 import type { Event } from '../../utils/event.js';
 import type { ConfiguredIntegrationsChangeEvent } from './authentication/configuredIntegrationService.js';
 import type { ConfiguredIntegrationDescriptor } from './authentication/models.js';
 import type { IntegrationIds } from './constants.js';
-import type { IssueFilter, PullRequestFilter } from './providerFilters.js';
+import type { IssueFilter, IssueSearchCapabilities, PullRequestFilter } from './providerFilters.js';
+import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
 import type {
 	ConnectionStateChangeEvent,
 	ProviderBroadenResult,
@@ -200,6 +201,12 @@ export interface IntegrationManager {
 		pullRequestsAccountWide?: PullRequestFilter[];
 		issues: IssueFilter[];
 		issuesAccountWide: IssueFilter[];
+		/**
+		 * What {@link searchIssuesPage} (and {@link countIssues}, over the same criteria) can express for this
+		 * provider. Always present: a provider with no filtered issue search reports an empty `relationships` and
+		 * all-false flags, which is the signal to hide that surface rather than to hide individual chips.
+		 */
+		issueSearch: IssueSearchCapabilities;
 	};
 	/** Forces an authoritative cloud connection refresh. Rejects if the backend connection list cannot be read. */
 	refreshConnections(): Promise<void>;
@@ -306,6 +313,85 @@ export interface IntegrationManager {
 		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
 		domain?: string;
 	}): Promise<ProviderPagedResult<IssueShape>>;
+	/**
+	 * Issues matching structured criteria over a repository/org scope, with NO forced relationship to the current
+	 * user — the issue counterpart of the PR search, and the read to use for "every issue in these repos matching
+	 * X" rather than "my issues".
+	 *
+	 * Why this and not {@link listIssuesPage}: that read is either bound to the user's own relationships
+	 * (account-wide) or routed through the SDK's repo-scoped read, whose over-limit recovery walk can spend up to
+	 * 128 sequential requests and still return an incomplete set. This one is a single request per page.
+	 *
+	 * Three parts of the contract worth reading before calling:
+	 *
+	 * - **Scope is mandatory.** Pass `repos`, `org`, or a user relationship (`authored`/`assigned`/`mentioned`).
+	 *   `any-assignee`/`unassigned` do NOT scope anything — either alone matches every such issue on the host —
+	 *   so a call carrying only those is refused (warning + `fetchFailed`).
+	 * - **Ordering is always most-recently-updated-first**, not an option. A "show the N most recent" policy at
+	 *   the provider's result ceiling is only correct under a guaranteed order.
+	 * - **At the result ceiling the read SUCCEEDS.** It reports an omission carrying `totalCount` (how many
+	 *   matched) and `limit` (how many are reachable) with `recovery: 'none'`, so a consumer can say "19.240
+	 *   matched, showing the 1.000 most recent" and know not to offer a "load more". It never falls back to a
+	 *   per-repository recovery walk.
+	 *
+	 * Check `getSupportedFilters().issueSearch` first: a provider with no filtered issue search reports empty
+	 * relationships (and this read refuses), and a criterion it can't express refuses the whole read rather than
+	 * serving a wider result than asked for.
+	 */
+	searchIssuesPage(options: {
+		providerId: IntegrationIds;
+		/** Repositories to search. Combines with `org`; both constrain the same query. */
+		repos?: ProviderRepositoriesInput;
+		/** Organization/account to search. Combines with `repos`. */
+		org?: string;
+		criteria?: IssueSearchCriteria;
+		/**
+		 * Requested 1-based page. This read is cursor-only, so without a `cursor` reaching page N costs O(N)
+		 * upstream requests; pass the previous page's cursor to make it exactly one.
+		 */
+		page?: number;
+		cursor?: string;
+		/**
+		 * Page size PER RELATIONSHIP, not per page. Each requested relationship is its own provider query, so a
+		 * page of a 2-relationship search returns up to `2 × itemsPerPage` items before deduplication — and fewer
+		 * than that when the two overlap. `page.itemsPerPage` reports what actually came back, so size the UI off
+		 * that rather than off this. A provider may also cap it below what is asked for.
+		 */
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		connectionId?: string;
+		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+		domain?: string;
+	}): Promise<ProviderPagedResult<IssueShape>>;
+	/**
+	 * How many issues MATCH each scope, without fetching any of them — the probe behind a "this will fetch ~N
+	 * issues" preview, and behind a live count next to a filter the user hasn't applied yet.
+	 *
+	 * Cheap by design: every scope that can share a request does, and no issue data crosses the wire (measured
+	 * against GitHub, 30 counts are a single rate-limit point). Still a network request per batch, so debounce and
+	 * cache it if it's driven from UI state.
+	 *
+	 * A separate method rather than a flag on {@link searchIssuesPage} because transferring zero issues is the
+	 * whole point: a `countOnly` read would hand back a paged result whose `items`/`cursor`/`hasMore` are all
+	 * meaningless.
+	 *
+	 * Results are echoed under the caller's own `key`, so no positional matching is needed. Per-scope isolation is
+	 * the rule: a scope refused for its own reasons, or a batch that failed upstream, warns and drops only its own
+	 * scopes (with `fetchFailed` set) while every other count still comes back.
+	 *
+	 * `count: undefined` means the provider didn't report one — NOT zero, which is a real answer. Render the
+	 * difference: showing an unknown count as 0 tells the user a filter matches nothing when it may match
+	 * thousands. A provider that can't count at all (only GitHub/GHE can today) refuses the probe outright rather
+	 * than returning fabricated numbers.
+	 */
+	countIssues(options: {
+		providerId: IntegrationIds;
+		/** Each needs its own scope, and each requested relationship its own entry — see {@link IssueCountScope}. */
+		scopes: readonly IssueCountScope[];
+		connectionId?: string;
+		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+		domain?: string;
+	}): Promise<ProviderResult<IssueCountResult>>;
 	/** Issue trackers are cloud-only, so this read takes no `domain`. */
 	listIssueTrackerIssuesPage(options: {
 		providerId: IntegrationIds;