@gitkraken/core-gitlens 0.3.1 → 0.4.100

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

@@ -0,0 +1,202 @@
+import { microhash } from '../../../utils/hash.js';
+import type { IntegrationIds, SupportedCloudIntegrationIds } from '../constants.js';
+import {
+	GitCloudHostIntegrationId,
+	GitSelfManagedHostIntegrationId,
+	IssuesCloudHostIntegrationId,
+	supportedOrderedCloudIntegrationIds,
+} from '../constants.js';
+
+/**
+ * Mirrors the shape of `vscode.AuthenticationSession` so the integrations
+ * package can stay vscode-free. Host adapters bridge VS Code sessions to
+ * this shape via {@link AuthenticationProvider}.
+ */
+export interface AuthenticationSessionLike {
+	readonly id: string;
+	readonly accessToken: string;
+	readonly account: { readonly id: string; readonly label: string };
+	readonly scopes: readonly string[];
+}
+
+export interface ProviderAuthenticationSession extends AuthenticationSessionLike {
+	readonly cloud: boolean;
+	readonly type: CloudIntegrationAuthType | undefined;
+	readonly expiresAt?: Date;
+	readonly domain: string;
+	readonly protocol?: string;
+	/** The provider app key paired with the token for providers whose client needs one (e.g. Trello). */
+	readonly appKey?: string;
+}
+
+export interface TokenInfo<T extends IntegrationIds | 'gitkraken' = IntegrationIds | 'gitkraken'> {
+	readonly providerId: T;
+	/**
+	 * The first 3 characters of the md5 hash of the token.
+	 * It's a very obfuscated representation of the token that we can use in logs
+	 * to see whether the token survives refreshing or gets updated.
+	 */
+	readonly microHash: string | undefined;
+	readonly cloud: boolean;
+	readonly type: CloudIntegrationAuthType | undefined;
+	readonly scopes: readonly string[] | undefined;
+	readonly expiresAt?: Date;
+}
+
+export interface TokenWithInfo<T extends IntegrationIds = IntegrationIds> extends TokenInfo<T> {
+	readonly accessToken: string;
+}
+
+export function toTokenInfo<T extends IntegrationIds | 'gitkraken'>(
+	providerId: T,
+	accessToken: string | undefined,
+	info: { cloud: boolean; type: CloudIntegrationAuthType | undefined; scopes?: readonly string[]; expiresAt?: Date },
+): TokenInfo<T> {
+	return {
+		providerId: providerId,
+		microHash: microhash(accessToken, 3),
+		cloud: info.cloud,
+		type: info.type,
+		scopes: info.scopes,
+		expiresAt: info.expiresAt,
+	};
+}
+
+export function toTokenWithInfo<T extends IntegrationIds>(
+	providerId: T,
+	session: ProviderAuthenticationSession,
+	altToken?: string,
+): TokenWithInfo<T> {
+	const { accessToken: sessionToken, ...sessionInfo } = session;
+	const accessToken = altToken ?? session.accessToken;
+	return {
+		// pass original token info to form the correlated microhash
+		...toTokenInfo(providerId, sessionToken, sessionInfo),
+		// use the actual token used for the request
+		accessToken: accessToken,
+	};
+}
+
+export type TokenOptInfo<T extends IntegrationIds = IntegrationIds> =
+	| TokenWithInfo<T>
+	// `connectionId` targets a specific connection (multi-account) when the token still has to be resolved.
+	// Omitted resolves the provider's primary connection, preserving the pre-multi-account behavior.
+	| { providerId: T; accessToken?: undefined; connectionId?: string };
+
+export interface ConfiguredIntegrationDescriptor {
+	/**
+	 * Stable per-connection identifier, distinct from the domain, so multiple accounts can be
+	 * connected to the same provider+domain simultaneously. For legacy/migrated single connections
+	 * this is the domain (self-managed) or the provider's canonical domain (cloud), which keeps the
+	 * existing secret key (`integration.auth[.cloud]:{id}|{domain}`) valid with zero migration.
+	 */
+	readonly id: string;
+	/**
+	 * Whether this is the connection used by default for the provider. Optional: when no descriptor
+	 * for a provider+domain carries an explicit flag, the first one is treated as primary. Only
+	 * {@link ConfiguredIntegrationService.setPrimaryConnection} sets the flag (and clears it on siblings).
+	 */
+	readonly primary?: boolean;
+	/** The connection's auth type (`oauth`/`pat`), when known. */
+	readonly type?: CloudIntegrationAuthType;
+	/**
+	 * Human-readable account handle for this connection (e.g. the GitHub login). Resolved from the
+	 * provider API (the token backend doesn't expose it); absent until resolved or if the lookup fails.
+	 */
+	readonly accountName?: string;
+	readonly cloud: boolean;
+	readonly integrationId: IntegrationIds;
+	readonly scopes: string;
+	readonly domain?: string;
+	readonly expiresAt?: string | Date;
+}
+
+export interface CloudIntegrationAuthenticationSession {
+	type: CloudIntegrationAuthType;
+	accessToken: string;
+	domain: string;
+	expiresIn: number;
+	scopes: string;
+	/** Backend per-connection token identifier, when the provider-tokens backend supports multi-account. */
+	id?: string;
+	/** Provider app key paired with the token (e.g. Trello app key), when the backend supplies one. */
+	appKey?: string;
+}
+
+export interface CloudIntegrationAuthorization {
+	url: string;
+}
+
+export interface CloudIntegrationConnection {
+	type: CloudIntegrationAuthType;
+	provider: CloudIntegrationType;
+	domain: string;
+	/** Backend per-connection token identifier, when the provider-tokens backend supports multi-account. */
+	id?: string;
+	/** Whether the backend marks this connection as the primary/default for the provider. */
+	primary?: boolean;
+	/** Human-readable account handle, when the backend provides it on the connection (may be absent). */
+	accountName?: string;
+}
+
+export type CloudIntegrationType =
+	| 'jira'
+	| 'linear'
+	| 'trello'
+	| 'gitlab'
+	| 'github'
+	| 'bitbucket'
+	| 'bitbucketServer'
+	| 'azure'
+	| 'azureDevopsServer'
+	| 'githubEnterprise'
+	| 'gitlabSelfHosted';
+
+export type CloudIntegrationAuthType = 'oauth' | 'pat';
+
+export const CloudIntegrationAuthenticationUriPathPrefix = 'did-authenticate-cloud-integration';
+
+/** Returns all supported cloud integration ids. */
+export function getSupportedCloudIntegrationIds(): readonly SupportedCloudIntegrationIds[] {
+	// Return the shared const directly (readonly so callers can't mutate it) — this runs on hot,
+	// per-integration membership paths, so avoid allocating a fresh array per call.
+	return supportedOrderedCloudIntegrationIds;
+}
+
+/** Whether `id` is a supported cloud integration id. */
+export function isSupportedCloudIntegrationId(id: string): id is SupportedCloudIntegrationIds {
+	return getSupportedCloudIntegrationIds().includes(id as SupportedCloudIntegrationIds);
+}
+
+export function isIssueCloudIntegrationId(id: string): id is IssuesCloudHostIntegrationId {
+	const issueIds: string[] = Object.values(IssuesCloudHostIntegrationId);
+	return issueIds.includes(id);
+}
+
+export const toIntegrationId: { [key in CloudIntegrationType]: IntegrationIds } = {
+	jira: IssuesCloudHostIntegrationId.Jira,
+	linear: IssuesCloudHostIntegrationId.Linear,
+	trello: IssuesCloudHostIntegrationId.Trello,
+	gitlab: GitCloudHostIntegrationId.GitLab,
+	github: GitCloudHostIntegrationId.GitHub,
+	githubEnterprise: GitSelfManagedHostIntegrationId.CloudGitHubEnterprise,
+	gitlabSelfHosted: GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted,
+	bitbucket: GitCloudHostIntegrationId.Bitbucket,
+	bitbucketServer: GitSelfManagedHostIntegrationId.BitbucketServer,
+	azure: GitCloudHostIntegrationId.AzureDevOps,
+	azureDevopsServer: GitSelfManagedHostIntegrationId.AzureDevOpsServer,
+};
+
+export const toCloudIntegrationType: { [key in IntegrationIds]: CloudIntegrationType | undefined } = {
+	[IssuesCloudHostIntegrationId.Jira]: 'jira',
+	[IssuesCloudHostIntegrationId.Linear]: 'linear',
+	[IssuesCloudHostIntegrationId.Trello]: 'trello',
+	[GitCloudHostIntegrationId.GitLab]: 'gitlab',
+	[GitCloudHostIntegrationId.GitHub]: 'github',
+	[GitCloudHostIntegrationId.Bitbucket]: 'bitbucket',
+	[GitCloudHostIntegrationId.AzureDevOps]: 'azure',
+	[GitSelfManagedHostIntegrationId.AzureDevOpsServer]: 'azureDevopsServer',
+	[GitSelfManagedHostIntegrationId.CloudGitHubEnterprise]: 'githubEnterprise',
+	[GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted]: 'gitlabSelfHosted',
+	[GitSelfManagedHostIntegrationId.BitbucketServer]: 'bitbucketServer',
+};

