From cc08c0983a431afbf5e620b5b7802bb5846d33d2 Mon Sep 17 00:00:00 2001 From: zho Date: Tue, 16 Jun 2026 05:22:29 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20phase=201=20export=20trim=20=E2=80=94?= =?UTF-8?q?=20remove=20experimental=20block=20builders=20from=20public=20A?= =?UTF-8?q?PI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove buildQueryExperimental and buildGuidedQueryExperimental from package root and /alliance re-exports. PineconeClient return types and Zod response schemas remain public. Add MIGRATION.md guidance, CHANGELOG entry, and export-surface regression test. Co-authored-by: Cursor --- CHANGELOG.md | 6 ++++++ docs/MIGRATION.md | 17 +++++++++++++++++ src/core/__tests__/public-exports.test.ts | 9 +++++++++ src/core/index.ts | 2 -- 4 files changed, 32 insertions(+), 2 deletions(-) create mode 100644 src/core/__tests__/public-exports.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f4955d..24efa2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,12 +14,18 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release - **Breaking (core):** `resolveConfig` requires a Pinecone index name and no longer applies Alliance index/rerank defaults. Removed exported `DEFAULT_INDEX_NAME` and `DEFAULT_RERANK_MODEL` from the package root. Rerank is opt-in when `PINECONE_RERANK_MODEL` / `rerankModel` is unset. - **Breaking (core):** `setupCoreServer` MCP `instructions` use `CORE_SERVER_INSTRUCTIONS` (no `guided_query` / `suggest_query_params`). `resolveConfig` defaults `disableSuggestFlow` to `true` so `query` / `count` / `query_documents` work without Alliance tools. Alliance CLI / `resolveAllianceConfig` unchanged: gate on by default, `ALLIANCE_SERVER_INSTRUCTIONS`. - **Alliance CLI / `resolveAllianceConfig`:** When index or rerank env/CLI values are omitted, defaults remain `rag-hybrid` and `bge-reranker-v2-m3` (API-key-only MCP configs unchanged). See [examples/alliance/.env.example](examples/alliance/.env.example). +- **Breaking (library):** Trimmed public re-exports — `buildQueryExperimental` and `buildGuidedQueryExperimental` removed from package root and `/alliance` entry. See [MIGRATION.md](docs/MIGRATION.md#unreleased-trimmed-library-exports). ### Added - Zod schemas for all nine MCP tool success responses (`queryResponseSchema`, `guidedQueryResponseSchema`, etc.) exported from the package root for client-side validation. Success payloads are runtime-validated before return. - Stable vs experimental response field taxonomy documented in [docs/TOOLS.md](docs/TOOLS.md) and [docs/deprecation-policy.md](docs/deprecation-policy.md#stable-vs-experimental-mcp-response-fields). - Formal deprecation policy ([docs/deprecation-policy.md](docs/deprecation-policy.md)) and breaking-change release notes template ([docs/templates/breaking-change-release-notes.md](docs/templates/breaking-change-release-notes.md)). +### Removed + +- **Breaking (library):** `buildQueryExperimental` and `buildGuidedQueryExperimental` are no longer re-exported from `@will-cppa/pinecone-read-only-mcp` or `@will-cppa/pinecone-read-only-mcp/alliance`. They were internal helpers used to assemble the `experimental` block on `query` / `query_documents` / `guided_query` success payloads. The assembled fields and Zod schemas (`queryResponseSchema`, `QueryExperimental`, etc.) are unchanged — see [Unreleased stable vs experimental](docs/MIGRATION.md#unreleased-stable-vs-experimental-response-fields). +- **No change:** `HybridQueryResult`, `HybridLegFailed`, and `KeywordIndexNamespacesResult` remain exported as the declared return types of public `PineconeClient` methods. + ## [0.2.0] - 2026-05-29 ### Changed diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 0b6c61d..7a8d894 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -69,6 +69,23 @@ When no experimental fields apply, the `experimental` key is **omitted** (not an **Promotion:** Moving a field from `experimental` to stable requires CHANGELOG, TOOLS.md, and schema updates per [deprecation-policy.md § Stable vs experimental](./deprecation-policy.md#stable-vs-experimental-mcp-response-fields). +## Unreleased: trimmed library exports + +**Who is affected:** Library embedders that imported `buildQueryExperimental` or `buildGuidedQueryExperimental` from `@will-cppa/pinecone-read-only-mcp` or `/alliance`. + +**Before:** + +```ts +import { buildQueryExperimental } from '@will-cppa/pinecone-read-only-mcp'; +``` + +**After:** These helpers are internal to the server. Options: + +1. Invoke the relevant MCP tool handler and parse the success payload with `queryResponseSchema` / `guidedQueryResponseSchema`. +2. Build the `experimental` object yourself to match `QueryExperimental` if you control the response shape. + +`PineconeClient.query()` return types (`HybridQueryResult`, etc.) and all Zod response schemas remain on the public surface. + ## Unreleased: `ServerContext` instance APIs (phase 1) **Rationale:** Process-global singletons (Pinecone client slot, config, URL registry, suggest-flow gate, namespaces cache) complicate testing and multi-tenant embedding. Phase 1 introduces an opt-in **`ServerContext`** without removing legacy getters. diff --git a/src/core/__tests__/public-exports.test.ts b/src/core/__tests__/public-exports.test.ts new file mode 100644 index 0000000..cf02b92 --- /dev/null +++ b/src/core/__tests__/public-exports.test.ts @@ -0,0 +1,9 @@ +import { describe, expect, it } from 'vitest'; +import * as core from '../index.js'; + +describe('public export surface', () => { + it('does not export internal experimental block builders', () => { + expect('buildQueryExperimental' in core).toBe(false); + expect('buildGuidedQueryExperimental' in core).toBe(false); + }); +}); diff --git a/src/core/index.ts b/src/core/index.ts index d2845cb..4f1684b 100644 --- a/src/core/index.ts +++ b/src/core/index.ts @@ -16,8 +16,6 @@ export type { MetadataFilterValidationError } from './server/metadata-filter.js' export { toolErrorSchema } from './server/tool-error.js'; export type { ToolError, ToolErrorCode } from './server/tool-error.js'; export { - buildGuidedQueryExperimental, - buildQueryExperimental, countResponseSchema, generateUrlsResponseSchema, guidedQueryResponseSchema,