@githits/mcp 0.9.1 → 0.10.0

package/dist/client.d.ts

@@ -9,9 +9,23 @@
 * Back-compat: `src/shared/code-navigation.ts` re-exports these under
 * the existing `CodeNavigationRegistry*` names.
 */
-type PkgseerRegistry = "NPM" | "PYPI" | "HEX" | "CRATES" | "NUGET" | "MAVEN" | "ZIG" | "VCPKG" | "PACKAGIST" | "RUBYGEMS" | "GO" | "SWIFT";
 declare const PKGSEER_REGISTRY_ARGS: readonly ["npm", "pypi", "hex", "crates", "nuget", "maven", "zig", "vcpkg", "packagist", "rubygems", "go", "swift"];
 type PkgseerRegistryArg = (typeof PKGSEER_REGISTRY_ARGS)[number];
+declare const registryMap: {
+	readonly npm: "NPM";
+	readonly pypi: "PYPI";
+	readonly hex: "HEX";
+	readonly crates: "CRATES";
+	readonly nuget: "NUGET";
+	readonly maven: "MAVEN";
+	readonly zig: "ZIG";
+	readonly vcpkg: "VCPKG";
+	readonly packagist: "PACKAGIST";
+	readonly rubygems: "RUBYGEMS";
+	readonly go: "GO";
+	readonly swift: "SWIFT";
+};
+type PkgseerRegistry = (typeof registryMap)[keyof typeof registryMap];
 declare const PKGSEER_REGISTRY_LIST: string;
 /**
 * Lowercase surface value → uppercase backend enum. Exhaustive over
@@ -124,13 +138,7 @@ type UnifiedSearchSource = "AUTO" | "DOCS" | "CODE" | "SYMBOL";
 type UnifiedSearchResultType = "DOCUMENTATION_PAGE" | "REPOSITORY_SYMBOL" | "REPOSITORY_CODE" | "REPOSITORY_DOC";
 type UnifiedSearchSessionStatus = "PENDING" | "INDEXING" | "SEARCHING" | "COMPLETED" | "TIMEOUT" | "FAILED";
 type CodeIndexState = "CURRENT" | "INDEXED" | "INDEXING" | "STALE" | "FAILED" | "MISSING" | string;
-/**
-* Coverage lifecycle for crawled documentation site data.
-*
-* `PARTIAL` is transient (a crawl is still running, so retrying later can
-* return more); `CAPPED` is terminal (a crawl limit stopped indexing, so
-* retrying will not help). Both mean served evidence may be incomplete.
-*/
+/** Coverage state of the selected published documentation corpus. */
 type DocCoverageState = "NONE" | "PARTIAL" | "CAPPED" | "COMPLETE" | string;
 /**
 * Coverage metadata for crawled documentation site data. Present on docs
@@ -140,10 +148,10 @@ interface DocCoverage {
 	coverageState: DocCoverageState;
 	coverageReason?: string;
 	pagesCrawled?: number;
-	frontierRemaining?: number;
+	frontierRemaining?: number | null;
 	artifactOverflowPageCount?: number;
 	estimatedTotalPages?: number;
-	/** Backend-owned note suitable for CLI/MCP rendering. Preferred over client wording. */
+	/** Backend-owned coverage note retained for structured callers. */
 	note?: string;
 }
 type DiscoveryRequestedRefKind = "OMITTED_VERSION" | "LATEST_VERSION" | "EXACT_VERSION" | "DEFAULT_BRANCH" | "HEAD" | "BRANCH" | "SHA";
