@farming-labs/theme 0.2.77 → 0.2.78

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_AGENT_MANIFEST_VERSION, 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, resolveDocsRetrievalLastModified, resolveDocsSearchAudience, resolveDocsSearchError, resolveDocsSearchRequest, 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_AGENT_MANIFEST_VERSION, DOCS_CONTENT_CHANGES_FORMAT, DOCS_CONTENT_CHANGES_RESPONSE_VALUE, DOCS_MARKDOWN_SECTION_INDEX_FORMAT, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, buildDocsSearchFacets, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsContentChangeFeed, createDocsContentChangesHttpResponse, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsContentChangesRequest, isDocsDiagnosticsRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, performDocsSearchWithMetadata, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsContentChangesConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, resolveDocsRetrievalLastModified, resolveDocsSearchAudience, resolveDocsSearchError, resolveDocsSearchRequest, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
 import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceOpenApiDiscovery, resolveConfiguredAgentSkills, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -197,10 +197,11 @@ function isRobotsDiscoveryEnabled(robots) {
 function isApiReferenceOpenApiRequest(url) {
 	return url.searchParams.get("format")?.trim() === "openapi";
 }
-function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp, feedback, llms, sitemap, robots, openapi, publishedSkills = [], agentCard }) {
+function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, contentChanges, mcp, feedback, llms, sitemap, robots, openapi, publishedSkills = [], agentCard }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const localesEnabled = i18n !== null;
 	const searchEnabled = isSearchEnabled(search);
+	const contentChangesEnabled = resolveDocsContentChangesConfig(contentChanges).enabled;
 	const sitemapConfig = resolveDocsSitemapConfig(sitemap, { baseUrl: llms.baseUrl });
 	const robotsEnabled = isRobotsDiscoveryEnabled(robots);
 	const llmsSections = resolveDocsLlmsTxtSections(llms);
@@ -238,6 +239,7 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			skills: true,
 			mcp: mcp.enabled,
 			search: searchEnabled,
+			contentChanges: contentChangesEnabled,
 			sitemap: sitemapConfig.enabled,
 			robots: robotsEnabled,
 			structuredData: true,
@@ -260,6 +262,7 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			agentSpecQuery: `${apiRoute}?agent=spec`,
 			agents: `${apiRoute}?format=agents`,
 			openapi: `${apiRoute}?format=openapi`,
+			...contentChangesEnabled ? { contentChanges: `${apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}` } : {},
 			...apiCatalog ? {
 				apiCatalog: DEFAULT_API_CATALOG_ROUTE,
 				apiCatalogQuery: `${apiRoute}?format=api-catalog`
@@ -394,13 +397,16 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			endpoint: `${apiRoute}?query={query}`,
 			agentEndpoint: `${apiRoute}?query={query}&audience=agent`,
 			structuredAgentEndpoint: `${apiRoute}?query={query}&audience=agent&response=structured`,
+			facetsEndpoint: `${apiRoute}?audience=agent&response=facets`,
 			method: "GET",
 			queryParam: "query",
 			localeParam: "lang",
 			audienceParam: "audience",
 			responseParam: "response",
 			structuredResponseValue: "structured",
+			facetsResponseValue: "facets",
 			responseFormat: "docs-search.v1",
+			facetsResponseFormat: "docs-search-facets.v1",
 			filterParams: {
 				framework: "framework",
 				version: "version",
@@ -414,6 +420,8 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 				"tags"
 			],
 			warningsField: "warnings",
+			facetParam: "facet",
+			limitParam: "limit",
 			cursorParam: "cursor",
 			nextCursorField: "nextCursor",
 			hasMoreField: "hasMore",
@@ -421,6 +429,27 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 			defaultAudience: "human",
 			supportedAudiences: ["human", "agent"]
 		},
+		contentChanges: {
+			enabled: contentChangesEnabled,
+			endpoint: contentChangesEnabled ? `${apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}` : null,
+			method: "GET",
+			audienceParam: "audience",
+			defaultAudience: "agent",
+			supportedAudiences: ["human", "agent"],
+			responseParam: "response",
+			responseValue: DOCS_CONTENT_CHANGES_RESPONSE_VALUE,
+			sinceParam: "since",
+			format: DOCS_CONTENT_CHANGES_FORMAT,
+			generationField: "indexGeneration",
+			resetRequiredField: "resetRequired",
+			modes: [
+				"snapshot",
+				"delta",
+				"reset"
+			],
+			bodyFree: true,
+			etag: true
+		},
 		agents: {
 			enabled: true,
 			file: "AGENTS.md",
@@ -1294,7 +1323,7 @@ function renderMarkdownDocument(page, options = {}) {
 		sitemap: options.sitemap
 	});
 }