package/src/plus/integrations/collectionMetadata.ts

@@ -0,0 +1,143 @@
+import type { CollectionMetadata, CollectionScopeFailure } from '@gitkraken/provider-apis';
+import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
+import type { IntegrationIds } from './constants.js';
+import { isRateLimitResponse } from './errors.js';
+import type { ProviderWarning } from './results.js';
+import { appendDedupedWarning } from './results.js';
+
+/**
+ * Maps a caught GitLens request error to the SDK collection failure vocabulary used inside provider fan-outs.
+ */
+export function toCollectionFailureKind(ex: unknown): CollectionScopeFailure['kind'] {
+	if (ex instanceof AuthenticationError) return 'authentication';
+	if (ex instanceof RequestRateLimitError) return 'rate-limit';
+	if (ex instanceof RequestNotFoundError) return 'not-found';
+	return 'provider';
+}
+
+/** Builds a structured SDK scope failure from a caught GitLens request error. */
+export function toCollectionScopeFailure(scope: CollectionScopeFailure['scope'], ex: unknown): CollectionScopeFailure {
+	return {
+		scope: scope,
+		kind: toCollectionFailureKind(ex),
+		...(ex instanceof Error && ex.message ? { message: ex.message } : {}),
+	};
+}
+
+function collectionFailureKindToWarningKind(kind: CollectionScopeFailure['kind']): ProviderWarning['kind'] {
+	switch (kind) {
+		case 'authentication':
+			return 'auth';
+		case 'rate-limit':
+			return 'rate-limit';
+		case 'not-found':
+			return 'not-found';
+		default:
+			return 'other';
+	}
+}
+
+function getCollectionFailureStatus(message: string | undefined): number | undefined {
+	if (message == null) return undefined;
+
+	const match = /\((\d{3})\)/.exec(message) ?? /^(?:HTTP\s+)?(\d{3})\b/i.exec(message.trim());
+	return match != null ? Number(match[1]) : undefined;
+}
+
+function toCollectionFailureWarningKind(failure: CollectionScopeFailure): ProviderWarning['kind'] {
+	const mapped = collectionFailureKindToWarningKind(failure.kind);
+	if (mapped !== 'other' || (failure.kind !== 'provider' && failure.kind !== 'unknown')) return mapped;
+
+	// provider-apis currently groups several HTTP statuses under `provider` in partial fan-outs. The custom
+	// fetch adapter retains the status in `message`, so recover the same neutral classification the thrown-error
+	// path exposes instead of downgrading these structured failures to `other`.
+	const status = getCollectionFailureStatus(failure.message);
+	switch (status) {
+		case 401:
+			return 'auth';
+		case 403:
+			return isRateLimitResponse({ status: status, message: failure.message }) ? 'rate-limit' : 'auth';
+		case 404:
+		case 410:
+		case 422:
+			return 'not-found';
+		case 429:
+			return 'rate-limit';
+		default:
+			return mapped;
+	}
+}
+
+function collectionFailureMessage(failure: CollectionScopeFailure): string {
+	const scope = failure.scope;
+	const parts: string[] = [];
+	if (scope?.resourceId != null) {
+		parts.push(`resource ${scope.resourceId}`);
+	}
+	if (scope?.projectId != null) {
+		parts.push(`project ${scope.projectId}`);
+	}
+	if (scope?.repositoryId != null) {
+		parts.push(`repository ${scope.repositoryId}`);
+	}
+
+	const scopeText = parts.length ? ` (${parts.join(', ')})` : '';
+	const detail = failure.message != null ? `: ${failure.message}` : '';
+	return `Failed to read ${failure.kind} scope${scopeText}${detail}`;
+}
+
+/** Converts internal SDK collection metadata into neutral provider facade signals. */
+export function assessCollectionMetadata(
+	providerId: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	metadata: CollectionMetadata | undefined,
+): { warnings: ProviderWarning[]; fetchFailed: boolean; truncated: boolean } {
+	if (metadata == null) return { warnings: [], fetchFailed: false, truncated: false };
+
+	const warnings: ProviderWarning[] = [];
+	const failures = metadata.failures ?? [];
+	for (const failure of failures) {
+		const kind = toCollectionFailureWarningKind(failure);
+		appendDedupedWarning(warnings, {
+			providerId: providerId,
+			domain: domain,
+			connectionId: connectionId,
+			message: collectionFailureMessage(failure),
+			kind: kind,
+			isAuth: kind === 'auth',
+		});
+	}
+
+	const incomplete = metadata.completeness !== 'complete';
+	if (incomplete && failures.length === 0) {
+		appendDedupedWarning(warnings, {
+			providerId: providerId,
+			domain: domain,
+			connectionId: connectionId,
+			message:
+				metadata.completeness === 'partial'
+					? 'Some results were omitted; the read is incomplete'
+					: 'Result completeness could not be confirmed',
+			kind: 'other',
+			isAuth: false,
+		});
+	}
+
+	return { warnings: warnings, fetchFailed: failures.length > 0, truncated: incomplete };
+}
+
+/** Appends neutral warnings derived from SDK metadata and returns its failure/truncation assessment. */
+export function mergeAssessmentInto(
+	warnings: ProviderWarning[],
+	providerId: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	metadata: CollectionMetadata | undefined,
+): { fetchFailed: boolean; truncated: boolean } {
+	const assessment = assessCollectionMetadata(providerId, domain, connectionId, metadata);
+	for (const warning of assessment.warnings) {
+		appendDedupedWarning(warnings, warning);
+	}
+	return { fetchFailed: assessment.fetchFailed, truncated: assessment.truncated };
+}

