@githits/mcp 0.40.1 → 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
@@ -108,9 +117,13 @@ interface ServiceRequestOptions {
108
117
  interface TokenProvider {
109
118
  /** Get a valid token, refreshing proactively or reactively as needed. */
110
119
  getToken(): Promise<string | undefined>;
111
- /** Force a refresh, usually after an authentication failure. */
120
+ /**
121
+ * Force a refresh, usually after an authentication failure. Providers without
122
+ * a refresh flow return undefined without I/O so callers retain the original error.
123
+ */
112
124
  forceRefresh(): Promise<string | undefined>;
113
125
  }
126
+ /** Treat the token as opaque; refresh is a no-op with no I/O. */
114
127
  declare function createStaticTokenProvider(token: string): TokenProvider;
115
128
  /**
116
129
  * Optional per-call progress correlation for backend requests.
@@ -834,7 +847,7 @@ interface CodeDiffErrorRef {
834
847
  * arbitrary extension values here: this object is safe to pass to public
835
848
  * error envelopes and telemetry.
836
849
  */
837
- interface CodeDiffErrorDetails {
850
+ interface CodeDiffErrorDetails extends PkgseerErrorDetails {
838
851
  code?: string;
839
852
  retryable?: boolean;
840
853
  side?: string;
@@ -846,7 +859,7 @@ interface CodeDiffErrorDetails {
846
859
  stage?: string;
847
860
  limitKind?: string;
848
861
  repoUrl?: string;
849
- gitRef?: string;
862
+ gitRef?: string | null;
850
863
  availableRefs?: CodeDiffErrorRef[];
851
864
  suggestedRefs?: CodeDiffErrorRef[];
852
865
  refKinds?: string[];
@@ -1174,6 +1187,12 @@ interface GrepTargetStatus {
1174
1187
  urlPrefixes?: string[];
1175
1188
  }
1176
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;
1177
1196
  inputIndex: number;
1178
1197
  target: string;
1179
1198
  reason: string;
@@ -1231,7 +1250,8 @@ declare class GrepBackendError extends Error {
1231
1250
  readonly status?: number | undefined;
1232
1251
  readonly graphqlCode?: string | undefined;
1233
1252
  readonly retryable?: boolean | undefined;
1234
- 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);
1235
1255
  }
1236
1256
  declare class GrepAccessError extends Error {
1237
1257
  constructor(message: string);
@@ -1266,6 +1286,7 @@ interface ListParams {
1266
1286
  after?: string;
1267
1287
  waitTimeoutMs?: number;
1268
1288
  includeDetailedFields: boolean;
1289
+ /** Select source provenance and empty-package guidance for annotated text. */
1269
1290
  includeTargetProvenance?: boolean;
1270
1291
  /** Select exact read actions for compact site text; detailed fields always include them. */
1271
1292
  includeReadActions?: boolean;
@@ -1350,6 +1371,8 @@ interface ListSitePreparation {
1350
1371
  awaited: ListSiteWait[];
1351
1372
  }
1352
1373
  interface ListResult {
1374
+ /** Backend-authored empty-package guidance; omitted for unannotated selections. */
1375
+ hint?: string | null;
1353
1376
  indexingEstimates?: DiscoveryIndexingEstimate[];
1354
1377
  inventoryKind: ListInventoryKind;
1355
1378
  requestedTarget: string;
@@ -1397,13 +1420,15 @@ declare class ListGraphQLError extends Error {
1397
1420
  readonly hint?: string | undefined;
1398
1421
  readonly indexingMetadata: ListIndexingErrorMetadata | undefined;
1399
1422
  readonly recovery: VersionRefRecovery | undefined;
1400
- 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);
1401
1425
  }
1402
1426
  declare class ListBackendError extends Error {
1403
1427
  readonly status?: number | undefined;
1404
1428
  readonly graphqlCode?: string | undefined;
1405
1429
  readonly retryable?: boolean | undefined;
1406
- 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);
1407
1432
  }
1408
1433
  declare class ListNetworkError extends Error {
1409
1434
  constructor(message: string, options?: {
@@ -1423,6 +1448,54 @@ declare class ListServiceImpl implements ListService {
1423
1448
  list(params: ListParams, options?: ServiceRequestOptions): Promise<ListResult>;
1424
1449
  private executeList;
1425
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
+ }
1426
1499
  interface PackageSummaryParams {
1427
1500
  registry: PkgseerRegistry;
1428
1501
  packageName: string;
@@ -1461,6 +1534,16 @@ interface PackageIdentity {
1461
1534
  downloadsRefreshedAt?: string;
1462
1535
  githubRepository?: GithubRepository;
1463
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;
1464
1547
  }
1465
1548
  interface GithubRepository {
1466
1549
  stargazersCount?: number;
@@ -1490,12 +1573,16 @@ interface ChangelogEntry {
1490
1573
  }
1491
1574
  interface PackageSummary {
1492
1575
  package: PackageIdentity;
1576
+ /** Absent when the optional selected-release assessment is unavailable. */
1577
+ lifecycle?: PackageLifecycle;
1493
1578
  security?: PackageSecurityOverview;
1494
1579
  latestChangelogs?: ChangelogEntry[];
1495
1580
  }
1496
1581
  interface PackageVulnerabilitiesParams {
1497
1582
  /** Opt in to full current OSV explanations on bounded direct advisory pages. */
1498
1583
  includeSourceDetails?: boolean;
1584
+ /** Expanded per-finding provenance, consumed by verbose text or JSON. */
1585
+ includeVulnerabilityEvidence?: boolean;
1499
1586
  registry: PkgseerRegistry;
1500
1587
  packageName: string;
1501
1588
  /** Optional — backend defaults to latest when omitted. */
@@ -1522,6 +1609,9 @@ interface PackageVersionIdentity {
1522
1609
  registryRepository?: RegistryRepository;
1523
1610
  }
1524
1611
  interface VulnerabilityDetail {
1612
+ relationship?: "PACKAGE" | "RELATED";
1613
+ assessmentComplete?: boolean;
1614
+ evidence?: VulnerabilityEvidence[];
1525
1615
  osvId?: string;
1526
1616
  summary?: string;
1527
1617
  severityScore?: number;
@@ -1542,6 +1632,8 @@ interface VulnerabilityDetail {
1542
1632
  duplicateIds?: string[];
1543
1633
  }
1544
1634
  interface VulnerabilitySecurityDetails {
1635
+ assessmentComplete?: boolean;
1636
+ assessmentReasons?: string[];
1545
1637
  unknownVulnerabilityCount?: number;
1546
1638
  assessmentStatus?: string;
1547
1639
  affectedVulnerabilityCount: number;
@@ -1552,8 +1644,16 @@ interface VulnerabilitySecurityDetails {
1552
1644
  upgradePaths?: string[];
1553
1645
  }
1554
1646
  interface VulnerabilityReport {
1647
+ paginationComplete?: false;
1648
+ related?: {
1649
+ totalCount: number;
1650
+ vulnerabilities: VulnerabilityDetail[];
1651
+ sourceDetails?: VulnerabilitySourceEntry[];
1652
+ };
1555
1653
  sourceDetails?: VulnerabilitySourceEntry[];
1556
- package: PackageVersionIdentity;
1654
+ package: Omit<PackageVersionIdentity, "version"> & {
1655
+ version: string | null;
1656
+ };
1557
1657
  security?: VulnerabilitySecurityDetails;
1558
1658
  transitive?: TransitiveVulnerabilityAudit;
1559
1659
  }
@@ -1701,7 +1801,6 @@ interface PackageUpgradeChangelogEntry {
1701
1801
  body?: string;
1702
1802
  bodyPreview?: string;
1703
1803
  headline?: string;
1704
- signals: string[];
1705
1804
  }
1706
1805
  interface ChangelogRiskCoverage {
1707
1806
  versionsClassified: number;
@@ -1724,14 +1823,10 @@ interface PackageUpgradeChangelog {
1724
1823
  fallback?: string;
1725
1824
  entries?: PackageUpgradeChangelogEntry[];
1726
1825
  sampledEntries?: PackageUpgradeChangelogEntry[];
1727
- keywordEntries?: PackageUpgradeChangelogEntry[];
1728
- totalKeywordEntries: number;
1729
1826
  totalEntries: number;
1730
1827
  totalEntriesWithBodies: number;
1731
1828
  truncated: boolean;
1732
1829
  hasReleaseNoteBodies: boolean;
1733
- breakingSignals: string[];
1734
- migrationSignals: string[];
1735
1830
  }
1736
1831
  interface PackageUpgradeCompatibility {
1737
1832
  peerDependencyChanges: string[];
@@ -1795,7 +1890,6 @@ interface PackageUpgradeReviewResponse {
1795
1890
  total: number;
1796
1891
  withUnknowns: number;
1797
1892
  withAddedAdvisories: number;
1798
- withBreakingSignals: number;
1799
1893
  withDirectDependencyChanges: number;
1800
1894
  withTransitiveVulnerabilityAdditions: number;
1801
1895
  };
@@ -2250,8 +2344,6 @@ declare class PackageIntelligenceServiceImpl implements PackageIntelligenceServi
2250
2344
  private normalise;
2251
2345
  packageVulnerabilities(params: PackageVulnerabilitiesParams, options?: ServiceRequestOptions): Promise<VulnerabilityReport>;
2252
2346
  private executePackageVulnerabilities;
2253
- private fetchPackageVulnerabilitiesPage;
2254
- private normaliseVulnerabilityReport;
2255
2347
  private fetchTransitiveVulnerabilityAudit;
2256
2348
  private normaliseTransitiveVulnerabilityAudit;
2257
2349
  packageDependencies(params: PackageDependenciesParams, options?: ServiceRequestOptions): Promise<DependencyReport>;
@@ -2462,4 +2554,4 @@ declare class ProviderReauthenticationRequiredError extends Error {
2462
2554
  readonly reauthUrl: string | undefined;
2463
2555
  constructor(reauthUrl?: string);
2464
2556
  }
2465
- 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-3r5rg40v.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-6v8mtag5.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.