@oomkapwn/enquire-mcp 3.6.0-rc.1 → 3.6.0-rc.3

package/CHANGELOG.md

@@ -2,6 +2,126 @@
 
 All notable changes to this project will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.0-rc.3] — 2026-05-15
+
+> **TL;DR:** v3.6.0 Phase 3 of 4 — **+2238 lines of Full TSDoc** added across 44 MCP tool functions, 19 prompt definitions, and ~50 exported helpers/types. Every exported function now ships with one-sentence summary + detailed description + `@param` / `@returns` / `@throws` / `@example`. Internal cross-domain helpers marked `@internal` so v3.6.0-rc.4's TypeDoc auto-generation keeps them out of the public surface. Pure documentation addition: 712 tests pass, zero behavior change. Published under npm dist-tag `rc`.
+
+**Pre-release — v3.6.0 sprint Phase 3.**
+
+### Added — Full TSDoc on the public API surface
+
+Every exported function in `src/tools/*` and every prompt in `src/prompts.ts` now has comprehensive TSDoc. Per-file expansion:
+
+| File | Before | After | TSDoc blocks |
+|---|---:|---:|---:|
+| `src/tools/search.ts` | 1224 | 1565 (+341) | 62 |
+| `src/tools/read.ts` | 864 | 1384 (+520) | 111 |
+| `src/tools/write.ts` | 682 | 1094 (+412) | 47 |
+| `src/tools/media.ts` | 516 | 725 (+209) | 53 |
+| `src/tools/meta.ts` | 984 | 1425 (+441) | 76 |
+| `src/prompts.ts` | 790 | 1105 (+315) | 20 |
+| **Total** | **5060** | **7298** | **369 TSDoc blocks** |
+
+The 369 TSDoc blocks include:
+- **44 MCP tool functions** (the public API surface) — each with summary, description distinguishing it from alternatives, `@param` per parameter with type-aware description, `@returns`, `@throws` where applicable, and ` ```ts ``` ` `@example` showing realistic usage.
+- **19 prompt registrations** in `src/prompts.ts` — each with a `// === prompt_name ============` banner header above the registration call + a TSDoc block above the banner describing purpose, expected args (read from `argsSchema`), and intended use case.
+- **~30 exported types/interfaces** (e.g., `SearchHit`, `SearchHybridResponse`, `RenameNoteResult`, `ContextPackResult`) — each with description and field-level docs where the field-doc convention was already in place.
+- **~15 cross-domain helpers** (e.g., `tokenizeForTfidf`, `findBestMatch`, `resolveTarget`, `rewriteRawTarget`, `jaccard`) — marked `@internal` so the v3.6.0-rc.4 TypeDoc pass keeps them out of the public API reference.
+
+Distinct-from cross-references are present where two functions could be confused:
+- `searchText` / `semanticSearch` / `embeddingsSearch` / `searchHybrid` — each TSDoc explicitly contrasts the variant and points readers at `{@link searchHybrid}` as the recommended umbrella entry.
+- `vault_synth` / `vault_synthesis_page` / `vault_research` / `search_with_query_expansion` — prompt-to-prompt cross-references explaining when each is the right pick.
+
+### Validation
+
+712 unit tests pass · branches 75.29% · lines 89.54% · statements 86.07% · functions 82.15% · lint clean · `tsc` strict + `noUncheckedIndexedAccess` clean · smoke pass · version-consistency green at `3.6.0-rc.3` (5 surfaces).
+
+### Migration
+
+**No-op for consumers.** No function signatures changed, no behavior changed, no exports added or removed. Pure documentation addition.
+
+For contributors:
+- IDE hovers now display full descriptions + examples for every tool function.
+- VS Code, Cursor, IntelliJ, Vim+lsp all surface the TSDoc instantly.
+
+### npm dist-tag
+
+Published under **`rc`** dist-tag. Users on `latest` stay on v3.5.14. Try: `npm install @oomkapwn/enquire-mcp@rc`.
+
+### Next RC
+
+`v3.6.0-rc.4`: TypeDoc auto-generation of API reference docs + publish to GitHub Pages. Plus public benchmarks (MRR / NDCG@10 / Recall@K on a BEIR/TREC subset, with comparison vs main competitors).
+
+### Method note
+
+This is the second phase that ships **without any logic change** — pure structural/documentation work that compounds value: the TSDoc written here becomes the source for rc.4's auto-generated API docs site. The maintenance burden going forward is low because the TSDoc lives next to the code (drift requires actively writing wrong docs vs. doing nothing).
+
+## [3.6.0-rc.2] — 2026-05-15
+
+> **TL;DR:** v3.6.0 Phase 2 of 4 — `src/index.ts` (3665 lines) split into 5 domain modules (`cli.ts` 702 + `server.ts` 877 + `tool-registry.ts` 1300 + `prompts.ts` 790) plus a slim 84-line entry point. NEW `src/tool-manifest.ts` (318 lines, 44 machine-readable tool entries) becomes the single source of truth — `tests/docs-consistency.test.ts` pivoted off regex-parsing source code and reads the manifest directly. Pure refactor: same CLI surface, same registered tools, same 712 tests pass. Published under npm dist-tag `rc`.
+
+**Pre-release — v3.6.0 sprint Phase 2.**
+
+### Changed — `src/index.ts` (3665 lines) → domain modules
+
+Phase 1 (rc.1) split `tools.ts`. This RC does the same for `index.ts`. The pre-refactor file packed CLI definition, MCP server construction, tool registration, prompt definitions, sync routines, and utility helpers into a single 3665-line monolith. After rc.2:
+
+| File | Lines | Purpose |
+|---|---:|---|
+| `src/index.ts` (slim) | 84 | `VERSION` literal (kept here so `scripts/check-version-consistency.mjs` regex still finds it) + CLI-entry guard + re-exports (`main`, `parsePositiveInt`, `parseQuantizationMode`, `startServer`, `buildMcpServer`, `buildEmbedText`, `formatReadyBanner`, `prepareServerDeps`, types `ServeOptions` / `ServerDeps`) |
+| `src/cli.ts` | 702 | `main()` + commander program definition (all 12 subcommands) |
+| `src/server.ts` | 877 | MCP server construction: `ServeOptions`, `ServerDeps`, `prepareServerDeps`, `buildMcpServer`, `startServer`, `formatReadyBanner`, `buildEmbedText`, `syncEmbedDb` / `syncFtsIndex` / `syncPdfFtsIndex` / `syncPdfEmbedDb` |
+| `src/tool-registry.ts` | 1300 | `registerFtsTools` + `registerReadTools` + `registerWriteTools` + `registerResources` + `registerChunkResource` + helpers (`embedDbPath`, `parsePositiveInt`, `parseQuantizationMode`, `encodeNotePath`, `decodeNotePath`, `textResult`) |
+| `src/prompts.ts` | 790 | `registerPrompts` with all 19 MCP prompt definitions |
+
+The slim `index.ts` keeps the v3.5.x re-export surface so `src/http-transport.ts` + tests + external consumers don't need to know about the new layout. Module dependency graph is cycle-safe (the `cli.ts` ↔ `index.ts` VERSION cycle is a literal-value cycle, evaluated at module-init time; runtime-only, no TDZ surprises).
+
+### Added — `src/tool-manifest.ts` (318 lines, 44 entries)
+
+Machine-readable manifest of every MCP tool: `name`, `kind` (`read` | `fts` | `write` | `diagnostic`), `gating` (the `--persistent-index` / `--enable-write` / etc. clause), and a 1-line `summary`. Entries:
+
+| Kind | Count | Gating |
+|---|---:|---|
+| `read` | 33 | always-on |
+| `fts` | 1 | `--persistent-index + --diagnostic-search-tools` |
+| `diagnostic` | 3 | `--diagnostic-search-tools` |
+| `write` | 7 | `--enable-write` |
+| **Total** | **44** | (matches the count math invariant in `tests/docs-consistency.test.ts`) |
+
+The full `registerTool()` description argument stays at the registration site so MCP clients still see verbatim what they did pre-refactor. The manifest's `summary` is a 1-line distillation for docs / future auto-generation use cases.
+
+### Changed — `tests/docs-consistency.test.ts` pivots to TOOL_MANIFEST
+
+Pre-v3.6.0-rc.2, this file regex-parsed `src/index.ts` for `registerTool(` patterns + `function registerWriteTools(` markers + `if (diagnosticSearchTools) server.registerTool(` gating syntax. After the rc.2 monolith split, those patterns moved to `tool-registry.ts` — but rather than chase the regex paths, we **pivoted the entire tool-count invariants to read `TOOL_MANIFEST` directly**. Type-safe, no regex brittleness, single source of truth.
+
+Surfaces still parsed by regex (no manifest yet):
+- `src/prompts.ts` — registerPrompt() names (possible v3.6.0-rc.3: introduce `PROMPT_MANIFEST`)
+- `src/cli.ts` — `.command()` subcommand names + the `serve` / `serve-http` flag blocks (for the shared-help-strings invariant)
+
+### Validation
+
+712 unit tests pass · 31 test files · branches 75.29% · lines 89.54% · statements 86.06% · functions 82.15% · lint clean (1 pre-existing info note about biome schema 2.4.15 vs locally-cached 2.4.14 CLI — resolves on CI which installs 2.4.15 fresh) · `tsc` strict + `noUncheckedIndexedAccess` clean · smoke pass · version-consistency green at `3.6.0-rc.2` (5 surfaces).
+
+### Migration
+
+**No-op for consumers.** Public npm package surface (44 tools, 19 prompts, CLI flags, `package.json` `exports` sub-paths) is identical. The refactor is internal file structure + new `tool-manifest.ts` as a documentation source-of-truth.
+
+For contributors:
+- `import { TOOL_MANIFEST } from "@oomkapwn/enquire-mcp/dist/tool-manifest.js"` — programmatically iterate tools by kind / gating / summary.
+- `src/index.ts` re-exports the v3.5.x surface unchanged. Imports from `./index.js` continue to work.
+
+### Method note
+
+This RC removed an entire **class of brittleness** (regex-parsing source code to extract structured data). Replaced with type-safe, IDE-completable iteration over a typed const array. The methodology: when refactor causes drift in tests, don't chase the regex — pivot the test to a machine-readable structure that survives future refactors.
+
+### npm dist-tag
+
+Published under **`rc`** dist-tag. Users on `latest` stay on v3.5.14. To try: `npm install @oomkapwn/enquire-mcp@rc`.
+
+### Next RC
+
+`v3.6.0-rc.3`: Full TSDoc (`@param` / `@returns` / `@example`) on 44 tools + 19 prompts + 20 `src/` modules (~1300+ lines of doc-comments). Setup for `v3.6.0-rc.4` TypeDoc auto-generation.
+
 ## [3.6.0-rc.1] — 2026-05-15
 
 > **TL;DR:** v3.6.0 Phase 1 of 4 — `src/tools.ts` (4252 lines) split into 5 domain modules under `src/tools/` with a barrel re-export. Pure refactor: same exported surface, same signatures, all 712 tests pass. Published to npm under dist-tag `rc` (NOT `latest`); install with `npm i @oomkapwn/enquire-mcp@rc` to try.

