@farming-labs/theme 0.2.72 → 0.2.74

package/dist/docs-api.d.mts

@@ -87,6 +87,8 @@ interface DocsMCPAPIOptions {
   rootDir?: string;
   entry?: string;
   contentDir?: string;
+  /** Canonical public docs origin used in retrieval provenance. */
+  baseUrl?: string;
   nav?: {
     title?: unknown;
   };

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, 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 { 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, 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
@@ -223,7 +223,7 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, mcp
 	return {
 		$schema: DOCS_AGENT_MANIFEST_SCHEMA_URI,
 		format: DOCS_AGENT_MANIFEST_FORMAT,
-		version: "1",
+		version: DOCS_AGENT_MANIFEST_VERSION,
 		name: "@farming-labs/docs",
 		baseUrl: origin,
 		site: {
@@ -970,12 +970,17 @@ function readAudienceAgentDoc(dir) {
 		const agentRawContent = resolveDocsAudienceMdxContent(content, "agent");
 		return {
 			agentContent: stripMdx(agentRawContent),
-			agentRawContent
+			agentRawContent,
+			agentLastModified: fs.statSync(agentPath).mtime.toISOString()
 		};
 	} catch {
 		return;
 	}
 }
+function normalizeFrontmatterLastmod(value) {
+	if (typeof value === "string") return value;
+	return value instanceof Date && Number.isFinite(value.getTime()) ? value.toISOString() : void 0;
+}
 function scanDocsDir(docsDir, entry, locale, excludedDirs = [], publicPath = `/${normalizePathSegment(entry) || "docs"}`) {
 	const indexes = [];
 	function isExcluded(dir) {
@@ -1014,6 +1019,7 @@ function scanDocsDir(docsDir, entry, locale, excludedDirs = [], publicPath = `/$
 					agentFallbackRawContent: agentRawContent !== rawContent ? agentRawContent : void 0,
 					url,
 					sourcePath: pageSource.replace(/\\/g, "/"),
+					lastmod: normalizeFrontmatterLastmod(data.lastmod),
 					lastModified: fs.statSync(pageSource).mtime.toISOString(),
 					locale,
 					framework,
@@ -1080,6 +1086,9 @@ function scanChangelogDir(changelogDir, entryPath, changelogPath, locale, public
 				rawContent,
 				agentFallbackRawContent: agentRawContent !== rawContent ? agentRawContent : void 0,
 				url,
+				sourcePath: pagePath.replace(/\\/g, "/"),
+				lastmod: normalizeFrontmatterLastmod(data.lastmod),
+				lastModified: fs.statSync(pagePath).mtime.toISOString(),
 				locale,
 				type: "changelog",
 				version: typeof data.version === "string" ? data.version : void 0,
@@ -2038,7 +2047,8 @@ async function handleAskAI(request, indexes, aiConfig, cloudConfig, search, anal
 		locale: analyticsContext.locale,
 		pathname: url.searchParams.get("pathname") ?? void 0,
 		siteTitle: "Documentation",
-		baseUrl: url.origin,
+		baseUrl: analyticsContext.syncBaseUrl || url.origin,
+		syncBaseUrl: analyticsContext.syncBaseUrl,
 		limit: maxResults
 	});
 	const scored = retrieval.results;
@@ -2716,7 +2726,7 @@ function createDocsAPI(options) {
 					origin,
 					sitemap: sitemapConfig
 				}),
-				lastModified: page.agentRawContent === void 0 ? page.lastModified : void 0
+				lastModified: resolveDocsRetrievalLastModified(page, "agent")
 			};
 		}
 		const fallbackPage = getIndexes(ctx).find((page) => {
@@ -2729,7 +2739,7 @@ function createDocsAPI(options) {
 				origin,
 				sitemap: sitemapConfig
 			}),
-			lastModified: fallbackPage.agentRawContent === void 0 ? fallbackPage.lastModified : void 0
+			lastModified: resolveDocsRetrievalLastModified(fallbackPage, "agent")
 		};
 		const requestedSlug = normalizePublicDocsSlug(ctx, normalizedPublicRequest);
 		for (const page of getIndexes(ctx)) if (normalizePublicDocsSlug(ctx, page.url) === requestedSlug) return {
@@ -2738,7 +2748,7 @@ function createDocsAPI(options) {
 				origin,
 				sitemap: sitemapConfig
 			}),
-			lastModified: page.agentRawContent === void 0 ? page.lastModified : void 0
+			lastModified: resolveDocsRetrievalLastModified(page, "agent")
 		};
 		return null;
 	}
@@ -3157,30 +3167,24 @@ function createDocsAPI(options) {
 			const audience = resolveDocsSearchAudience(url.searchParams.get("audience"));
 			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();
+			if (!query && !structured) return new Response("[]", { headers: { "Content-Type": "application/json" } });
 			const searchOptions = {
 				pages: getIndexes(ctx),
-				query,
+				query: 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
+				baseUrl: markdownMetadataBaseUrl || url.origin,
+				syncBaseUrl: markdownMetadataBaseUrl ?? null
 			};
+			if (!query) {
+				const searchResponse = structured ? await performDocsSearchWithMetadata(searchOptions) : [];
+				return new Response(JSON.stringify(searchResponse), { headers: { "Content-Type": "application/json" } });
+			}
+			const searchStartedAt = Date.now();
 			const searchResponse = structured ? await performDocsSearchWithMetadata(searchOptions) : await performDocsSearch(searchOptions);
 			const resultCount = Array.isArray(searchResponse) ? searchResponse.length : searchResponse.resultCount;
 			await emitDocsAnalyticsEvent(analytics, {
@@ -3299,7 +3303,10 @@ function createDocsAPI(options) {
 				mcpEnabled: mcpConfig.enabled,
 				mcpSearchEnabled: mcpConfig.tools.searchDocs,
 				requestUrl: request.url
-			}), analytics, observability, { locale: ctx.locale });
+			}), analytics, observability, {
+				locale: ctx.locale,
+				syncBaseUrl: markdownMetadataBaseUrl ?? null
+			});
 		}
 	};
 	return {
@@ -3342,6 +3349,7 @@ function createDocsMCPAPI(options = {}) {
 				entry,
 				contentDir,
 				siteTitle: navTitle,
+				baseUrl: options.baseUrl?.trim() || resolveDocsMetadataBaseUrl(options) || void 0,
 				ordering: options.ordering
 			}),
 			async getSkills() {

package/package.json

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