-function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, mcp, feedback, llms, sitemap, robots, openapi }) {
+function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, contentChanges, mcp, feedback, llms, sitemap, robots, openapi }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const siteTitle = compactSkillText(llms.siteTitle ?? "Documentation");
 	const siteDescription = llms.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
@@ -1318,7 +1347,8 @@ 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&response=structured when you do not know the page; add framework, version, package, or repeated tags filters when scope matters.`);
+	if (searchEnabled) lines.push(`- Discover valid search filters with ${apiRoute}?audience=agent&response=facets before choosing framework, version, package, or tag values; continue a large field with facet={field}, limit={limit}, and its nextCursor.`, `- 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 (resolveDocsContentChangesConfig(contentChanges).enabled) lines.push(`- Synchronize changed documents with ${apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}; pass indexGeneration as since on the next request and clear stale state when resetRequired is true.`);
 	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.`);
@@ -1354,7 +1384,7 @@ function renderSkillDocument({ origin, entry, apiRoute, apiCatalog, search, mcp,
 	lines.push("", "## Reusable Framework Skills", "For framework setup, CLI, page actions, Ask AI, or configuration work, install the reusable Farming Labs skills:", "", "```sh", "npx skills add farming-labs/docs", "```");
 	return lines.join("\n");
 }
-function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, mcp, feedback, llms, sitemap, robots, openapi }) {
+function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, contentChanges, mcp, feedback, llms, sitemap, robots, openapi }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const siteTitle = compactSkillText(llms.siteTitle ?? "Documentation");
 	const siteDescription = llms.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
@@ -1383,7 +1413,8 @@ 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&response=structured when the route is unknown; add framework, version, package, or repeated tags filters when scope matters.`);
+	if (searchEnabled) lines.push(`- Discover valid search filters with ${apiRoute}?audience=agent&response=facets before choosing framework, version, package, or tag values; continue a large field with facet={field}, limit={limit}, and its nextCursor.`, `- 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 (resolveDocsContentChangesConfig(contentChanges).enabled) lines.push(`- Synchronize changed documents with ${apiRoute}?audience=agent&response=${DOCS_CONTENT_CHANGES_RESPONSE_VALUE}; pass indexGeneration as since on the next request and clear stale state when resetRequired is true.`);
 	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}.`);
@@ -2527,6 +2558,8 @@ function createDocsAPI(options) {
 		apiRoute: configuredApiRoute
 	} : cloudConfig;
 	const searchConfig = options?.search;
+	const contentChangesConfig = resolveDocsContentChangesConfig(options?.agent?.contentChanges, { staticExport: options?.staticExport === true });
+	const contentChangeFeed = createDocsContentChangeFeed(options?.agent?.contentChanges);
 	const llmsConfig = resolveLlmsTxtConfig(options?.llmsTxt, readLlmsTxtConfig(root));
 	const apiCatalogEnabled = options?.apiCatalog ?? llmsConfig.apiCatalog ?? true;
 	const sitemapConfig = options?.sitemap ?? readSitemapConfig(root);
