@farming-labs/theme 0.2.71 → 0.2.72

package/dist/docs-api.mjs

@@ -4,7 +4,7 @@ import { BoundedRouteCache } from "./bounded-route-cache.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_MARKDOWN_SECTION_INDEX_FORMAT, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, resolveDocsSearchAudience, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
+import { DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_MARKDOWN_SECTION_INDEX_FORMAT, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, performDocsSearchWithMetadata, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, resolveDocsSearchAudience, resolveDocsSearchFilters, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
 import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceConfig, resolveConfiguredAgentSkills, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -405,10 +405,27 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			enabled: searchEnabled,
 			endpoint: `${apiRoute}?query={query}`,
 			agentEndpoint: `${apiRoute}?query={query}&audience=agent`,
+			structuredAgentEndpoint: `${apiRoute}?query={query}&audience=agent&response=structured`,
 			method: "GET",
 			queryParam: "query",
 			localeParam: "lang",
 			audienceParam: "audience",
+			responseParam: "response",
+			structuredResponseValue: "structured",
+			responseFormat: "docs-search.v1",
+			filterParams: {
+				framework: "framework",
+				version: "version",
+				package: "package",
+				tags: "tags"
+			},
+			repeatedFilterParams: [
+				"framework",
+				"version",
+				"package",
+				"tags"
+			],
+			warningsField: "warnings",
 			defaultAudience: "human",
 			supportedAudiences: ["human", "agent"]
 		},
@@ -978,6 +995,9 @@ function scanDocsDir(docsDir, entry, locale, excludedDirs = [], publicPath = `/$
 			if (resolvePageSidebarFolderIndexBehavior(data.sidebar) === "hidden" && hasVisibleDescendantDocsSearchPage(dir)) {} else {
 				const title = data.title || slugParts[slugParts.length - 1]?.replace(/-/g, " ") || "Documentation";
 				const description = data.description;
+				const framework = typeof data.framework === "string" ? data.framework : void 0;
+				const version = typeof data.version === "string" ? data.version : void 0;
+				const tags = Array.isArray(data.tags) ? data.tags.filter((value) => typeof value === "string") : void 0;
 				const { content: fileContent } = matter(raw);
 				const rawContent = resolveDocsAudienceMdxContent(fileContent, "human");
 				const agentRawContent = resolveDocsAudienceMdxContent(fileContent, "agent");
@@ -996,6 +1016,9 @@ function scanDocsDir(docsDir, entry, locale, excludedDirs = [], publicPath = `/$
 					sourcePath: pageSource.replace(/\\/g, "/"),
 					lastModified: fs.statSync(pageSource).mtime.toISOString(),
 					locale,
+					framework,
+					version,
+					tags,
 					...agentDoc
 				});
 			}
@@ -1293,7 +1316,7 @@ function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, mcp,
 	lines.push("", "## When To Use", "Use this skill when you need to read or implement against this documentation site.", "", "## Start Here", `- Fetch ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${agentSpecRoute}.`);
 	if (apiCatalog) lines.push(`- Fetch ${DEFAULT_API_CATALOG_ROUTE} for the standards-based API catalog.`);
 	lines.push(`- Fetch ${DEFAULT_AGENT_SKILLS_INDEX_ROUTE} to discover the published site skill and verify its SHA-256 digest.`, `- Fetch /${normalizedEntry}.md for the root docs page.`, `- Fetch /${normalizedEntry}/{slug}.md for page-specific context.`, `- Fetch /${normalizedEntry}/{slug}.md?sections to list section IDs and size estimates before requesting ?section={id}.`, "- You can also request text/markdown from normal page URLs.");
