@githits/mcp 0.40.2 → 0.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/client.d.ts CHANGED
@@ -27,6 +27,37 @@ interface CreateClientHeaderBuilderOptions {
27
27
  * relying on module-level CLI state.
28
28
  */
29
29
  declare function createClientHeaderBuilder(options: CreateClientHeaderBuilderOptions): ClientHeaderBuilder;
30
+ /**
31
+ * Host-supplied diagnostics for transport-neutral service clients.
32
+ *
33
+ * Implementations may record operation timings or debug events in whatever
34
+ * way is appropriate for their host. Core does not provide a default and
35
+ * remains silent when diagnostics are omitted. Core callers gate every debug
36
+ * event through `isEnabled(area)`; when it returns `false`, the corresponding
37
+ * debug call is suppressed entirely. Returning `true` is therefore both a log
38
+ * filter and a content-disclosure decision for the host.
39
+ *
40
+ * In particular, the `code-nav-wire` area may carry the exact GraphQL document
41
+ * and request variables, including caller query text, so it requires separate
42
+ * explicit opt-in. The `code-nav` and `pkg-graphql` schema-mismatch paths may
43
+ * carry raw backend error text, and an enabled area may select that raw error
44
+ * content instead of the sanitized message. These areas are not PII-safe;
45
+ * hosts own their privacy and retention policy for any enabled diagnostics.
46
+ */
47
+ interface ServiceDiagnostics {
48
+ withOperation<T>(name: string, operation: () => Promise<T>): Promise<T>;
49
+ isEnabled(area: string): boolean;
50
+ debug(area: string, event: Record<string, unknown>): void;
51
+ }
52
+ /** Allowlisted provider facts shared by service errors and transport envelopes. */
53
+ interface PkgseerErrorDetails {
54
+ rateLimitScope?: "repository_provider" | "app_admission" | "operation" | "registry";
55
+ tokenSource?: "app" | "user" | "supabase_user";
56
+ retryAfterMs?: number;
57
+ retryAfterSeconds?: number;
58
+ repoUrl?: string;
59
+ gitRef?: string | null;
60
+ }
30
61
  interface OsvCredit {
31
62
  name: string;
32
63
  contact: string[];
@@ -65,7 +96,7 @@ interface VulnerabilitySourceEntry {
65
96
  /** Exact representative ID from one original backend row, before assessment dedup. */
66
97
  advisoryId: string | null;
67
98
  source: OsvSourceDetails | null;
68
- error?: {
99
+ error?: PkgseerErrorDetails & {
69
100
  code: string;
70
101
  message: string;
71
102
  retryable: boolean;
@@ -73,28 +104,6 @@ interface VulnerabilitySourceEntry {
73
104
  };
74
105
  }
75
106
  /**
76
- * Host-supplied diagnostics for transport-neutral service clients.
77
- *
78
- * Implementations may record operation timings or debug events in whatever
79
- * way is appropriate for their host. Core does not provide a default and
80
- * remains silent when diagnostics are omitted. Core callers gate every debug
81
- * event through `isEnabled(area)`; when it returns `false`, the corresponding
82
- * debug call is suppressed entirely. Returning `true` is therefore both a log
83
- * filter and a content-disclosure decision for the host.
84
- *
85
- * In particular, the `code-nav-wire` area may carry the exact GraphQL document
86
- * and request variables, including caller query text, so it requires separate
87
- * explicit opt-in. The `code-nav` and `pkg-graphql` schema-mismatch paths may
88
- * carry raw backend error text, and an enabled area may select that raw error
89
- * content instead of the sanitized message. These areas are not PII-safe;
90
- * hosts own their privacy and retention policy for any enabled diagnostics.
91
- */
92
- interface ServiceDiagnostics {
93
- withOperation<T>(name: string, operation: () => Promise<T>): Promise<T>;
94
- isEnabled(area: string): boolean;
95
- debug(area: string, event: Record<string, unknown>): void;
96
- }
97
- /**
98
107
  * Optional per-call controls shared by network-backed service methods.
99
108
  *
100
109
  * `signal` is the caller's cancellation signal, such as an MCP request
@@ -838,7 +847,7 @@ interface CodeDiffErrorRef {
838
847
  * arbitrary extension values here: this object is safe to pass to public
839
848
  * error envelopes and telemetry.
840
849
  */
841
- interface CodeDiffErrorDetails {
850
+ interface CodeDiffErrorDetails extends PkgseerErrorDetails {
842
851
  code?: string;
843
852
  retryable?: boolean;
844
853
  side?: string;
@@ -850,7 +859,7 @@ interface CodeDiffErrorDetails {
850
859
  stage?: string;
851
860
  limitKind?: string;
852
861
  repoUrl?: string;
853
- gitRef?: string;
862
+ gitRef?: string | null;
854
863
  availableRefs?: CodeDiffErrorRef[];
855
864
  suggestedRefs?: CodeDiffErrorRef[];
856
865
  refKinds?: string[];
@@ -1178,6 +1187,12 @@ interface GrepTargetStatus {
1178
1187
  urlPrefixes?: string[];
1179
1188
  }
1180
1189
  interface GrepUnavailableTarget {
1190
+ /** Backend diagnostic; display only, never a retry/readiness classifier. */
1191
+ message?: string | null;
1192
+ requestedVersion?: string | null;
1193
+ suggestedRefs?: RecoveryRef[] | null;
1194
+ availableRefs?: RecoveryRef[] | null;
1195
+ availableVersions?: RecoveryRef[] | null;
1181
1196
  inputIndex: number;
1182
1197
  target: string;
1183
1198
  reason: string;
@@ -1235,7 +1250,8 @@ declare class GrepBackendError extends Error {
1235
1250
  readonly status?: number | undefined;
1236
1251
  readonly graphqlCode?: string | undefined;
1237
1252
  readonly retryable?: boolean | undefined;
1238
- constructor(message: string, status?: number | undefined, graphqlCode?: string | undefined, retryable?: boolean | undefined);
1253
+ readonly metadata: PkgseerErrorDetails | undefined;
1254
+ constructor(message: string, status?: number | undefined, graphqlCode?: string | undefined, retryable?: boolean | undefined, metadata?: PkgseerErrorDetails | undefined);
1239
1255
  }
1240
1256
  declare class GrepAccessError extends Error {
1241
1257
  constructor(message: string);
@@ -1270,6 +1286,7 @@ interface ListParams {
1270
1286
  after?: string;
1271
1287
  waitTimeoutMs?: number;
1272
1288
  includeDetailedFields: boolean;
1289
+ /** Select source provenance and empty-package guidance for annotated text. */
1273
1290
  includeTargetProvenance?: boolean;
1274
1291
  /** Select exact read actions for compact site text; detailed fields always include them. */
1275
1292
  includeReadActions?: boolean;
@@ -1354,6 +1371,8 @@ interface ListSitePreparation {
1354
1371
  awaited: ListSiteWait[];
1355
1372
  }
1356
1373
  interface ListResult {
1374
+ /** Backend-authored empty-package guidance; omitted for unannotated selections. */
1375
+ hint?: string | null;
1357
1376
  indexingEstimates?: DiscoveryIndexingEstimate[];
1358
1377
  inventoryKind: ListInventoryKind;
1359
1378
  requestedTarget: string;
@@ -1401,13 +1420,15 @@ declare class ListGraphQLError extends Error {
1401
1420
  readonly hint?: string | undefined;
1402
1421
  readonly indexingMetadata: ListIndexingErrorMetadata | undefined;
1403
1422
  readonly recovery: VersionRefRecovery | undefined;
1404
- constructor(message: string, code?: string | undefined, retryable?: boolean | undefined, repoUrl?: string | undefined, commitSha?: string | undefined, indexingRef?: string | undefined, hint?: string | undefined, indexingMetadata?: ListIndexingErrorMetadata | undefined, recovery?: VersionRefRecovery | undefined);
1423
+ readonly metadata: PkgseerErrorDetails | undefined;
1424
+ constructor(message: string, code?: string | undefined, retryable?: boolean | undefined, repoUrl?: string | undefined, commitSha?: string | undefined, indexingRef?: string | undefined, hint?: string | undefined, indexingMetadata?: ListIndexingErrorMetadata | undefined, recovery?: VersionRefRecovery | undefined, metadata?: PkgseerErrorDetails | undefined);
1405
1425
  }
1406
1426
  declare class ListBackendError extends Error {
1407
1427
  readonly status?: number | undefined;
1408
1428
  readonly graphqlCode?: string | undefined;
1409
1429
  readonly retryable?: boolean | undefined;
1410
- constructor(message: string, status?: number | undefined, graphqlCode?: string | undefined, retryable?: boolean | undefined);
1430
+ readonly metadata: PkgseerErrorDetails | undefined;
1431
+ constructor(message: string, status?: number | undefined, graphqlCode?: string | undefined, retryable?: boolean | undefined, metadata?: PkgseerErrorDetails | undefined);
1411
1432
  }
1412
1433
  declare class ListNetworkError extends Error {
1413
1434
  constructor(message: string, options?: {
@@ -1427,6 +1448,54 @@ declare class ListServiceImpl implements ListService {
1427
1448
  list(params: ListParams, options?: ServiceRequestOptions): Promise<ListResult>;
1428
1449
  private executeList;
1429
1450
  }
1451
+ type PackageLifecycleKind = "DEPRECATED" | "RETIRED" | "ABANDONED" | "DISCONTINUED" | "YANKED" | "PARTIALLY_YANKED" | "RETRACTED" | "UNLISTED" | (string & {});
1452
+ type PackageLifecycleScope = "PACKAGE" | "RELEASE" | "FILES" | (string & {});
1453
+ /** A native fact, not a vulnerability or a client-selected upgrade policy. */
1454
+ interface PackageLifecycleFinding {
1455
+ kind: PackageLifecycleKind;
1456
+ scope: PackageLifecycleScope;
1457
+ source: string;
1458
+ /** Authority release, which may differ from the affected/selected release. */
1459
+ sourceVersion?: string | null;
1460
+ /** Collection time, not a status-change time or freshness guarantee. */
1461
+ observedAt?: string | null;
1462
+ reason?: string | null;
1463
+ reasonCodes: string[];
1464
+ /** Publisher advice, not a resolved upgrade recommendation. */
1465
+ replacement?: string | null;
1466
+ }
1467
+ interface PackageLifecycleRetainedWarning {
1468
+ classification: "LEGACY_UNCLASSIFIED" | (string & {});
1469
+ reason: string;
1470
+ }
1471
+ /** Native findings and publisher/source evidence for the selected release. */
1472
+ interface PackageLifecycle {
1473
+ findings: PackageLifecycleFinding[];
1474
+ retainedWarnings: PackageLifecycleRetainedWarning[];
1475
+ contentSafety: {
1476
+ filtered: boolean;
1477
+ };
1478
+ }
1479
+ /** Discovery evidence belongs to its finding; it never grants package scope. */
1480
+ interface VulnerabilityEvidence {
1481
+ kind: string;
1482
+ relationship: string;
1483
+ sourceId: string;
1484
+ assessmentStatus: string;
1485
+ complete: boolean;
1486
+ reasons: string[];
1487
+ affectedEntryIndices: number[] | null;
1488
+ repositoryUrl: string | null;
1489
+ commitSha: string | null;
1490
+ proofKind: string | null;
1491
+ sourceModifiedNs: string | null;
1492
+ contentDigest: string | null;
1493
+ assessedContentDigest: string | null;
1494
+ evaluatedAt: string | null;
1495
+ checkedAt: string | null;
1496
+ sourceStale: boolean | null;
1497
+ withdrawnAt: string | null;
1498
+ }
1430
1499
  interface PackageSummaryParams {
1431
1500
  registry: PkgseerRegistry;
1432
1501
  packageName: string;
@@ -1465,6 +1534,16 @@ interface PackageIdentity {
1465
1534
  downloadsRefreshedAt?: string;
1466
1535
  githubRepository?: GithubRepository;
1467
1536
  registryRepository?: RegistryRepository;
1537
+ /** Explicit temporary failure of optional repository popularity metadata. */
1538
+ githubRepositoryError?: PackageSummaryMetadataError;
1539
+ /** Explicit temporary failure of optional selected-release provenance and lifecycle. */
1540
+ registryRepositoryError?: PackageSummaryMetadataError;
1541
+ }
1542
+ /** A nullable summary metadata failure; independently readable facts remain valid. */
1543
+ interface PackageSummaryMetadataError extends PkgseerErrorDetails {
1544
+ code: "RATE_LIMITED";
1545
+ message: string;
1546
+ retryable: boolean;
1468
1547
  }
1469
1548
  interface GithubRepository {
1470
1549
  stargazersCount?: number;
@@ -1494,12 +1573,16 @@ interface ChangelogEntry {
1494
1573
  }
1495
1574
  interface PackageSummary {
1496
1575
  package: PackageIdentity;
1576
+ /** Absent when the optional selected-release assessment is unavailable. */
1577
+ lifecycle?: PackageLifecycle;
1497
1578
  security?: PackageSecurityOverview;
1498
1579
  latestChangelogs?: ChangelogEntry[];
1499
1580
  }
1500
1581
  interface PackageVulnerabilitiesParams {
1501
1582
  /** Opt in to full current OSV explanations on bounded direct advisory pages. */
1502
1583
  includeSourceDetails?: boolean;
1584
+ /** Expanded per-finding provenance, consumed by verbose text or JSON. */
1585
+ includeVulnerabilityEvidence?: boolean;
1503
1586
  registry: PkgseerRegistry;
1504
1587
  packageName: string;
1505
1588
  /** Optional — backend defaults to latest when omitted. */
@@ -1526,6 +1609,9 @@ interface PackageVersionIdentity {
1526
1609
  registryRepository?: RegistryRepository;
1527
1610
  }
1528
1611
  interface VulnerabilityDetail {
1612
+ relationship?: "PACKAGE" | "RELATED";
1613
+ assessmentComplete?: boolean;
1614
+ evidence?: VulnerabilityEvidence[];
1529
1615
  osvId?: string;
1530
1616
  summary?: string;
1531
1617
  severityScore?: number;
@@ -1546,6 +1632,8 @@ interface VulnerabilityDetail {
1546
1632
  duplicateIds?: string[];
1547
1633
  }
1548
1634
  interface VulnerabilitySecurityDetails {
1635
+ assessmentComplete?: boolean;
1636
+ assessmentReasons?: string[];
1549
1637
  unknownVulnerabilityCount?: number;
1550
1638
  assessmentStatus?: string;
1551
1639
  affectedVulnerabilityCount: number;
@@ -1556,8 +1644,16 @@ interface VulnerabilitySecurityDetails {
1556
1644
  upgradePaths?: string[];
1557
1645
  }
1558
1646
  interface VulnerabilityReport {
1647
+ paginationComplete?: false;
1648
+ related?: {
1649
+ totalCount: number;
1650
+ vulnerabilities: VulnerabilityDetail[];
1651
+ sourceDetails?: VulnerabilitySourceEntry[];
1652
+ };
1559
1653
  sourceDetails?: VulnerabilitySourceEntry[];
1560
- package: PackageVersionIdentity;
1654
+ package: Omit<PackageVersionIdentity, "version"> & {
1655
+ version: string | null;
1656
+ };
1561
1657
  security?: VulnerabilitySecurityDetails;
1562
1658
  transitive?: TransitiveVulnerabilityAudit;
1563
1659
  }
@@ -1705,7 +1801,6 @@ interface PackageUpgradeChangelogEntry {
1705
1801
  body?: string;
1706
1802
  bodyPreview?: string;
1707
1803
  headline?: string;
1708
- signals: string[];
1709
1804
  }
1710
1805
  interface ChangelogRiskCoverage {
1711
1806
  versionsClassified: number;
@@ -1728,14 +1823,10 @@ interface PackageUpgradeChangelog {
1728
1823
  fallback?: string;
1729
1824
  entries?: PackageUpgradeChangelogEntry[];
1730
1825
  sampledEntries?: PackageUpgradeChangelogEntry[];
1731
- keywordEntries?: PackageUpgradeChangelogEntry[];
1732
- totalKeywordEntries: number;
1733
1826
  totalEntries: number;
1734
1827
  totalEntriesWithBodies: number;
1735
1828
  truncated: boolean;
1736
1829
  hasReleaseNoteBodies: boolean;
1737
- breakingSignals: string[];
1738
- migrationSignals: string[];
1739
1830
  }
1740
1831
  interface PackageUpgradeCompatibility {
1741
1832
  peerDependencyChanges: string[];
@@ -1799,7 +1890,6 @@ interface PackageUpgradeReviewResponse {
1799
1890
  total: number;
1800
1891
  withUnknowns: number;
1801
1892
  withAddedAdvisories: number;
1802
- withBreakingSignals: number;
1803
1893
  withDirectDependencyChanges: number;
1804
1894
  withTransitiveVulnerabilityAdditions: number;
1805
1895
  };
@@ -2254,8 +2344,6 @@ declare class PackageIntelligenceServiceImpl implements PackageIntelligenceServi
2254
2344
  private normalise;
2255
2345
  packageVulnerabilities(params: PackageVulnerabilitiesParams, options?: ServiceRequestOptions): Promise<VulnerabilityReport>;
2256
2346
  private executePackageVulnerabilities;
2257
- private fetchPackageVulnerabilitiesPage;
2258
- private normaliseVulnerabilityReport;
2259
2347
  private fetchTransitiveVulnerabilityAudit;
2260
2348
  private normaliseTransitiveVulnerabilityAudit;
2261
2349
  packageDependencies(params: PackageDependenciesParams, options?: ServiceRequestOptions): Promise<DependencyReport>;
@@ -2466,4 +2554,4 @@ declare class ProviderReauthenticationRequiredError extends Error {
2466
2554
  readonly reauthUrl: string | undefined;
2467
2555
  constructor(reauthUrl?: string);
2468
2556
  }
2469
- export { AGENTIC_ASK_REQUEST_TIMEOUT_MS, AgentInfo, AgenticAskRateLimitScope, AgenticAskRequest, AgenticAskRequestOptions, AgenticAskResponse, AgenticAskService, AgenticAskServiceImpl, AgenticAskServiceRuntimeOptions, CodeDiffError, CodeDiffErrorDetails, CodeDiffErrorRef, CodeDiffMode, CodeDiffOptions, CodeDiffPackageInfo, CodeDiffPackageTarget, CodeDiffParams, CodeDiffPartialResult, CodeDiffRefKind, CodeDiffRefResolution, CodeDiffRepositoryTarget, CodeDiffResult, CodeDiffService, CodeDiffTarget, CodeDiffVersionSource, CodeNavigationService, CodeNavigationServiceImpl, CodeSymbolCandidate, CodeSymbolResolution, CodeSymbolSuggestion, ContentModification, ContentSafety, DEFAULT_API_URL, DEFAULT_CODE_NAV_URL, DEFAULT_MCP_URL, DiscoveryIndexingEstimate, GitHitsService, GitHitsServiceImpl, GrepAccessError, GrepBackendError, GrepContentSafety, GrepCorpus, GrepFileIssue, GrepGraphQLError, GrepHit, GrepInputTargetResolution, GrepLineSlice, GrepNetworkError, GrepParams, GrepPathSelector, GrepPathSuggestion, GrepPathWarning, GrepReadAction, GrepReadiness, GrepRepositoryHit, GrepResult, GrepService, GrepServiceImpl, GrepSiteHit, GrepTarget, GrepTargetStatus, GrepTraversal, GrepUnavailableTarget, IndexingDurationEstimate, KnownLatestVersionMaliciousStatus, KnownMaliciousAdvisoryClassificationReason, LatestVersionMaliciousStatus, ListAccessError, ListAction, ListAvailableVersion, ListBackendError, ListBrowseAction, ListEntry, ListEntryKind, ListFileIntent, ListGraphQLError, ListIndexingEstimate, ListInventoryKind, ListNetworkError, ListParams, ListReadAction, ListResolution, ListResult, ListService, ListServiceImpl, ListSiteJob, ListSitePreparation, ListSiteWait, ListSiteWaitOutcome, ListTargetIdentity, ListTargetResolution, MalformedGrepResponseError, MalformedListResponseError, MaliciousAdvisoryClassificationReason, PKGSEER_REGISTRY_LIST, PackageIntelligenceService, PackageIntelligenceServiceImpl, ProviderReauthenticationRequiredError, RawCodeDiff, RawCodeDiffContentCoverage, RawCodeDiffContentFailure, RawCodeDiffFile, RawCodeDiffFileContentStatus, RawCodeDiffFileStatus, RawCodeDiffPathEncoding, RawCodeDiffScope, RawCodeDiffScopeStatus, RawCodeDiffSummary, ReadCodeResult, ReadDocsResult, ReadParams, ReadResult, ReadService, ReadServiceImpl, ReadSymbolResolutionResult, ReadTarget, RefreshingGitHitsService, RegistryRepository, ResolveTargetKind, ResolveTargetLatestVersionMaliciousAdvisory, ResolveTargetLatestVersionMaliciousEvidence, ResolveTargetMatch, ResolveTargetParams, ResolveTargetReference, ResolveTargetResult, ResolveTargetService, ResolveTargetServiceImpl, ResolveTargetTarget, ServiceDiagnostics, ServiceRequestOptions, SessionIdConfigError, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getEnvSessionId, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
2557
+ export { AGENTIC_ASK_REQUEST_TIMEOUT_MS, AgentInfo, AgenticAskRateLimitScope, AgenticAskRequest, AgenticAskRequestOptions, AgenticAskResponse, AgenticAskService, AgenticAskServiceImpl, AgenticAskServiceRuntimeOptions, CodeDiffError, CodeDiffErrorDetails, CodeDiffErrorRef, CodeDiffMode, CodeDiffOptions, CodeDiffPackageInfo, CodeDiffPackageTarget, CodeDiffParams, CodeDiffPartialResult, CodeDiffRefKind, CodeDiffRefResolution, CodeDiffRepositoryTarget, CodeDiffResult, CodeDiffService, CodeDiffTarget, CodeDiffVersionSource, CodeNavigationService, CodeNavigationServiceImpl, CodeSymbolCandidate, CodeSymbolResolution, CodeSymbolSuggestion, ContentModification, ContentSafety, DEFAULT_API_URL, DEFAULT_CODE_NAV_URL, DEFAULT_MCP_URL, DiscoveryIndexingEstimate, GitHitsService, GitHitsServiceImpl, GrepAccessError, GrepBackendError, GrepContentSafety, GrepCorpus, GrepFileIssue, GrepGraphQLError, GrepHit, GrepInputTargetResolution, GrepLineSlice, GrepNetworkError, GrepParams, GrepPathSelector, GrepPathSuggestion, GrepPathWarning, GrepReadAction, GrepReadiness, GrepRepositoryHit, GrepResult, GrepService, GrepServiceImpl, GrepSiteHit, GrepTarget, GrepTargetStatus, GrepTraversal, GrepUnavailableTarget, IndexingDurationEstimate, KnownLatestVersionMaliciousStatus, KnownMaliciousAdvisoryClassificationReason, LatestVersionMaliciousStatus, ListAccessError, ListAction, ListAvailableVersion, ListBackendError, ListBrowseAction, ListEntry, ListEntryKind, ListFileIntent, ListGraphQLError, ListIndexingEstimate, ListInventoryKind, ListNetworkError, ListParams, ListReadAction, ListResolution, ListResult, ListService, ListServiceImpl, ListSiteJob, ListSitePreparation, ListSiteWait, ListSiteWaitOutcome, ListTargetIdentity, ListTargetResolution, MalformedGrepResponseError, MalformedListResponseError, MaliciousAdvisoryClassificationReason, PKGSEER_REGISTRY_LIST, PackageIntelligenceService, PackageIntelligenceServiceImpl, PackageLifecycle, PackageLifecycleFinding, PackageLifecycleKind, PackageLifecycleRetainedWarning, PackageLifecycleScope, ProviderReauthenticationRequiredError, RawCodeDiff, RawCodeDiffContentCoverage, RawCodeDiffContentFailure, RawCodeDiffFile, RawCodeDiffFileContentStatus, RawCodeDiffFileStatus, RawCodeDiffPathEncoding, RawCodeDiffScope, RawCodeDiffScopeStatus, RawCodeDiffSummary, ReadCodeResult, ReadDocsResult, ReadParams, ReadResult, ReadService, ReadServiceImpl, ReadSymbolResolutionResult, ReadTarget, RefreshingGitHitsService, RegistryRepository, ResolveTargetKind, ResolveTargetLatestVersionMaliciousAdvisory, ResolveTargetLatestVersionMaliciousEvidence, ResolveTargetMatch, ResolveTargetParams, ResolveTargetReference, ResolveTargetResult, ResolveTargetService, ResolveTargetServiceImpl, ResolveTargetTarget, ServiceDiagnostics, ServiceRequestOptions, SessionIdConfigError, TokenProvider, VulnerabilityEvidence, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getEnvSessionId, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
package/dist/client.js CHANGED
@@ -1 +1 @@
1
- import{GrepGraphQLError2,GrepBackendError2,GrepAccessError2,GrepNetworkError2,MalformedGrepResponseError2,GrepServiceImpl2,ListAccessError2,ListGraphQLError2,ListBackendError2,ListNetworkError2,MalformedListResponseError2,ListServiceImpl2,ReadServiceImpl2,RefreshingGitHitsService2,ResolveTargetServiceImpl2,createStaticTokenProvider2,SessionIdConfigError2,getEnvSessionId2,createClientHeaderBuilder2}from"./shared/chunk-nfpnv59a.js";import{ProviderReauthenticationRequiredError2,DEFAULT_MCP_URL2,DEFAULT_API_URL2,DEFAULT_CODE_NAV_URL2,getMcpUrl2,getApiUrl2,getCodeNavigationUrl2,getEnvApiToken2,GitHitsServiceImpl2,AGENTIC_ASK_REQUEST_TIMEOUT_MS2,AgenticAskServiceImpl2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,CodeDiffError2,CodeNavigationServiceImpl2,PackageIntelligenceServiceImpl2}from"./shared/chunk-bzjgrtan.js";export{AGENTIC_ASK_REQUEST_TIMEOUT_MS2 as AGENTIC_ASK_REQUEST_TIMEOUT_MS,AgenticAskServiceImpl2 as AgenticAskServiceImpl,CodeDiffError2 as CodeDiffError,CodeNavigationServiceImpl2 as CodeNavigationServiceImpl,DEFAULT_API_URL2 as DEFAULT_API_URL,DEFAULT_CODE_NAV_URL2 as DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL2 as DEFAULT_MCP_URL,GitHitsServiceImpl2 as GitHitsServiceImpl,GrepAccessError2 as GrepAccessError,GrepBackendError2 as GrepBackendError,GrepGraphQLError2 as GrepGraphQLError,GrepNetworkError2 as GrepNetworkError,GrepServiceImpl2 as GrepServiceImpl,ListAccessError2 as ListAccessError,ListBackendError2 as ListBackendError,ListGraphQLError2 as ListGraphQLError,ListNetworkError2 as ListNetworkError,ListServiceImpl2 as ListServiceImpl,MalformedGrepResponseError2 as MalformedGrepResponseError,MalformedListResponseError2 as MalformedListResponseError,PKGSEER_REGISTRY_LIST2 as PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl2 as PackageIntelligenceServiceImpl,ProviderReauthenticationRequiredError2 as ProviderReauthenticationRequiredError,ReadServiceImpl2 as ReadServiceImpl,RefreshingGitHitsService2 as RefreshingGitHitsService,ResolveTargetServiceImpl2 as ResolveTargetServiceImpl,SessionIdConfigError2 as SessionIdConfigError,createClientHeaderBuilder2 as createClientHeaderBuilder,createStaticTokenProvider2 as createStaticTokenProvider,getApiUrl2 as getApiUrl,getCodeNavigationUrl2 as getCodeNavigationUrl,getEnvApiToken2 as getEnvApiToken,getEnvSessionId2 as getEnvSessionId,getMcpUrl2 as getMcpUrl,toPkgseerRegistry2 as toPkgseerRegistry,toPkgseerRegistryLowercase2 as toPkgseerRegistryLowercase};
1
+ import{GrepGraphQLError2,GrepBackendError2,GrepAccessError2,GrepNetworkError2,MalformedGrepResponseError2,GrepServiceImpl2,ListAccessError2,ListGraphQLError2,ListBackendError2,ListNetworkError2,MalformedListResponseError2,ListServiceImpl2,ReadServiceImpl2,RefreshingGitHitsService2,ResolveTargetServiceImpl2,createStaticTokenProvider2,SessionIdConfigError2,getEnvSessionId2,createClientHeaderBuilder2}from"./shared/chunk-2xmk0srn.js";import{ProviderReauthenticationRequiredError2,DEFAULT_MCP_URL2,DEFAULT_API_URL2,DEFAULT_CODE_NAV_URL2,getMcpUrl2,getApiUrl2,getCodeNavigationUrl2,getEnvApiToken2,GitHitsServiceImpl2,AGENTIC_ASK_REQUEST_TIMEOUT_MS2,AgenticAskServiceImpl2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,CodeDiffError2,CodeNavigationServiceImpl2,PackageIntelligenceServiceImpl2}from"./shared/chunk-39naxvkd.js";export{AGENTIC_ASK_REQUEST_TIMEOUT_MS2 as AGENTIC_ASK_REQUEST_TIMEOUT_MS,AgenticAskServiceImpl2 as AgenticAskServiceImpl,CodeDiffError2 as CodeDiffError,CodeNavigationServiceImpl2 as CodeNavigationServiceImpl,DEFAULT_API_URL2 as DEFAULT_API_URL,DEFAULT_CODE_NAV_URL2 as DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL2 as DEFAULT_MCP_URL,GitHitsServiceImpl2 as GitHitsServiceImpl,GrepAccessError2 as GrepAccessError,GrepBackendError2 as GrepBackendError,GrepGraphQLError2 as GrepGraphQLError,GrepNetworkError2 as GrepNetworkError,GrepServiceImpl2 as GrepServiceImpl,ListAccessError2 as ListAccessError,ListBackendError2 as ListBackendError,ListGraphQLError2 as ListGraphQLError,ListNetworkError2 as ListNetworkError,ListServiceImpl2 as ListServiceImpl,MalformedGrepResponseError2 as MalformedGrepResponseError,MalformedListResponseError2 as MalformedListResponseError,PKGSEER_REGISTRY_LIST2 as PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl2 as PackageIntelligenceServiceImpl,ProviderReauthenticationRequiredError2 as ProviderReauthenticationRequiredError,ReadServiceImpl2 as ReadServiceImpl,RefreshingGitHitsService2 as RefreshingGitHitsService,ResolveTargetServiceImpl2 as ResolveTargetServiceImpl,SessionIdConfigError2 as SessionIdConfigError,createClientHeaderBuilder2 as createClientHeaderBuilder,createStaticTokenProvider2 as createStaticTokenProvider,getApiUrl2 as getApiUrl,getCodeNavigationUrl2 as getCodeNavigationUrl,getEnvApiToken2 as getEnvApiToken,getEnvSessionId2 as getEnvSessionId,getMcpUrl2 as getMcpUrl,toPkgseerRegistry2 as toPkgseerRegistry,toPkgseerRegistryLowercase2 as toPkgseerRegistryLowercase};
package/dist/index.d.ts CHANGED
@@ -19,6 +19,15 @@ declare function buildMcpQuickStart(options?: BuildMcpQuickStartOptions): string
19
19
  */
20
20
  declare function buildMcpInstructions(options?: BuildMcpInstructionsOptions): string;
21
21
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
22
+ /** Allowlisted provider facts shared by service errors and transport envelopes. */
23
+ interface PkgseerErrorDetails {
24
+ rateLimitScope?: "repository_provider" | "app_admission" | "operation" | "registry";
25
+ tokenSource?: "app" | "user" | "supabase_user";
26
+ retryAfterMs?: number;
27
+ retryAfterSeconds?: number;
28
+ repoUrl?: string;
29
+ gitRef?: string | null;
30
+ }
22
31
  interface OsvCredit {
23
32
  name: string;
24
33
  contact: string[];
@@ -57,7 +66,7 @@ interface VulnerabilitySourceEntry {
57
66
  /** Exact representative ID from one original backend row, before assessment dedup. */
58
67
  advisoryId: string | null;
59
68
  source: OsvSourceDetails | null;
60
- error?: {
69
+ error?: PkgseerErrorDetails & {
61
70
  code: string;
62
71
  message: string;
63
72
  retryable: boolean;
@@ -157,6 +166,11 @@ interface ReadTarget {
157
166
  startLine?: number;
158
167
  endLine?: number;
159
168
  }
169
+ /** Nullable registry-version association carried by public error inventories. */
170
+ interface RecoveryRef {
171
+ ref: string;
172
+ version?: string | null;
173
+ }
160
174
  /**
161
175
  * Back-compat alias — the canonical registry union now lives in
162
176
  * `src/shared/pkgseer-registry.ts`. Re-exported here so existing
@@ -933,6 +947,12 @@ interface GrepTargetStatus {
933
947
  urlPrefixes?: string[];
934
948
  }
935
949
  interface GrepUnavailableTarget {
950
+ /** Backend diagnostic; display only, never a retry/readiness classifier. */
951
+ message?: string | null;
952
+ requestedVersion?: string | null;
953
+ suggestedRefs?: RecoveryRef[] | null;
954
+ availableRefs?: RecoveryRef[] | null;
955
+ availableVersions?: RecoveryRef[] | null;
936
956
  inputIndex: number;
937
957
  target: string;
938
958
  reason: string;
@@ -987,6 +1007,7 @@ interface ListParams {
987
1007
  after?: string;
988
1008
  waitTimeoutMs?: number;
989
1009
  includeDetailedFields: boolean;
1010
+ /** Select source provenance and empty-package guidance for annotated text. */
990
1011
  includeTargetProvenance?: boolean;
991
1012
  /** Select exact read actions for compact site text; detailed fields always include them. */
992
1013
  includeReadActions?: boolean;
@@ -1070,6 +1091,8 @@ interface ListSitePreparation {
1070
1091
  awaited: ListSiteWait[];
1071
1092
  }
1072
1093
  interface ListResult {
1094
+ /** Backend-authored empty-package guidance; omitted for unannotated selections. */
1095
+ hint?: string | null;
1073
1096
  indexingEstimates?: DiscoveryIndexingEstimate[];
1074
1097
  inventoryKind: ListInventoryKind;
1075
1098
  requestedTarget: string;
@@ -1094,6 +1117,54 @@ interface ListResult {
1094
1117
  interface ListService {
1095
1118
  list(params: ListParams, options?: ServiceRequestOptions): Promise<ListResult>;
1096
1119
  }
1120
+ type PackageLifecycleKind = "DEPRECATED" | "RETIRED" | "ABANDONED" | "DISCONTINUED" | "YANKED" | "PARTIALLY_YANKED" | "RETRACTED" | "UNLISTED" | (string & {});
1121
+ type PackageLifecycleScope = "PACKAGE" | "RELEASE" | "FILES" | (string & {});
1122
+ /** A native fact, not a vulnerability or a client-selected upgrade policy. */
1123
+ interface PackageLifecycleFinding {
1124
+ kind: PackageLifecycleKind;
1125
+ scope: PackageLifecycleScope;
1126
+ source: string;
1127
+ /** Authority release, which may differ from the affected/selected release. */
1128
+ sourceVersion?: string | null;
1129
+ /** Collection time, not a status-change time or freshness guarantee. */
1130
+ observedAt?: string | null;
1131
+ reason?: string | null;
1132
+ reasonCodes: string[];
1133
+ /** Publisher advice, not a resolved upgrade recommendation. */
1134
+ replacement?: string | null;
1135
+ }
1136
+ interface PackageLifecycleRetainedWarning {
1137
+ classification: "LEGACY_UNCLASSIFIED" | (string & {});
1138
+ reason: string;
1139
+ }
1140
+ /** Native findings and publisher/source evidence for the selected release. */
1141
+ interface PackageLifecycle {
1142
+ findings: PackageLifecycleFinding[];
1143
+ retainedWarnings: PackageLifecycleRetainedWarning[];
1144
+ contentSafety: {
1145
+ filtered: boolean;
1146
+ };
1147
+ }
1148
+ /** Discovery evidence belongs to its finding; it never grants package scope. */
1149
+ interface VulnerabilityEvidence {
1150
+ kind: string;
1151
+ relationship: string;
1152
+ sourceId: string;
1153
+ assessmentStatus: string;
1154
+ complete: boolean;
1155
+ reasons: string[];
1156
+ affectedEntryIndices: number[] | null;
1157
+ repositoryUrl: string | null;
1158
+ commitSha: string | null;
1159
+ proofKind: string | null;
1160
+ sourceModifiedNs: string | null;
1161
+ contentDigest: string | null;
1162
+ assessedContentDigest: string | null;
1163
+ evaluatedAt: string | null;
1164
+ checkedAt: string | null;
1165
+ sourceStale: boolean | null;
1166
+ withdrawnAt: string | null;
1167
+ }
1097
1168
  interface PackageSummaryParams {
1098
1169
  registry: PkgseerRegistry;
1099
1170
  packageName: string;
@@ -1132,6 +1203,16 @@ interface PackageIdentity {
1132
1203
  downloadsRefreshedAt?: string;
1133
1204
  githubRepository?: GithubRepository;
1134
1205
  registryRepository?: RegistryRepository;
1206
+ /** Explicit temporary failure of optional repository popularity metadata. */
1207
+ githubRepositoryError?: PackageSummaryMetadataError;
1208
+ /** Explicit temporary failure of optional selected-release provenance and lifecycle. */
1209
+ registryRepositoryError?: PackageSummaryMetadataError;
1210
+ }
1211
+ /** A nullable summary metadata failure; independently readable facts remain valid. */
1212
+ interface PackageSummaryMetadataError extends PkgseerErrorDetails {
1213
+ code: "RATE_LIMITED";
1214
+ message: string;
1215
+ retryable: boolean;
1135
1216
  }
1136
1217
  interface GithubRepository {
1137
1218
  stargazersCount?: number;
@@ -1161,12 +1242,16 @@ interface ChangelogEntry {
1161
1242
  }
1162
1243
  interface PackageSummary {
1163
1244
  package: PackageIdentity;
1245
+ /** Absent when the optional selected-release assessment is unavailable. */
1246
+ lifecycle?: PackageLifecycle;
1164
1247
  security?: PackageSecurityOverview;
1165
1248
  latestChangelogs?: ChangelogEntry[];
1166
1249
  }
1167
1250
  interface PackageVulnerabilitiesParams {
1168
1251
  /** Opt in to full current OSV explanations on bounded direct advisory pages. */
1169
1252
  includeSourceDetails?: boolean;
1253
+ /** Expanded per-finding provenance, consumed by verbose text or JSON. */
1254
+ includeVulnerabilityEvidence?: boolean;
1170
1255
  registry: PkgseerRegistry;
1171
1256
  packageName: string;
1172
1257
  /** Optional — backend defaults to latest when omitted. */
@@ -1193,6 +1278,9 @@ interface PackageVersionIdentity {
1193
1278
  registryRepository?: RegistryRepository;
1194
1279
  }
1195
1280
  interface VulnerabilityDetail {
1281
+ relationship?: "PACKAGE" | "RELATED";
1282
+ assessmentComplete?: boolean;
1283
+ evidence?: VulnerabilityEvidence[];
1196
1284
  osvId?: string;
1197
1285
  summary?: string;
1198
1286
  severityScore?: number;
@@ -1213,6 +1301,8 @@ interface VulnerabilityDetail {
1213
1301
  duplicateIds?: string[];
1214
1302
  }
1215
1303
  interface VulnerabilitySecurityDetails {
1304
+ assessmentComplete?: boolean;
1305
+ assessmentReasons?: string[];
1216
1306
  unknownVulnerabilityCount?: number;
1217
1307
  assessmentStatus?: string;
1218
1308
  affectedVulnerabilityCount: number;
@@ -1223,8 +1313,16 @@ interface VulnerabilitySecurityDetails {
1223
1313
  upgradePaths?: string[];
1224
1314
  }
1225
1315
  interface VulnerabilityReport {
1316
+ paginationComplete?: false;
1317
+ related?: {
1318
+ totalCount: number;
1319
+ vulnerabilities: VulnerabilityDetail[];
1320
+ sourceDetails?: VulnerabilitySourceEntry[];
1321
+ };
1226
1322
  sourceDetails?: VulnerabilitySourceEntry[];
1227
- package: PackageVersionIdentity;
1323
+ package: Omit<PackageVersionIdentity, "version"> & {
1324
+ version: string | null;
1325
+ };
1228
1326
  security?: VulnerabilitySecurityDetails;
1229
1327
  transitive?: TransitiveVulnerabilityAudit;
1230
1328
  }
@@ -1372,7 +1470,6 @@ interface PackageUpgradeChangelogEntry {
1372
1470
  body?: string;
1373
1471
  bodyPreview?: string;
1374
1472
  headline?: string;
1375
- signals: string[];
1376
1473
  }
1377
1474
  interface ChangelogRiskCoverage {
1378
1475
  versionsClassified: number;
@@ -1395,14 +1492,10 @@ interface PackageUpgradeChangelog {
1395
1492
  fallback?: string;
1396
1493
  entries?: PackageUpgradeChangelogEntry[];
1397
1494
  sampledEntries?: PackageUpgradeChangelogEntry[];
1398
- keywordEntries?: PackageUpgradeChangelogEntry[];
1399
- totalKeywordEntries: number;
1400
1495
  totalEntries: number;
1401
1496
  totalEntriesWithBodies: number;
1402
1497
  truncated: boolean;
1403
1498
  hasReleaseNoteBodies: boolean;
1404
- breakingSignals: string[];
1405
- migrationSignals: string[];
1406
1499
  }
1407
1500
  interface PackageUpgradeCompatibility {
1408
1501
  peerDependencyChanges: string[];
@@ -1466,7 +1559,6 @@ interface PackageUpgradeReviewResponse {
1466
1559
  total: number;
1467
1560
  withUnknowns: number;
1468
1561
  withAddedAdvisories: number;
1469
- withBreakingSignals: number;
1470
1562
  withDirectDependencyChanges: number;
1471
1563
  withTransitiveVulnerabilityAdditions: number;
1472
1564
  };
@@ -2168,7 +2260,7 @@ interface McpProgressAnimationOptions {
2168
2260
  }
2169
2261
  /** Backend stage covered by the opening message. */
2170
2262
  declare const OPENING_STAGE = "started";
2171
- import { z as z5 } from "zod";
2263
+ import { z as z6 } from "zod";
2172
2264
  /** Annotation fields required by OpenAI's MCP marketplace validation. */
2173
2265
  interface CompleteToolAnnotations {
2174
2266
  title?: string;
@@ -2221,7 +2313,7 @@ type ToolResult = {
2221
2313
  * Zod raw shape type (what MCP SDK expects)
2222
2314
  */
2223
2315
  type ZodRawShape = {
2224
- [k: string]: z5.ZodTypeAny;
2316
+ [k: string]: z6.ZodTypeAny;
2225
2317
  };
2226
2318
  /**
2227
2319
  * Services required to construct the MCP tool surface.