@@ -2559,6 +2592,7 @@ function createDocsAPI(options) {
 		contentDir,
 		telemetry: options?.telemetry,
 		search: searchConfig,
+		agent: options?.agent,
 		ai: aiConfig,
 		cloud: effectiveCloudConfig,
 		i18n: i18nConfig ?? void 0,
@@ -2580,6 +2614,7 @@ function createDocsAPI(options) {
 	setConfigMapFallback("entry", entry);
 	setConfigMapFallback("ai", Object.keys(aiConfig).length > 0 ? aiConfig : void 0);
 	setConfigMapFallback("search", searchConfig);
+	setConfigMapFallback("agent", options?.agent);
 	setConfigMapFallback("i18n", i18nConfig ?? void 0);
 	setConfigMapFallback("mcp", rawMcpConfig);
 	setConfigMapFallback("apiReference", apiReferenceConfig);
@@ -2777,6 +2812,7 @@ function createDocsAPI(options) {
 			apiCatalog: apiCatalogEnabled,
 			i18n,
 			search: searchConfig,
+			contentChanges: contentChangesConfig.enabled,
 			mcp: mcpConfig,
 			feedback: agentFeedbackConfig,
 			llms: llmsConfig,
@@ -2797,6 +2833,7 @@ function createDocsAPI(options) {
 			apiRoute,
 			i18n,
 			search: searchConfig,
+			contentChanges: contentChangesConfig.enabled,
 			mcp: mcpConfig,
 			feedback: agentFeedbackConfig,
 			llms: llmsConfig,
@@ -2862,6 +2899,7 @@ function createDocsAPI(options) {
 					apiCatalog: apiCatalogEnabled,
 					i18n,
 					search: searchConfig,
+					contentChanges: contentChangesConfig.enabled,
 					mcp: mcpConfig,
 					feedback: agentFeedbackConfig,
 					llms: llmsConfig,
@@ -2877,6 +2915,7 @@ function createDocsAPI(options) {
 							apiCatalog: apiCatalogEnabled,
 							i18n,
 							search: searchConfig,
+							contentChanges: contentChangesConfig.enabled,
 							mcp: mcpConfig,
 							feedback: agentFeedbackConfig,
 							llms: llmsConfig,
@@ -2892,6 +2931,23 @@ function createDocsAPI(options) {
 					"X-Robots-Tag": "noindex"
 				} });
 			}
+			if (isDocsContentChangesRequest(url)) {
+				if (!contentChangesConfig.enabled) return new Response("Not Found", {
+					status: 404,
+					headers: {
+						"Content-Type": "text/plain; charset=utf-8",
+						"X-Robots-Tag": "noindex"
+					}
+				});
+				return createDocsContentChangesHttpResponse({
+					request,
+					feed: contentChangeFeed,
+					pages: getIndexes(ctx),
+					search: searchConfig,
+					locale: ctx.locale,
+					baseUrl: markdownMetadataBaseUrl || url.origin
+				});
+			}
 			if (isApiReferenceOpenApiRequest(url)) {
 				if (!openapiDiscovery.enabled) return new Response("Not Found", {
 					status: 404,
@@ -2957,6 +3013,7 @@ function createDocsAPI(options) {
 					apiRoute: requestApiRoute,
 					apiCatalog: apiCatalogEnabled,
 					search: searchConfig,
+					contentChanges: contentChangesConfig.enabled,
 					mcp: mcpConfig,
 					feedback: agentFeedbackConfig,
 					llms: llmsConfig,
@@ -2989,6 +3046,7 @@ function createDocsAPI(options) {
 					apiCatalog: apiCatalogEnabled,
 					i18n,
 					search: searchConfig,
+					contentChanges: contentChangesConfig.enabled,
 					mcp: mcpConfig,
 					feedback: agentFeedbackConfig,
 					llms: llmsConfig,
@@ -3169,8 +3227,8 @@ function createDocsAPI(options) {
 				if (!searchError) throw error;
 				return Response.json({ error: searchError }, { status: 400 });
 			}
-			const { filters, structured, cursor, limit } = searchRequest;
-			if (!query && !structured) return new Response("[]", { headers: { "Content-Type": "application/json" } });
+			const { filters, structured, facets, facet, cursor, limit } = searchRequest;
+			if (!query && !structured && !facets) return new Response("[]", { headers: { "Content-Type": "application/json" } });
 			const searchOptions = {
 				pages: getIndexes(ctx),
 				query: query ?? "",
@@ -3182,20 +3240,22 @@ function createDocsAPI(options) {
 				siteTitle: llmsConfig.siteTitle ?? "Documentation",
 				baseUrl: markdownMetadataBaseUrl || url.origin,
 				syncBaseUrl: markdownMetadataBaseUrl ?? null,
+				facet,
 				cursor,
 				limit
 			};
 			const searchStartedAt = Date.now();
 			let searchResponse;
 			try {
-				searchResponse = structured ? await performDocsSearchWithMetadata(searchOptions) : query ? await performDocsSearch(searchOptions) : [];
+				searchResponse = facets ? await buildDocsSearchFacets(searchOptions) : structured ? await performDocsSearchWithMetadata(searchOptions) : query ? await performDocsSearch(searchOptions) : [];
 			} catch (error) {
 				const searchError = resolveDocsSearchError(error);
 				if (!searchError) throw error;
 				return Response.json({ error: searchError }, { status: 400 });
 			}
+			if (facets) return Response.json(searchResponse, { headers: { "Cache-Control": "public, max-age=60, stale-while-revalidate=300" } });
 			if (!query) return Response.json(searchResponse);
-			const resultCount = Array.isArray(searchResponse) ? searchResponse.length : searchResponse.resultCount;
+			const resultCount = Array.isArray(searchResponse) ? searchResponse.length : "resultCount" in searchResponse ? searchResponse.resultCount : searchResponse.matchedPageCount;
 			await emitDocsAnalyticsEvent(analytics, {
 				type: "api_search",
 				source: "server",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.2.77",
+  "version": "0.2.78",
   "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.77"
+    "@farming-labs/docs": "0.2.78"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",