@@ -224,8 +232,26 @@ interface UnifiedSearchSourceStatus {
 	appliedQueryFeatures: string[];
 	ignoredQueryFeatures: string[];
 	incompatibleQueryFeatures: string[];
+	suggestedSiteTargets: string[];
+	suggestedSiteTargetsTruncated: boolean;
 	note?: string;
 	coverage?: DocCoverage;
+	contributors?: UnifiedSearchDocumentationContributor[];
+}
+type UnifiedSearchDocumentationContributorKind = "REPOSITORY_DOCS" | "DOCPACK";
+type UnifiedSearchDocumentationContributorState = "SEARCHED" | "READY" | "PENDING" | "UNAVAILABLE";
+type UnifiedSearchDocumentationFreshness = "CURRENT" | "STALE";
+/** One physical documentation corpus disclosed for a DOCS source row. */
+interface UnifiedSearchDocumentationContributor {
+	kind: UnifiedSearchDocumentationContributorKind;
+	state: UnifiedSearchDocumentationContributorState;
+	freshness?: UnifiedSearchDocumentationFreshness;
+	resultCount: number;
+	repositoryUrl?: string;
+	commitSha?: string;
+	siteKey?: string;
+	siteUrl?: string;
+	coverage?: DocCoverage;
 }
 interface UnifiedSearchProgressTarget {
 	requested?: string;
@@ -256,6 +282,7 @@ interface UnifiedSearchResult {
 	page: UnifiedSearchPageInfo;
 	partialResults: boolean;
 	sourceStatus: UnifiedSearchSourceStatus[];
+	evidenceNotice?: string;
 }
 interface UnifiedSearchProgress {
 	searchRef: string;
@@ -350,6 +377,159 @@ interface ReadFileResult {
 	targetResolution?: TargetResolution;
 	availableVersions?: AvailableVersion[];
 }
+/**
+* A package-addressing target for a repository-wide CodeDiff. Version
+* resolution belongs to the comparison endpoints, so this target
+* intentionally has no version field. Package addressing resolves repository
+* identity and commits; it does not narrow raw file results to a package path.
+* Target selection uses own-key presence; a `repoUrl` key rejects this shape
+* even when its value is `undefined`.
+*/
+interface CodeDiffPackageTarget {
+	registry: CodeNavigationRegistry;
+	packageName: string;
+}
+/**
+* A public repository target for CodeDiff. Ref resolution belongs to the
+* comparison endpoints, so this target intentionally has no gitRef field.
+* Target selection uses own-key presence; a `registry` or `packageName` key
+* rejects this shape even when its value is `undefined`.
+*/
+interface CodeDiffRepositoryTarget {
+	repoUrl: string;
+}
+type CodeDiffTarget = CodeDiffPackageTarget | CodeDiffRepositoryTarget;
+type CodeDiffMode = "inventory" | "stats" | "patches";
+interface CodeDiffOptions {
+	maxFiles?: number;
+	maxPatchBytes?: number;
+	pathPrefix?: string;
+	pathGlob?: string;
+}
+interface CodeDiffParams {
+	target: CodeDiffTarget;
+	from: string;
+	to: string;
+	mode: CodeDiffMode;
+	options?: CodeDiffOptions;
+}
+type CodeDiffRefKind = "SHA" | "TAG" | "BRANCH" | "HEAD" | "UNKNOWN";
+type CodeDiffVersionSource = "REGISTRY" | "GIT_HEAD" | "TAG" | "RELEASE";
+/**
+* Effective raw inventory scope. Current successful backends return
+* `REPOSITORY`; `PACKAGE` and `UNKNOWN` remain accepted for compatibility with
+* legacy responses.
+*/
+type RawCodeDiffScopeStatus = "PACKAGE" | "REPOSITORY" | "UNKNOWN";
+type RawCodeDiffFileStatus = "ADDED" | "DELETED" | "MODIFIED";
+type RawCodeDiffPathEncoding = "UTF8" | "BYTE_ESCAPED";
+type RawCodeDiffFileContentStatus = "NOT_REQUESTED" | "STATS" | "PATCH" | "BINARY" | "METADATA_ONLY" | "OMITTED" | "UNAVAILABLE";
+type RawCodeDiffContentCoverage = "NOT_REQUESTED" | "COMPLETE" | "PARTIAL" | "FAILED";
+type ContentModification = "INVISIBLE_CONTROLS_STRIPPED" | "HTML_COMMENTS_STRIPPED" | "IMAGES_REPLACED" | "UNSAFE_LINKS_NEUTRALIZED";
+interface CodeDiffPackageInfo {
+	registry: CodeNavigationRegistry;
+	name: string;
+	repoUrl: string;
+}
+interface CodeDiffRefResolution {
+	requested: string;
+	resolvedVersion?: string;
+	ref: string;
+	commitSha: string;
+	refKind: CodeDiffRefKind;
+	versionSource?: CodeDiffVersionSource;
+}
+interface RawCodeDiffSummary {
+	filesChanged: number;
+	added: number;
+	deleted: number;
+	modified: number;
+	modeChanged: number;
+	typeChanged: number;
+	inventoryComplete: boolean;
+	unprojectableFiles: number;
+}
+interface RawCodeDiffScope {
+	/** Scope of returned paths and counts, independent of addressing form. */
+	status: RawCodeDiffScopeStatus;
+	/** Legacy package-scope metadata; absent from current repository results. */
+	fromSubpath?: string;
+	/** Legacy package-scope metadata; absent from current repository results. */
+	toSubpath?: string;
+	/** Caller-supplied repository-relative filter, not verified package scope. */
+	pathPrefix?: string;
+	/** Caller-supplied repository-relative filter, not verified package scope. */
+	pathGlob?: string;
+}
+interface RawCodeDiffContentFailure {
+	code: string;
+	retryable: boolean;
+	retryAfterMs?: number;
+	stage?: string;
+	limitKind?: string;
+}
+interface ContentSafety {
+	filtered: boolean;
+	modifications: ContentModification[];
+}
+interface RawCodeDiffFile {
+	path: string;
+	pathEncoding: RawCodeDiffPathEncoding;
+	status: RawCodeDiffFileStatus;
+	modeChanged: boolean;
+	typeChanged: boolean;
+	additions?: number;
+	deletions?: number;
+	patch?: string;
+	contentStatus: RawCodeDiffFileContentStatus;
+	contentOmissionReason?: string;
+	contentSafety: ContentSafety;
+}
+interface RawCodeDiff {
+	summary: RawCodeDiffSummary;
+	scope: RawCodeDiffScope;
+	contentCoverage: RawCodeDiffContentCoverage;
+	contentFailure?: RawCodeDiffContentFailure;
+	files: RawCodeDiffFile[];
+	hasMoreFiles: boolean;
+}
+interface CodeDiffResult {
+	package?: CodeDiffPackageInfo;
+	fromResolution: CodeDiffRefResolution;
+	toResolution: CodeDiffRefResolution;
+	raw: RawCodeDiff;
+}
+interface CodeDiffErrorRef {
+	ref: string;
+	version?: string;
+}
+/**
+* Bounded metadata retained from PkgSeer CodeDiff GraphQL errors. Do not add
+* arbitrary extension values here: this object is safe to pass to public
+* error envelopes and telemetry.
+*/
+interface CodeDiffErrorDetails {
+	code?: string;
+	retryable?: boolean;
+	side?: string;
+	publishedVersions?: string[];
+	publishedVersionsTruncated?: boolean;
+	registry?: string;
+	retryAfterMs?: number;
+	stage?: string;
+	limitKind?: string;
+	repoUrl?: string;
+	gitRef?: string;
+	availableRefs?: CodeDiffErrorRef[];
+	suggestedRefs?: CodeDiffErrorRef[];
+	refKinds?: string[];
+}
+interface CodeDiffPartialResult {
+	package?: CodeDiffPackageInfo;
+	fromResolution: CodeDiffRefResolution;
+	toResolution: CodeDiffRefResolution;
+	raw?: RawCodeDiff;
+}
 type GrepRepoPatternType = "LITERAL" | "REGEX";
 type GrepPathSelectorKind = "EXACT" | "PREFIX" | "GLOB";
 interface GrepRepoPathSelector {
@@ -429,7 +609,20 @@ interface CodeNavigationService {
 	readFile(params: ReadFileParams): Promise<ReadFileResult>;
 	grepRepo(params: GrepRepoParams): Promise<GrepRepoResult>;
 }
-declare class CodeNavigationServiceImpl implements CodeNavigationService {
+/** Additive client capability for the unpromoted CodeDiff surface. */
+interface CodeDiffService {
+	codeDiff(params: CodeDiffParams): Promise<CodeDiffResult>;
+}
+/**
+* GraphQL resolver error for CodeDiff. `partial` is present only when the
+* backend returned a valid root resolution alongside a field-local error.
+*/
+declare class CodeDiffError extends Error {
+	readonly details: CodeDiffErrorDetails | undefined;
+	readonly partial: CodeDiffPartialResult | undefined;
+	constructor(message: string, details?: CodeDiffErrorDetails | undefined, partial?: CodeDiffPartialResult | undefined);
+}
+declare class CodeNavigationServiceImpl implements CodeNavigationService, CodeDiffService {
 	private readonly codeNavigationUrl;
 	private readonly tokenProvider;
 	private readonly fetchFn;
@@ -442,6 +635,9 @@ declare class CodeNavigationServiceImpl implements CodeNavigationService {
 	private postGraphqlWithTargetResolutionFallback;
 	search(params: UnifiedSearchParams): Promise<UnifiedSearchOutcome>;
 	searchStatus(searchRef: string, waitTimeoutMs?: number): Promise<UnifiedSearchOutcome>;
+	codeDiff(params: CodeDiffParams): Promise<CodeDiffResult>;
+	private executeCodeDiff;
+	private createCodeDiffRootError;
 	private executeUnifiedSearch;
 	private executeUnifiedSearchStatus;
 	private createHttpError;
@@ -1275,4 +1471,4 @@ declare function withTelemetrySpan<T>(name: string, operation: () => Promise<T>,
 declare function startTelemetrySpan(name: string, attributes?: TelemetryAttributes): TelemetrySpanHandle | undefined;
 declare function endTelemetrySpan(handle: TelemetrySpanHandle | undefined, attributes?: TelemetryAttributes): void;
 declare function flushTelemetry(exitCode?: number): void;
-export { withTelemetrySpan, toPkgseerRegistryLowercase, toPkgseerRegistry, startTelemetrySpan, getMcpUrl, getEnvApiToken, getCodeNavigationUrl, getApiUrl, flushTelemetry, endTelemetrySpan, createStaticTokenProvider, createClientHeaderBuilder, TokenProvider, RefreshingGitHitsService, PackageIntelligenceServiceImpl, PackageIntelligenceService, PKGSEER_REGISTRY_LIST, GitHitsServiceImpl, GitHitsService, DEFAULT_MCP_URL, DEFAULT_CODE_NAV_URL, DEFAULT_API_URL, CodeNavigationServiceImpl, CodeNavigationService, AgentInfo };
+export { withTelemetrySpan, toPkgseerRegistryLowercase, toPkgseerRegistry, startTelemetrySpan, getMcpUrl, getEnvApiToken, getCodeNavigationUrl, getApiUrl, flushTelemetry, endTelemetrySpan, createStaticTokenProvider, createClientHeaderBuilder, TokenProvider, RefreshingGitHitsService, RawCodeDiffSummary, RawCodeDiffScopeStatus, RawCodeDiffScope, RawCodeDiffPathEncoding, RawCodeDiffFileStatus, RawCodeDiffFileContentStatus, RawCodeDiffFile, RawCodeDiffContentFailure, RawCodeDiffContentCoverage, RawCodeDiff, PackageIntelligenceServiceImpl, PackageIntelligenceService, PKGSEER_REGISTRY_LIST, GitHitsServiceImpl, GitHitsService, DEFAULT_MCP_URL, DEFAULT_CODE_NAV_URL, DEFAULT_API_URL, ContentSafety, ContentModification, CodeNavigationServiceImpl, CodeNavigationService, CodeDiffVersionSource, CodeDiffTarget, CodeDiffService, CodeDiffResult, CodeDiffRepositoryTarget, CodeDiffRefResolution, CodeDiffRefKind, CodeDiffPartialResult, CodeDiffParams, CodeDiffPackageTarget, CodeDiffPackageInfo, CodeDiffOptions, CodeDiffMode, CodeDiffErrorRef, CodeDiffErrorDetails, CodeDiffError, AgentInfo };

package/dist/client.js

@@ -1 +1 @@
-import{CodeNavigationServiceImpl,DEFAULT_API_URL,DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL,GitHitsServiceImpl,PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl,RefreshingGitHitsService,createClientHeaderBuilder,createStaticTokenProvider,endTelemetrySpan,flushTelemetry,getApiUrl,getCodeNavigationUrl,getEnvApiToken,getMcpUrl,startTelemetrySpan,toPkgseerRegistry,toPkgseerRegistryLowercase,withTelemetrySpan}from"./shared/chunk-xd3b13qj.js";export{withTelemetrySpan,toPkgseerRegistryLowercase,toPkgseerRegistry,startTelemetrySpan,getMcpUrl,getEnvApiToken,getCodeNavigationUrl,getApiUrl,flushTelemetry,endTelemetrySpan,createStaticTokenProvider,createClientHeaderBuilder,RefreshingGitHitsService,PackageIntelligenceServiceImpl,PKGSEER_REGISTRY_LIST,GitHitsServiceImpl,DEFAULT_MCP_URL,DEFAULT_CODE_NAV_URL,DEFAULT_API_URL,CodeNavigationServiceImpl};
+import{CodeDiffError,CodeNavigationServiceImpl,DEFAULT_API_URL,DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL,GitHitsServiceImpl,PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl,RefreshingGitHitsService,createClientHeaderBuilder,createStaticTokenProvider,endTelemetrySpan,flushTelemetry,getApiUrl,getCodeNavigationUrl,getEnvApiToken,getMcpUrl,startTelemetrySpan,toPkgseerRegistry,toPkgseerRegistryLowercase,withTelemetrySpan}from"./shared/chunk-qawyzgzx.js";export{withTelemetrySpan,toPkgseerRegistryLowercase,toPkgseerRegistry,startTelemetrySpan,getMcpUrl,getEnvApiToken,getCodeNavigationUrl,getApiUrl,flushTelemetry,endTelemetrySpan,createStaticTokenProvider,createClientHeaderBuilder,RefreshingGitHitsService,PackageIntelligenceServiceImpl,PKGSEER_REGISTRY_LIST,GitHitsServiceImpl,DEFAULT_MCP_URL,DEFAULT_CODE_NAV_URL,DEFAULT_API_URL,CodeNavigationServiceImpl,CodeDiffError};

package/dist/index.d.ts

@@ -16,18 +16,21 @@ interface BuildMcpInstructionsOptions {
 }
 declare function buildMcpInstructions(options?: BuildMcpInstructionsOptions): string;
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/**
-* Registry taxonomy shared by code-navigation and package-intelligence
-* services. Single source of truth for:
-*
-* - `PkgseerRegistry` — the uppercase backend enum (what GraphQL expects).
-* - `PkgseerRegistryArg` — the lowercase surface value (CLI + MCP input).
-* - Lowercase ↔ uppercase conversion.
-*
-* Back-compat: `src/shared/code-navigation.ts` re-exports these under
-* the existing `CodeNavigationRegistry*` names.
-*/
-type PkgseerRegistry = "NPM" | "PYPI" | "HEX" | "CRATES" | "NUGET" | "MAVEN" | "ZIG" | "VCPKG" | "PACKAGIST" | "RUBYGEMS" | "GO" | "SWIFT";
+declare const registryMap: {
+	readonly npm: "NPM";
+	readonly pypi: "PYPI";
+	readonly hex: "HEX";
+	readonly crates: "CRATES";
+	readonly nuget: "NUGET";
+	readonly maven: "MAVEN";
+	readonly zig: "ZIG";
+	readonly vcpkg: "VCPKG";
+	readonly packagist: "PACKAGIST";
+	readonly rubygems: "RUBYGEMS";
+	readonly go: "GO";
+	readonly swift: "SWIFT";
+};
+type PkgseerRegistry = (typeof registryMap)[keyof typeof registryMap];
 /**
 * Back-compat alias — the canonical registry union now lives in
 * `src/shared/pkgseer-registry.ts`. Re-exported here so existing
@@ -98,13 +101,7 @@ type UnifiedSearchSource = "AUTO" | "DOCS" | "CODE" | "SYMBOL";
 type UnifiedSearchResultType = "DOCUMENTATION_PAGE" | "REPOSITORY_SYMBOL" | "REPOSITORY_CODE" | "REPOSITORY_DOC";
 type UnifiedSearchSessionStatus = "PENDING" | "INDEXING" | "SEARCHING" | "COMPLETED" | "TIMEOUT" | "FAILED";
 type CodeIndexState = "CURRENT" | "INDEXED" | "INDEXING" | "STALE" | "FAILED" | "MISSING" | string;
-/**
-* Coverage lifecycle for crawled documentation site data.
-*
-* `PARTIAL` is transient (a crawl is still running, so retrying later can
-* return more); `CAPPED` is terminal (a crawl limit stopped indexing, so
-* retrying will not help). Both mean served evidence may be incomplete.
-*/
+/** Coverage state of the selected published documentation corpus. */
 type DocCoverageState = "NONE" | "PARTIAL" | "CAPPED" | "COMPLETE" | string;
 /**
 * Coverage metadata for crawled documentation site data. Present on docs
@@ -114,10 +111,10 @@ interface DocCoverage {
 	coverageState: DocCoverageState;
 	coverageReason?: string;
 	pagesCrawled?: number;
-	frontierRemaining?: number;
+	frontierRemaining?: number | null;
 	artifactOverflowPageCount?: number;
 	estimatedTotalPages?: number;
-	/** Backend-owned note suitable for CLI/MCP rendering. Preferred over client wording. */
+	/** Backend-owned coverage note retained for structured callers. */
 	note?: string;
 }
 type DiscoveryRequestedRefKind = "OMITTED_VERSION" | "LATEST_VERSION" | "EXACT_VERSION" | "DEFAULT_BRANCH" | "HEAD" | "BRANCH" | "SHA";
@@ -198,8 +195,26 @@ interface UnifiedSearchSourceStatus {
 	appliedQueryFeatures: string[];
 	ignoredQueryFeatures: string[];
 	incompatibleQueryFeatures: string[];
+	suggestedSiteTargets: string[];
+	suggestedSiteTargetsTruncated: boolean;
 	note?: string;
 	coverage?: DocCoverage;
+	contributors?: UnifiedSearchDocumentationContributor[];
+}
+type UnifiedSearchDocumentationContributorKind = "REPOSITORY_DOCS" | "DOCPACK";
+type UnifiedSearchDocumentationContributorState = "SEARCHED" | "READY" | "PENDING" | "UNAVAILABLE";
+type UnifiedSearchDocumentationFreshness = "CURRENT" | "STALE";
+/** One physical documentation corpus disclosed for a DOCS source row. */
+interface UnifiedSearchDocumentationContributor {
+	kind: UnifiedSearchDocumentationContributorKind;
+	state: UnifiedSearchDocumentationContributorState;
+	freshness?: UnifiedSearchDocumentationFreshness;
+	resultCount: number;
+	repositoryUrl?: string;
+	commitSha?: string;
+	siteKey?: string;
+	siteUrl?: string;
+	coverage?: DocCoverage;
 }
 interface UnifiedSearchProgressTarget {
 	requested?: string;
@@ -230,6 +245,7 @@ interface UnifiedSearchResult {
 	page: UnifiedSearchPageInfo;
 	partialResults: boolean;
 	sourceStatus: UnifiedSearchSourceStatus[];
+	evidenceNotice?: string;
 }
 interface UnifiedSearchProgress {
 	searchRef: string;
@@ -1128,7 +1144,11 @@ interface McpServerMetadata {
 interface McpRequestContext<TExtra = unknown> {
 	extra: TExtra | undefined;
 }
-type McpToolServicesProvider<TExtra = unknown> = McpToolServices | ((context: McpRequestContext<TExtra>) => McpToolServices | Promise<McpToolServices>);
+type McpToolServicesProviderFor<
+	TServices extends McpToolServices,
+	TExtra = unknown
+> = TServices | ((context: McpRequestContext<TExtra>) => TServices | Promise<TServices>);
+type McpToolServicesProvider<TExtra = unknown> = McpToolServicesProviderFor<McpToolServices, TExtra>;
 /** Wraps one public MCP tool call without receiving arguments or auth data. */
 type McpToolExecutionHook = (toolName: string, runHandler: () => Promise<ToolResult>) => ToolResult | Promise<ToolResult>;
 interface CreateMcpServerOptions<TExtra = unknown> {