package/src/plus/integrations/constants.ts

@@ -0,0 +1,190 @@
+import type { CloudIntegrationAuthType } from './authentication/models.js';
+
+export const providerFanOutConcurrency = 6;
+
+export enum GitCloudHostIntegrationId {
+	GitHub = 'github',
+	GitLab = 'gitlab',
+	Bitbucket = 'bitbucket',
+	AzureDevOps = 'azureDevOps',
+}
+
+export enum GitSelfManagedHostIntegrationId {
+	BitbucketServer = 'bitbucket-server',
+	CloudGitHubEnterprise = 'cloud-github-enterprise',
+	CloudGitLabSelfHosted = 'cloud-gitlab-self-hosted',
+	AzureDevOpsServer = 'azure-devops-server',
+}
+
+export enum IssuesCloudHostIntegrationId {
+	Jira = 'jira',
+	Linear = 'linear',
+	Trello = 'trello',
+}
+
+export type CloudGitSelfManagedHostIntegrationIds =
+	| GitSelfManagedHostIntegrationId.CloudGitHubEnterprise
+	| GitSelfManagedHostIntegrationId.BitbucketServer
+	| GitSelfManagedHostIntegrationId.AzureDevOpsServer
+	| GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted;
+
+export type GitHostIntegrationIds = GitCloudHostIntegrationId | GitSelfManagedHostIntegrationId;
+export type IssuesHostIntegrationIds = IssuesCloudHostIntegrationId;
+
+export type IntegrationIds = GitHostIntegrationIds | IssuesHostIntegrationIds;
+
+export const supportedOrderedCloudIssuesIntegrationIds = [
+	IssuesCloudHostIntegrationId.Jira,
+	IssuesCloudHostIntegrationId.Linear,
+	IssuesCloudHostIntegrationId.Trello,
+];
+export const supportedOrderedCloudIntegrationIds = [
+	GitCloudHostIntegrationId.GitHub,
+	GitSelfManagedHostIntegrationId.CloudGitHubEnterprise,
+	GitCloudHostIntegrationId.GitLab,
+	GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted,
+	GitCloudHostIntegrationId.AzureDevOps,
+	GitSelfManagedHostIntegrationId.AzureDevOpsServer,
+	GitCloudHostIntegrationId.Bitbucket,
+	GitSelfManagedHostIntegrationId.BitbucketServer,
+	IssuesCloudHostIntegrationId.Jira,
+	IssuesCloudHostIntegrationId.Linear,
+	IssuesCloudHostIntegrationId.Trello,
+];
+
+export const integrationIds = [
+	GitCloudHostIntegrationId.GitHub,
+	GitCloudHostIntegrationId.GitLab,
+	GitCloudHostIntegrationId.Bitbucket,
+	GitCloudHostIntegrationId.AzureDevOps,
+	GitSelfManagedHostIntegrationId.AzureDevOpsServer,
+	GitSelfManagedHostIntegrationId.BitbucketServer,
+	GitSelfManagedHostIntegrationId.CloudGitHubEnterprise,
+	GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted,
+	IssuesCloudHostIntegrationId.Jira,
+	IssuesCloudHostIntegrationId.Linear,
+	IssuesCloudHostIntegrationId.Trello,
+];
+
+export type SupportedCloudIntegrationIds = (typeof supportedOrderedCloudIntegrationIds)[number];
+
+export function isSupportedCloudIntegrationId(id: IntegrationIds): id is SupportedCloudIntegrationIds {
+	return supportedOrderedCloudIntegrationIds.includes(id);
+}
+
+export function isIntegrationId(id: string): id is IntegrationIds {
+	return integrationIds.includes(id as IntegrationIds);
+}
+
+export type IntegrationFeatures = 'prs' | 'issues';
+
+export interface IntegrationDescriptor {
+	id: SupportedCloudIntegrationIds;
+	name: string;
+	icon: string;
+	supports: IntegrationFeatures[];
+	requiresPro: boolean;
+}
+
+/** Stored shape of a configured-integration descriptor in workspace state. */
+export interface StoredConfiguredIntegrationDescriptor {
+	/** Stable per-connection identifier. Backfilled from the domain for pre-multi-account stored data. */
+	id?: string;
+	/** Whether this is the primary/default connection for the provider. */
+	primary?: boolean;
+	/** The connection's auth type (`oauth`/`pat`), when known. */
+	type?: CloudIntegrationAuthType;
+	/** Human-readable account handle for this connection (e.g. the GitHub login), when resolved. */
+	accountName?: string;
+	cloud: boolean;
+	integrationId: IntegrationIds;
+	domain?: string;
+	expiresAt?: string;
+	scopes: string;
+}
+
+/** Stored shape of the `integrations:configured` storage key. */
+export type StoredIntegrationConfigurations = Record<
+	IntegrationIds,
+	StoredConfiguredIntegrationDescriptor[] | undefined
+>;
+
+export const supportedCloudIntegrationDescriptors: IntegrationDescriptor[] = [
+	{
+		id: GitCloudHostIntegrationId.GitHub,
+		name: 'GitHub',
+		icon: 'gl-provider-github',
+		supports: ['prs', 'issues'],
+		requiresPro: false,
+	},
+	{
+		id: GitSelfManagedHostIntegrationId.CloudGitHubEnterprise,
+		name: 'GitHub Enterprise',
+		icon: 'gl-provider-github',
+		supports: ['prs', 'issues'],
+		requiresPro: true,
+	},
+	{
+		id: GitCloudHostIntegrationId.GitLab,
+		name: 'GitLab',
+		icon: 'gl-provider-gitlab',
+		supports: ['prs', 'issues'],
+		requiresPro: false,
+	},
+	{
+		id: GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted,
+		name: 'GitLab Self-Hosted',
+		icon: 'gl-provider-gitlab',
+		supports: ['prs', 'issues'],
+		requiresPro: true,
+	},
+	{
+		id: GitCloudHostIntegrationId.AzureDevOps,
+		name: 'Azure DevOps',
+		icon: 'gl-provider-azdo',
+		supports: ['prs', 'issues'],
+		requiresPro: true,
+	},
+	{
+		id: GitSelfManagedHostIntegrationId.AzureDevOpsServer,
+		name: 'Azure DevOps Server',
+		icon: 'gl-provider-azdo',
+		supports: ['prs', 'issues'],
+		requiresPro: true,
+	},
+	{
+		id: GitCloudHostIntegrationId.Bitbucket,
+		name: 'Bitbucket',
+		icon: 'gl-provider-bitbucket',
+		supports: ['prs', 'issues'],
+		requiresPro: false,
+	},
+	{
+		id: GitSelfManagedHostIntegrationId.BitbucketServer,
+		name: 'Bitbucket Data Center',
+		icon: 'gl-provider-bitbucket',
+		supports: ['prs'],
+		requiresPro: true,
+	},
+	{
+		id: IssuesCloudHostIntegrationId.Jira,
+		name: 'Jira',
+		icon: 'gl-provider-jira',
+		supports: ['issues'],
+		requiresPro: true,
+	},
+	{
+		id: IssuesCloudHostIntegrationId.Linear,
+		name: 'Linear',
+		icon: 'gl-provider-linear',
+		supports: ['issues'],
+		requiresPro: true,
+	},
+	{
+		id: IssuesCloudHostIntegrationId.Trello,
+		name: 'Trello',
+		icon: 'gl-provider-trello',
+		supports: ['issues'],
+		requiresPro: true,
+	},
+];