-	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent when you do not know the page.`);
+	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent&response=structured when you do not know the page; add framework, version, package, or repeated tags filters when scope matters.`);
 	if (openapi.enabled && openapiUrl) lines.push(`- Fetch ${openapiUrl} for the machine-readable OpenAPI schema before scraping API reference pages.`);
 	if (llms.enabled) {
 		lines.push(`- Use ${DEFAULT_LLMS_TXT_ROUTE} for a compact docs index.`, `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} for full markdown context.`);
@@ -1358,7 +1381,7 @@ function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, mcp
 		if (sitemapConfig.xml.enabled) lines.push(`- Use ${sitemapConfig.xml.route} for canonical URLs and freshness metadata.`);
 	}
 	if (robotsEnabled) lines.push(`- Check ${DEFAULT_ROBOTS_TXT_ROUTE} before crawling broadly.`);
-	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent when the route is unknown.`);
+	if (searchEnabled) lines.push(`- Search with ${apiRoute}?query={query}&audience=agent&response=structured when the route is unknown; add framework, version, package, or repeated tags filters when scope matters.`);
 	if (openapi.enabled && openapiUrl) lines.push(`- Fetch ${openapiUrl} before scraping API reference pages; prefer schemas over prose.`);
 	if (mcp.enabled) lines.push(`- Use MCP at ${DEFAULT_MCP_PUBLIC_ROUTE} or ${DEFAULT_MCP_WELL_KNOWN_ROUTE} when your environment supports MCP tools.`);
 	if (feedback.enabled) lines.push(`- Read ${feedback.schemaRoute} before posting feedback to ${feedback.route}.`);
@@ -3131,19 +3154,35 @@ function createDocsAPI(options) {
 				} });
 			}
 			const query = url.searchParams.get("query")?.trim();
-			if (!query) return new Response(JSON.stringify([]), { headers: { "Content-Type": "application/json" } });
-			const searchStartedAt = Date.now();
 			const audience = resolveDocsSearchAudience(url.searchParams.get("audience"));
-			const results = await performDocsSearch({
+			const filters = resolveDocsSearchFilters(url.searchParams);
+			const structured = url.searchParams.get("response") === "structured";
+			if (!query) {
+				const searchResponse = structured ? {
+					format: "docs-search.v1",
+					query: "",
+					audience,
+					filters,
+					resultCount: 0,
+					results: [],
+					warnings: []
+				} : [];
+				return new Response(JSON.stringify(searchResponse), { headers: { "Content-Type": "application/json" } });
+			}
+			const searchStartedAt = Date.now();
+			const searchOptions = {
 				pages: getIndexes(ctx),
 				query,
 				search: resolveSearchRequestConfig(searchConfig, request.url),
 				audience,
+				filters,
 				locale: ctx.locale,
 				pathname: url.searchParams.get("pathname") ?? void 0,
 				siteTitle: llmsConfig.siteTitle ?? "Documentation",
 				baseUrl: markdownMetadataBaseUrl || url.origin
-			});
+			};
+			const searchResponse = structured ? await performDocsSearchWithMetadata(searchOptions) : await performDocsSearch(searchOptions);
+			const resultCount = Array.isArray(searchResponse) ? searchResponse.length : searchResponse.resultCount;
 			await emitDocsAnalyticsEvent(analytics, {
 				type: "api_search",
 				source: "server",
@@ -3155,12 +3194,12 @@ function createDocsAPI(options) {
 					...requestAnalyticsProperties,
 					queryLength: query.length,
 					audience,
-					resultCount: results.length,
+					resultCount,
 					pathname: url.searchParams.get("pathname") ?? void 0,
 					durationMs: Math.max(0, Date.now() - searchStartedAt)
 				}
 			});
-			return new Response(JSON.stringify(results), { headers: { "Content-Type": "application/json" } });
+			return new Response(JSON.stringify(searchResponse), { headers: { "Content-Type": "application/json" } });
 		},
 		async POST(request) {
 			trackTelemetryRequest(request);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.2.71",
+  "version": "0.2.72",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -148,7 +148,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@farming-labs/docs": "0.2.71"
+    "@farming-labs/docs": "0.2.72"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",