@contractspec/bundle.library 3.8.4 → 3.8.5

package/dist/presentation/features/templates/FeatureEventsTemplate/index.js

@@ -1,13 +1,4 @@
 // @bun
-// src/features/docs/docs.contracts.ts
-import {
-  ContractReferenceQuery,
-  DocSummaryModel,
-  DocsIndexInput,
-  DocsIndexOutput,
-  DocsIndexQuery,
-  DocsIndexQuery as DocsIndexQuery2
-} from "@contractspec/lib.contracts-spec/docs";
 // src/features/contracts-registry.ts
 import {
   EventRegistry,
@@ -18,11 +9,11 @@ import {
 } from "@contractspec/lib.contracts-spec/data-views";
 import {
   ContractReferenceDataView,
-  ContractReferenceQuery as ContractReferenceQuery2,
+  ContractReferenceQuery,
   DocsGenerateCommand,
   DocsGeneratedEvent,
   DocsIndexDataView,
-  DocsIndexQuery as DocsIndexQuery3,
+  DocsIndexQuery,
   DocsLayoutPresentation,
   DocsPublishCommand,
   DocsPublishedEvent,
@@ -44,7 +35,7 @@ import {
 var operationRegistry = null;
 function createContractSpecOperationRegistry() {
   const registry = new OperationSpecRegistry;
-  registry.register(DocsIndexQuery3).register(ContractReferenceQuery2).register(DocsGenerateCommand).register(DocsPublishCommand);
+  registry.register(DocsIndexQuery).register(ContractReferenceQuery).register(DocsGenerateCommand).register(DocsPublishCommand);
   return registry;
 }
 function getContractSpecOperationRegistry() {
@@ -190,6 +181,15 @@ var DocsFeature = {
   }
 };
 
+// src/features/docs/docs.contracts.ts
+import {
+  ContractReferenceQuery as ContractReferenceQuery2,
+  DocSummaryModel,
+  DocsIndexInput,
+  DocsIndexOutput,
+  DocsIndexQuery as DocsIndexQuery2,
+  DocsIndexQuery as DocsIndexQuery3
+} from "@contractspec/lib.contracts-spec/docs";
 // src/features/mcp.feature.ts
 var MCPFeature = {
   meta: {

package/dist/presentation/features/templates/FeatureFormsTemplate/FeatureFormsTemplate.js

@@ -1,13 +1,4 @@
 // @bun
-// src/features/docs/docs.contracts.ts
-import {
-  ContractReferenceQuery,
-  DocSummaryModel,
-  DocsIndexInput,
-  DocsIndexOutput,
-  DocsIndexQuery,
-  DocsIndexQuery as DocsIndexQuery2
-} from "@contractspec/lib.contracts-spec/docs";
 // src/features/contracts-registry.ts
 import {
   EventRegistry,
@@ -18,11 +9,11 @@ import {
 } from "@contractspec/lib.contracts-spec/data-views";
 import {
   ContractReferenceDataView,
-  ContractReferenceQuery as ContractReferenceQuery2,
+  ContractReferenceQuery,
   DocsGenerateCommand,
   DocsGeneratedEvent,
   DocsIndexDataView,
-  DocsIndexQuery as DocsIndexQuery3,
+  DocsIndexQuery,
   DocsLayoutPresentation,
   DocsPublishCommand,
   DocsPublishedEvent,
@@ -44,7 +35,7 @@ import {
 var operationRegistry = null;
 function createContractSpecOperationRegistry() {
   const registry = new OperationSpecRegistry;
-  registry.register(DocsIndexQuery3).register(ContractReferenceQuery2).register(DocsGenerateCommand).register(DocsPublishCommand);
+  registry.register(DocsIndexQuery).register(ContractReferenceQuery).register(DocsGenerateCommand).register(DocsPublishCommand);
   return registry;
 }
 function getContractSpecOperationRegistry() {
@@ -190,6 +181,15 @@ var DocsFeature = {
   }
 };
 
+// src/features/docs/docs.contracts.ts
+import {
+  ContractReferenceQuery as ContractReferenceQuery2,
+  DocSummaryModel,
+  DocsIndexInput,
+  DocsIndexOutput,
+  DocsIndexQuery as DocsIndexQuery2,
+  DocsIndexQuery as DocsIndexQuery3
+} from "@contractspec/lib.contracts-spec/docs";
 // src/features/mcp.feature.ts
 var MCPFeature = {
   meta: {

package/dist/presentation/features/templates/FeatureFormsTemplate/index.js

@@ -1,13 +1,4 @@
 // @bun
-// src/features/docs/docs.contracts.ts
-import {
-  ContractReferenceQuery,
-  DocSummaryModel,
-  DocsIndexInput,
-  DocsIndexOutput,
-  DocsIndexQuery,
-  DocsIndexQuery as DocsIndexQuery2
-} from "@contractspec/lib.contracts-spec/docs";
 // src/features/contracts-registry.ts
 import {
   EventRegistry,
@@ -18,11 +9,11 @@ import {
 } from "@contractspec/lib.contracts-spec/data-views";
 import {
   ContractReferenceDataView,
-  ContractReferenceQuery as ContractReferenceQuery2,
+  ContractReferenceQuery,
   DocsGenerateCommand,
   DocsGeneratedEvent,
   DocsIndexDataView,
-  DocsIndexQuery as DocsIndexQuery3,
+  DocsIndexQuery,
   DocsLayoutPresentation,
   DocsPublishCommand,
   DocsPublishedEvent,
@@ -44,7 +35,7 @@ import {
 var operationRegistry = null;
 function createContractSpecOperationRegistry() {
   const registry = new OperationSpecRegistry;
-  registry.register(DocsIndexQuery3).register(ContractReferenceQuery2).register(DocsGenerateCommand).register(DocsPublishCommand);
+  registry.register(DocsIndexQuery).register(ContractReferenceQuery).register(DocsGenerateCommand).register(DocsPublishCommand);
   return registry;
 }
 function getContractSpecOperationRegistry() {
@@ -190,6 +181,15 @@ var DocsFeature = {
   }
 };
 
+// src/features/docs/docs.contracts.ts
+import {
+  ContractReferenceQuery as ContractReferenceQuery2,
+  DocSummaryModel,
+  DocsIndexInput,
+  DocsIndexOutput,
+  DocsIndexQuery as DocsIndexQuery2,
+  DocsIndexQuery as DocsIndexQuery3
+} from "@contractspec/lib.contracts-spec/docs";
 // src/features/mcp.feature.ts
 var MCPFeature = {
   meta: {

package/dist/presentation/features/templates/FeaturePresentationsTemplate/FeaturePresentationsTemplate.js

@@ -1,13 +1,4 @@
 // @bun
-// src/features/docs/docs.contracts.ts
-import {
-  ContractReferenceQuery,
-  DocSummaryModel,
-  DocsIndexInput,
-  DocsIndexOutput,
-  DocsIndexQuery,
-  DocsIndexQuery as DocsIndexQuery2
-} from "@contractspec/lib.contracts-spec/docs";
 // src/features/contracts-registry.ts
 import {
   EventRegistry,
@@ -18,11 +9,11 @@ import {
 } from "@contractspec/lib.contracts-spec/data-views";
 import {
   ContractReferenceDataView,
-  ContractReferenceQuery as ContractReferenceQuery2,
+  ContractReferenceQuery,
   DocsGenerateCommand,
   DocsGeneratedEvent,
   DocsIndexDataView,
-  DocsIndexQuery as DocsIndexQuery3,
+  DocsIndexQuery,
   DocsLayoutPresentation,
   DocsPublishCommand,
   DocsPublishedEvent,
@@ -44,7 +35,7 @@ import {
 var operationRegistry = null;
 function createContractSpecOperationRegistry() {
   const registry = new OperationSpecRegistry;
-  registry.register(DocsIndexQuery3).register(ContractReferenceQuery2).register(DocsGenerateCommand).register(DocsPublishCommand);
+  registry.register(DocsIndexQuery).register(ContractReferenceQuery).register(DocsGenerateCommand).register(DocsPublishCommand);
   return registry;
 }
 function getContractSpecOperationRegistry() {
@@ -190,6 +181,15 @@ var DocsFeature = {
   }
 };
 
+// src/features/docs/docs.contracts.ts
+import {
+  ContractReferenceQuery as ContractReferenceQuery2,
+  DocSummaryModel,
+  DocsIndexInput,
+  DocsIndexOutput,
+  DocsIndexQuery as DocsIndexQuery2,
+  DocsIndexQuery as DocsIndexQuery3
+} from "@contractspec/lib.contracts-spec/docs";
 // src/features/mcp.feature.ts
 var MCPFeature = {
   meta: {

package/dist/presentation/features/templates/FeaturePresentationsTemplate/index.js

@@ -1,13 +1,4 @@
 // @bun
-// src/features/docs/docs.contracts.ts
-import {
-  ContractReferenceQuery,
-  DocSummaryModel,
-  DocsIndexInput,
-  DocsIndexOutput,
-  DocsIndexQuery,
-  DocsIndexQuery as DocsIndexQuery2
-} from "@contractspec/lib.contracts-spec/docs";
 // src/features/contracts-registry.ts
 import {
   EventRegistry,
@@ -18,11 +9,11 @@ import {
 } from "@contractspec/lib.contracts-spec/data-views";
 import {
   ContractReferenceDataView,
-  ContractReferenceQuery as ContractReferenceQuery2,
+  ContractReferenceQuery,
   DocsGenerateCommand,
   DocsGeneratedEvent,
   DocsIndexDataView,
-  DocsIndexQuery as DocsIndexQuery3,
+  DocsIndexQuery,
   DocsLayoutPresentation,
   DocsPublishCommand,
   DocsPublishedEvent,
@@ -44,7 +35,7 @@ import {
 var operationRegistry = null;
 function createContractSpecOperationRegistry() {
   const registry = new OperationSpecRegistry;
-  registry.register(DocsIndexQuery3).register(ContractReferenceQuery2).register(DocsGenerateCommand).register(DocsPublishCommand);
+  registry.register(DocsIndexQuery).register(ContractReferenceQuery).register(DocsGenerateCommand).register(DocsPublishCommand);
   return registry;
 }
 function getContractSpecOperationRegistry() {
@@ -190,6 +181,15 @@ var DocsFeature = {
   }
 };
 
+// src/features/docs/docs.contracts.ts
+import {
+  ContractReferenceQuery as ContractReferenceQuery2,
+  DocSummaryModel,
+  DocsIndexInput,
+  DocsIndexOutput,
+  DocsIndexQuery as DocsIndexQuery2,
+  DocsIndexQuery as DocsIndexQuery3
+} from "@contractspec/lib.contracts-spec/docs";
 // src/features/mcp.feature.ts
 var MCPFeature = {
   meta: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/bundle.library",
-  "version": "3.8.4",
+  "version": "3.8.5",
   "type": "module",
   "scripts": {
     "clean": "rm -rf dist",
@@ -84,12 +84,54 @@
       "node": "./dist/node/application/mcp/docsMcp.js",
       "default": "./dist/application/mcp/docsMcp.js"
     },
+    "./application/mcp/docsMcp.catalog": {
+      "types": "./dist/application/mcp/docsMcp.catalog.d.ts",
+      "bun": "./dist/application/mcp/docsMcp.catalog.js",
+      "node": "./dist/node/application/mcp/docsMcp.catalog.js",
+      "default": "./dist/application/mcp/docsMcp.catalog.js"
+    },
+    "./application/mcp/docsMcp.data": {
+      "types": "./dist/application/mcp/docsMcp.data.d.ts",
+      "bun": "./dist/application/mcp/docsMcp.data.js",
+      "node": "./dist/node/application/mcp/docsMcp.data.js",
+      "default": "./dist/application/mcp/docsMcp.data.js"
+    },
+    "./application/mcp/docsMcp.prompts": {
+      "types": "./dist/application/mcp/docsMcp.prompts.d.ts",
+      "bun": "./dist/application/mcp/docsMcp.prompts.js",
+      "node": "./dist/node/application/mcp/docsMcp.prompts.js",
+      "default": "./dist/application/mcp/docsMcp.prompts.js"
+    },
+    "./application/mcp/docsMcp.reference": {
+      "types": "./dist/application/mcp/docsMcp.reference.d.ts",
+      "bun": "./dist/application/mcp/docsMcp.reference.js",
+      "node": "./dist/node/application/mcp/docsMcp.reference.js",
+      "default": "./dist/application/mcp/docsMcp.reference.js"
+    },
+    "./application/mcp/docsMcp.resources": {
+      "types": "./dist/application/mcp/docsMcp.resources.d.ts",
+      "bun": "./dist/application/mcp/docsMcp.resources.js",
+      "node": "./dist/node/application/mcp/docsMcp.resources.js",
+      "default": "./dist/application/mcp/docsMcp.resources.js"
+    },
+    "./application/mcp/docsMcp.tools": {
+      "types": "./dist/application/mcp/docsMcp.tools.d.ts",
+      "bun": "./dist/application/mcp/docsMcp.tools.js",
+      "node": "./dist/node/application/mcp/docsMcp.tools.js",
+      "default": "./dist/application/mcp/docsMcp.tools.js"
+    },
     "./application/mcp/internalMcp": {
       "types": "./dist/application/mcp/internalMcp.d.ts",
       "bun": "./dist/application/mcp/internalMcp.js",
       "node": "./dist/node/application/mcp/internalMcp.js",
       "default": "./dist/application/mcp/internalMcp.js"
     },
+    "./application/mcp/normalizeMcpRequest": {
+      "types": "./dist/application/mcp/normalizeMcpRequest.d.ts",
+      "bun": "./dist/application/mcp/normalizeMcpRequest.js",
+      "node": "./dist/node/application/mcp/normalizeMcpRequest.js",
+      "default": "./dist/application/mcp/normalizeMcpRequest.js"
+    },
     "./application/mcp/providerRankingMcp": {
       "types": "./dist/application/mcp/providerRankingMcp.d.ts",
       "bun": "./dist/application/mcp/providerRankingMcp.js",
@@ -1945,12 +1987,54 @@
         "node": "./dist/node/application/mcp/docsMcp.js",
         "default": "./dist/application/mcp/docsMcp.js"
       },
+      "./application/mcp/docsMcp.catalog": {
+        "types": "./dist/application/mcp/docsMcp.catalog.d.ts",
+        "bun": "./dist/application/mcp/docsMcp.catalog.js",
+        "node": "./dist/node/application/mcp/docsMcp.catalog.js",
+        "default": "./dist/application/mcp/docsMcp.catalog.js"
+      },
+      "./application/mcp/docsMcp.data": {
+        "types": "./dist/application/mcp/docsMcp.data.d.ts",
+        "bun": "./dist/application/mcp/docsMcp.data.js",
+        "node": "./dist/node/application/mcp/docsMcp.data.js",
+        "default": "./dist/application/mcp/docsMcp.data.js"
+      },
+      "./application/mcp/docsMcp.prompts": {
+        "types": "./dist/application/mcp/docsMcp.prompts.d.ts",
+        "bun": "./dist/application/mcp/docsMcp.prompts.js",
+        "node": "./dist/node/application/mcp/docsMcp.prompts.js",
+        "default": "./dist/application/mcp/docsMcp.prompts.js"
+      },
+      "./application/mcp/docsMcp.reference": {
+        "types": "./dist/application/mcp/docsMcp.reference.d.ts",
+        "bun": "./dist/application/mcp/docsMcp.reference.js",
+        "node": "./dist/node/application/mcp/docsMcp.reference.js",
+        "default": "./dist/application/mcp/docsMcp.reference.js"
+      },
+      "./application/mcp/docsMcp.resources": {
+        "types": "./dist/application/mcp/docsMcp.resources.d.ts",
+        "bun": "./dist/application/mcp/docsMcp.resources.js",
+        "node": "./dist/node/application/mcp/docsMcp.resources.js",
+        "default": "./dist/application/mcp/docsMcp.resources.js"
+      },
+      "./application/mcp/docsMcp.tools": {
+        "types": "./dist/application/mcp/docsMcp.tools.d.ts",
+        "bun": "./dist/application/mcp/docsMcp.tools.js",
+        "node": "./dist/node/application/mcp/docsMcp.tools.js",
+        "default": "./dist/application/mcp/docsMcp.tools.js"
+      },
       "./application/mcp/internalMcp": {
         "types": "./dist/application/mcp/internalMcp.d.ts",
         "bun": "./dist/application/mcp/internalMcp.js",
         "node": "./dist/node/application/mcp/internalMcp.js",
         "default": "./dist/application/mcp/internalMcp.js"
       },
+      "./application/mcp/normalizeMcpRequest": {
+        "types": "./dist/application/mcp/normalizeMcpRequest.d.ts",
+        "bun": "./dist/application/mcp/normalizeMcpRequest.js",
+        "node": "./dist/node/application/mcp/normalizeMcpRequest.js",
+        "default": "./dist/application/mcp/normalizeMcpRequest.js"
+      },
       "./application/mcp/providerRankingMcp": {
         "types": "./dist/application/mcp/providerRankingMcp.d.ts",
         "bun": "./dist/application/mcp/providerRankingMcp.js",

package/src/application/mcp/common.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'bun:test';
+import {
+	OperationSpecRegistry,
+	PromptRegistry,
+	ResourceRegistry,
+} from '@contractspec/lib.contracts-spec';
+import { Elysia } from 'elysia';
+import { appLogger } from '../../infrastructure/elysia/logger';
+import { createMcpElysiaHandler } from './common';
+
+function createTestApp() {
+	return new Elysia().use(
+		createMcpElysiaHandler({
+			logger: appLogger,
+			path: '/mcp/test',
+			serverName: 'test-mcp',
+			ops: new OperationSpecRegistry(),
+			resources: new ResourceRegistry(),
+			prompts: new PromptRegistry(),
+		})
+	);
+}
+
+function createInitializeRequest(accept: string) {
+	return new Request('http://localhost/mcp/test', {
+		method: 'POST',
+		headers: {
+			accept,
+			'content-type': 'application/json',
+		},
+		body: JSON.stringify({
+			jsonrpc: '2.0',
+			id: 1,
+			method: 'initialize',
+			params: {
+				protocolVersion: '2024-11-05',
+				capabilities: {},
+				clientInfo: { name: 'test-client', version: '1.0.0' },
+			},
+		}),
+	});
+}
+
+describe('createMcpElysiaHandler', () => {
+	it('accepts JSON-only clients for POST MCP requests', async () => {
+		const response = await createTestApp().handle(
+			createInitializeRequest('application/json')
+		);
+
+		expect(response.status).toBe(200);
+		const body = await response.json();
+		expect(body.result.serverInfo.name).toBe('test-mcp');
+	});
+
+	it('keeps rejecting incompatible Accept headers', async () => {
+		const response = await createTestApp().handle(
+			createInitializeRequest('text/html')
+		);
+
+		expect(response.status).toBe(406);
+		const body = await response.json();
+		expect(body.error.message).toContain('Not Acceptable');
+	});
+});

package/src/application/mcp/common.ts

@@ -12,6 +12,7 @@ import { Logger } from '@contractspec/lib.logger';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 import { Elysia } from 'elysia';
+import { normalizeMcpRequest } from './normalizeMcpRequest';
 
 export interface McpAuthValidationResult {
 	valid: boolean;
@@ -150,7 +151,7 @@ export function createMcpElysiaHandler({
 		});
 
 		try {
-			return await state.transport.handleRequest(request);
+			return await state.transport.handleRequest(normalizeMcpRequest(request));
 		} finally {
 			await closeSessionState(state);
 		}
@@ -189,7 +190,9 @@ export function createMcpElysiaHandler({
 		}
 
 		try {
-			const response = await state.transport.handleRequest(request);
+			const response = await state.transport.handleRequest(
+				normalizeMcpRequest(request)
+			);
 			const activeSessionId = state.transport.sessionId;
 
 			if (activeSessionId && !sessions.has(activeSessionId)) {

package/src/application/mcp/docsMcp.catalog.ts

@@ -0,0 +1,2 @@
+export * from './docsMcp.data';
+export * from './docsMcp.reference';

package/src/application/mcp/docsMcp.data.ts

@@ -0,0 +1,196 @@
+import type { DocPresentationRoute } from '@contractspec/lib.contracts-spec/docs';
+import { defaultDocRegistry } from '@contractspec/lib.contracts-spec/docs';
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+
+type DocsSearchArgs = {
+	query?: string;
+	tag?: string | string[];
+	visibility?: string;
+	kind?: string;
+	limit?: number;
+	offset?: number;
+};
+
+function normalizeText(value: string | undefined | null) {
+	return value?.trim().toLowerCase() ?? '';
+}
+
+function normalizeRoute(route: string) {
+	const decoded = decodeURIComponent(route).trim();
+	if (!decoded) return '/';
+	return decoded.startsWith('/') ? decoded : `/${decoded}`;
+}
+
+function normalizeTags(value: string | string[] | undefined) {
+	const tags = Array.isArray(value) ? value : value ? [value] : [];
+	return tags.map((tag) => normalizeText(tag)).filter(Boolean);
+}
+
+function clampLimit(limit: number | undefined) {
+	if (!limit || Number.isNaN(limit)) return DEFAULT_LIMIT;
+	return Math.min(Math.max(limit, 1), MAX_LIMIT);
+}
+
+function clampOffset(offset: number | undefined) {
+	if (!offset || Number.isNaN(offset)) return 0;
+	return Math.max(offset, 0);
+}
+
+export function toDocSummary({ block, route }: DocPresentationRoute) {
+	return {
+		id: block.id,
+		title: block.title,
+		summary: block.summary ?? '',
+		route,
+		visibility: block.visibility ?? 'public',
+		kind: block.kind ?? 'reference',
+		version: block.version ?? '1.0.0',
+		tags: block.tags ?? [],
+	};
+}
+
+function scoreDoc(route: DocPresentationRoute, query: string) {
+	if (!query) return 1;
+
+	const tokens = query.split(/\s+/).filter(Boolean);
+	const title = normalizeText(route.block.title);
+	const id = normalizeText(route.block.id);
+	const summary = normalizeText(route.block.summary);
+	const body = normalizeText(route.block.body);
+	const path = normalizeText(route.route);
+	const tags = (route.block.tags ?? []).map((tag) => normalizeText(tag));
+	const haystack = [title, id, summary, body, path, ...tags].join(' ');
+
+	if (tokens.some((token) => !haystack.includes(token))) return 0;
+
+	let score = 0;
+	for (const token of tokens) {
+		if (id.includes(token)) score += 8;
+		if (title.includes(token)) score += 7;
+		if (tags.some((tag) => tag.includes(token))) score += 5;
+		if (summary.includes(token)) score += 4;
+		if (path.includes(token)) score += 3;
+		if (body.includes(token)) score += 2;
+	}
+
+	return score;
+}
+
+export function searchDocs(
+	routes: DocPresentationRoute[],
+	args: DocsSearchArgs
+) {
+	const query = normalizeText(
+		typeof args.query === 'string' ? args.query : undefined
+	);
+	const tags = normalizeTags(args.tag as string | string[] | undefined);
+	const visibility = normalizeText(
+		typeof args.visibility === 'string' ? args.visibility : undefined
+	);
+	const kind = normalizeText(
+		typeof args.kind === 'string' ? args.kind : undefined
+	);
+	const limit = clampLimit(
+		typeof args.limit === 'number' ? args.limit : undefined
+	);
+	const offset = clampOffset(
+		typeof args.offset === 'number' ? args.offset : undefined
+	);
+
+	const ranked = routes
+		.map((route) => ({
+			doc: toDocSummary(route),
+			score: scoreDoc(route, query),
+		}))
+		.filter(({ doc, score }) => {
+			const matchesQuery = query ? score > 0 : true;
+			const matchesTags = tags.length
+				? tags.every((tag) =>
+						doc.tags.some((docTag) => normalizeText(docTag).includes(tag))
+					)
+				: true;
+			const matchesVisibility = visibility
+				? normalizeText(doc.visibility) === visibility
+				: true;
+			const matchesKind = kind ? normalizeText(doc.kind) === kind : true;
+			return matchesQuery && matchesTags && matchesVisibility && matchesKind;
+		})
+		.sort((left, right) => {
+			if (right.score !== left.score) return right.score - left.score;
+			return left.doc.title.localeCompare(right.doc.title);
+		});
+
+	const docs = ranked.slice(offset, offset + limit).map(({ doc }) => doc);
+	const nextOffset =
+		offset + docs.length < ranked.length ? offset + docs.length : undefined;
+
+	return {
+		docs,
+		items: docs,
+		total: ranked.length,
+		...(nextOffset != null ? { nextOffset } : {}),
+	};
+}
+
+export function getDocById(id: string) {
+	const normalizedId = decodeURIComponent(id);
+	const found = defaultDocRegistry.get(normalizedId);
+	if (!found) return undefined;
+
+	return {
+		doc: toDocSummary(found),
+		content: String(found.block.body ?? ''),
+	};
+}
+
+export function getDocByRoute(
+	routes: DocPresentationRoute[],
+	routePath: string
+) {
+	const normalizedPath = normalizeRoute(routePath);
+	const found = routes.find(
+		(route) => normalizeRoute(route.route) === normalizedPath
+	);
+	if (!found) return undefined;
+
+	return {
+		doc: toDocSummary(found),
+		content: String(found.block.body ?? ''),
+	};
+}
+
+export function listDocFacets(routes: DocPresentationRoute[]) {
+	const tags = new Map<string, number>();
+	const kinds = new Map<string, number>();
+	const visibilities = new Map<string, number>();
+
+	for (const route of routes) {
+		const kind = route.block.kind ?? 'reference';
+		const visibility = route.block.visibility ?? 'public';
+		kinds.set(kind, (kinds.get(kind) ?? 0) + 1);
+		visibilities.set(visibility, (visibilities.get(visibility) ?? 0) + 1);
+
+		for (const tag of route.block.tags ?? []) {
+			tags.set(tag, (tags.get(tag) ?? 0) + 1);
+		}
+	}
+
+	const toEntries = (
+		values: Map<string, number>,
+		key: 'tag' | 'kind' | 'visibility'
+	) =>
+		[...values.entries()]
+			.sort(
+				(left, right) => right[1] - left[1] || left[0].localeCompare(right[0])
+			)
+			.map(([value, count]) => ({ [key]: value, count }));
+
+	return {
+		totalDocs: routes.length,
+		tags: toEntries(tags, 'tag'),
+		kinds: toEntries(kinds, 'kind'),
+		visibilities: toEntries(visibilities, 'visibility'),
+	};
+}