package/STABILITY.md

@@ -50,8 +50,9 @@ The package exports a few symbols for advanced embedding / programmatic use. The
 - `EmbedDb` / `EmbedDbOptions` / `EmbedQuantization` / `encodeInt8Vector` / `decodeInt8Vector` (`src/embed-db.ts`)
 - `FtsIndex` / `chunkContent` / `defaultIndexFile` (`src/fts5.ts`)
 - `Vault` (`src/vault.ts`)
-- `ServeOptions` / `parsePositiveInt` / `parseQuantizationMode` / `startServer` / `main` / `buildMcpServer` / `prepareServerDeps` / `formatReadyBanner` / `buildEmbedText` (`src/index.ts`)
+- `ServeOptions` / `parsePositiveInt` / `parseQuantizationMode` / `startServer` / `main` / `buildMcpServer` / `prepareServerDeps` / `formatReadyBanner` / `buildEmbedText` — re-exported from `src/index.ts` (since v3.6.0-rc.2 they live in `src/server.ts` / `src/cli.ts` / `src/tool-registry.ts`, with `src/index.ts` keeping the re-export surface for v3.5.x BC).
 - `HnswIndex` / `loadHnswFromDisk` / `HnswPersistedMeta` (`src/hnsw.ts`)
+- `TOOL_MANIFEST` / `ToolManifestEntry` (`src/tool-manifest.ts`) — machine-readable manifest of all MCP tools (added in v3.6.0-rc.2). New stable surface — guaranteed to retain `name`, `kind`, `gating`, `summary` fields per entry across all v3.x.
 
 Anything not listed here (private fields, internal helpers, test fixtures) is **not** semver-bound.
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export declare function main(): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAiCA,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA4pB1C"}