@farming-labs/theme 0.2.84 → 0.2.87

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_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 { 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, createDocsCacheableResponse, 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
@@ -1441,25 +1441,36 @@ function renderAgentsDocument({ origin, entry, apiRoute, apiCatalog, search, con
 	lines.push("", "## Framework Maintenance", "- For @farming-labs/docs projects, keep the framework package current before debugging missing agent surfaces.", "", "```sh", "npx @farming-labs/docs@latest upgrade --latest", "```", "", "- For framework setup, configuration, CLI, Ask AI, page actions, or theme work, install the reusable Skills pack:", "", "```sh", "npx skills add farming-labs/docs", "```");
 	return lines.join("\n");
 }
-function readRootSkillDocument(rootDir) {
-	const candidate = path.join(rootDir, "skill.md");
-	try {
-		if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return fs.readFileSync(candidate, "utf-8");
-	} catch {
-		return null;
-	}
-	return null;
-}
-function readRootAgentsDocument(rootDir) {
-	for (const fileName of ["AGENTS.md", "AGENT.md"]) {
-		const candidate = path.join(rootDir, fileName);
-		try {
-			if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return fs.readFileSync(candidate, "utf-8");
-		} catch {
-			continue;
+function createRootDocumentReader(rootDir, fileNames) {
+	let cached;
+	return function readRootDocument() {
+		for (const fileName of fileNames) {
+			const candidate = path.join(rootDir, fileName);
+			try {
+				const stats = fs.statSync(candidate);
+				if (!stats.isFile()) continue;
+				const signature = [
+					stats.dev,
+					stats.ino,
+					stats.size,
+					stats.mtimeMs,
+					stats.ctimeMs
+				].join(":");
+				if (cached?.path === candidate && cached.signature === signature) return cached.content;
+				const content = fs.readFileSync(candidate, "utf-8");
+				cached = {
+					path: candidate,
+					signature,
+					content
+				};
+				return content;
+			} catch {
+				continue;
+			}
 		}
-	}
-	return null;
+		cached = void 0;
+		return null;
+	};
 }
 function compactSkillText(value) {
 	return value.replace(/\s+/g, " ").trim();
@@ -2534,6 +2545,8 @@ function generateLlmsTxt(indexes, options) {
 */
 function createDocsAPI(options) {
 	const root = options?.rootDir ?? process.cwd();
+	const readRootSkillDocument = createRootDocumentReader(root, ["skill.md"]);
+	const readRootAgentsDocument = createRootDocumentReader(root, ["AGENTS.md", "AGENT.md"]);
 	let publishedAgentSkills;
 	function getPublishedAgentSkills() {
 		if (!publishedAgentSkills) publishedAgentSkills = Array.isArray(options?._preloadedAgentSkills) ? Promise.resolve([...options._preloadedAgentSkills]) : resolveConfiguredAgentSkills(options?.agent?.skills, { rootDir: root });
@@ -2711,6 +2724,8 @@ function createDocsAPI(options) {
 	}
 	const indexesByLocale = /* @__PURE__ */ new Map();
 	const llmsCache = new BoundedRouteCache(MAX_LLMS_CACHE_ROUTES_PER_LOCALE);
+	const generatedAgentsCache = new BoundedRouteCache(MAX_LLMS_CACHE_ROUTES_PER_LOCALE);
+	const generatedSkillCache = new BoundedRouteCache(MAX_LLMS_CACHE_ROUTES_PER_LOCALE);
 	const markdownSourcesByLocale = /* @__PURE__ */ new Map();
 	function getIndexes(ctx) {
 		const key = ctx.locale ?? "__default__";
@@ -2799,14 +2814,33 @@ function createDocsAPI(options) {
 		llmsCache.set(ctx.locale, apiRoute, next);
 		return next;
 	}
-	async function resolveStandardsResponse(request, url) {
-		const apiRoute = resolveDocsRequestApiRoute(url, configuredApiRouteInput);
-		const resolved = resolveDocsStandardsDiscoveryRequest(url, { apiRoute });
-		if (!resolved) return null;
-		const method = request.method.toUpperCase();
-		const needsSkill = (method === "GET" || method === "HEAD") && resolved.kind !== "api-catalog";
-		const fallbackSkillDocument = needsSkill ? renderSkillDocument({
-			origin: url.origin,
+	function getGeneratedAgentsDocument(origin, apiRoute) {
+		const cacheKey = `${origin}\0${apiRoute}`;
+		const cached = generatedAgentsCache.get(void 0, cacheKey);
+		if (cached) return cached;
+		const next = renderAgentsDocument({
+			origin,
+			entry,
+			apiRoute,
+			apiCatalog: apiCatalogEnabled,
+			search: searchConfig,
+			contentChanges: contentChangesConfig.enabled,
+			mcp: mcpConfig,
+			feedback: agentFeedbackConfig,
+			llms: llmsConfig,
+			sitemap: sitemapConfig,
+			robots: robotsConfig,
+			openapi: openapiDiscovery
+		});
+		generatedAgentsCache.set(void 0, cacheKey, next);
+		return next;
+	}
+	function getGeneratedSkillDocument(origin, apiRoute) {
+		const cacheKey = `${origin}\0${apiRoute}`;
+		const cached = generatedSkillCache.get(void 0, cacheKey);
+		if (cached) return cached;
+		const next = renderSkillDocument({
+			origin,
 			entry,
 			apiRoute,
 			apiCatalog: apiCatalogEnabled,
@@ -2819,10 +2853,20 @@ function createDocsAPI(options) {
 			sitemap: sitemapConfig,
 			robots: robotsConfig,
 			openapi: openapiDiscovery
-		}) : "";
+		});
+		generatedSkillCache.set(void 0, cacheKey, next);
+		return next;
+	}
+	async function resolveStandardsResponse(request, url) {
+		const apiRoute = resolveDocsRequestApiRoute(url, configuredApiRouteInput);
+		const resolved = resolveDocsStandardsDiscoveryRequest(url, { apiRoute });
+		if (!resolved) return null;
+		const method = request.method.toUpperCase();
+		const needsSkill = (method === "GET" || method === "HEAD") && resolved.kind !== "api-catalog";
+		const fallbackSkillDocument = needsSkill ? getGeneratedSkillDocument(url.origin, apiRoute) : "";
 		return createDocsStandardsDiscoveryResponse({
 			request,
-			preferredSkillDocument: needsSkill ? readRootSkillDocument(root) : null,
+			preferredSkillDocument: needsSkill ? readRootSkillDocument() : null,
 			fallbackSkillDocument,
 			publishedSkills: needsSkill ? await getPublishedAgentSkills() : [],
 			agentCard: options?.agent?.a2a,
@@ -2886,50 +2930,35 @@ function createDocsAPI(options) {
 						method: requestMethod
 					}
 				});
-				if (isHeadRequest) return new Response(null, { headers: {
-					"Content-Type": "application/json",
-					"Cache-Control": "public, max-age=0, s-maxage=3600",
-					Link: agentManifestLinkHeader,
-					"X-Robots-Tag": "noindex"
-				} });
-				return Response.json(buildAgentSpec({
-					origin: url.origin,
-					entry,
-					apiRoute: requestApiRoute,
-					apiCatalog: apiCatalogEnabled,
-					i18n,
-					search: searchConfig,
-					contentChanges: contentChangesConfig.enabled,
-					mcp: mcpConfig,
-					feedback: agentFeedbackConfig,
-					llms: llmsConfig,
-					sitemap: sitemapConfig,
-					robots: robotsConfig,
-					openapi: openapiDiscovery,
-					publishedSkills: [await resolveDocsPublishedAgentSkill({
-						preferredDocument: readRootSkillDocument(root),
-						fallbackDocument: renderSkillDocument({
-							origin: url.origin,
-							entry,
-							apiRoute: requestApiRoute,
-							apiCatalog: apiCatalogEnabled,
-							i18n,
-							search: searchConfig,
-							contentChanges: contentChangesConfig.enabled,
-							mcp: mcpConfig,
-							feedback: agentFeedbackConfig,
-							llms: llmsConfig,
-							sitemap: sitemapConfig,
-							robots: robotsConfig,
-							openapi: openapiDiscovery
-						})
-					}), ...await getPublishedAgentSkills()],
-					agentCard: options?.agent?.a2a
-				}), { headers: {
-					"Cache-Control": "public, max-age=0, s-maxage=3600",
-					Link: agentManifestLinkHeader,
-					"X-Robots-Tag": "noindex"
-				} });
+				return createDocsCacheableResponse({
+					request,
+					content: `${JSON.stringify(buildAgentSpec({
+						origin: url.origin,
+						entry,
+						apiRoute: requestApiRoute,
+						apiCatalog: apiCatalogEnabled,
+						i18n,
+						search: searchConfig,
+						contentChanges: contentChangesConfig.enabled,
+						mcp: mcpConfig,
+						feedback: agentFeedbackConfig,
+						llms: llmsConfig,
+						sitemap: sitemapConfig,
+						robots: robotsConfig,
+						openapi: openapiDiscovery,
+						publishedSkills: [await resolveDocsPublishedAgentSkill({
+							preferredDocument: readRootSkillDocument(),
+							fallbackDocument: getGeneratedSkillDocument(url.origin, requestApiRoute)
+						}), ...await getPublishedAgentSkills()],
+						agentCard: options?.agent?.a2a
+					}), null, 2)}\n`,
+					headers: {
+						"Content-Type": "application/json; charset=utf-8",
+						"Cache-Control": "public, max-age=0, s-maxage=3600",
+						Link: agentManifestLinkHeader,
+						"X-Robots-Tag": "noindex"
+					}
+				});
 			}
 			if (isDocsContentChangesRequest(url)) {
 				if (!contentChangesConfig.enabled) return new Response("Not Found", {
@@ -3007,25 +3036,16 @@ function createDocsAPI(options) {
 						method: requestMethod
 					}
 				});
-				return new Response(isHeadRequest ? null : readRootAgentsDocument(root) ?? renderAgentsDocument({
-					origin: url.origin,
-					entry,
-					apiRoute: requestApiRoute,
-					apiCatalog: apiCatalogEnabled,
-					search: searchConfig,
-					contentChanges: contentChangesConfig.enabled,
-					mcp: mcpConfig,
-					feedback: agentFeedbackConfig,
-					llms: llmsConfig,
-					sitemap: sitemapConfig,
-					robots: robotsConfig,
-					openapi: openapiDiscovery
-				}), { headers: {
-					"Content-Type": "text/markdown; charset=utf-8",
-					"Cache-Control": "public, max-age=0, s-maxage=3600",
-					Link: discoveryLinkHeader,
-					"X-Robots-Tag": "noindex"
-				} });
+				return createDocsCacheableResponse({
+					request,
+					content: readRootAgentsDocument() ?? getGeneratedAgentsDocument(url.origin, requestApiRoute),
+					headers: {
+						"Content-Type": "text/markdown; charset=utf-8",
+						"Cache-Control": "public, max-age=0, s-maxage=3600",
+						Link: discoveryLinkHeader,
+						"X-Robots-Tag": "noindex"
+					}
+				});
 			}
 			if (resolveSkillRequest(url)) {
 				await emitDocsAnalyticsEvent(analytics, {
@@ -3039,26 +3059,16 @@ function createDocsAPI(options) {
 						method: requestMethod
 					}
 				});
-				return new Response(isHeadRequest ? null : readRootSkillDocument(root) ?? renderSkillDocument({
-					origin: url.origin,
-					entry,
-					apiRoute: requestApiRoute,
-					apiCatalog: apiCatalogEnabled,
-					i18n,
-					search: searchConfig,
-					contentChanges: contentChangesConfig.enabled,
-					mcp: mcpConfig,
-					feedback: agentFeedbackConfig,
-					llms: llmsConfig,
-					sitemap: sitemapConfig,
-					robots: robotsConfig,
-					openapi: openapiDiscovery
-				}), { headers: {
-					"Content-Type": "text/markdown; charset=utf-8",
-					"Cache-Control": "public, max-age=0, s-maxage=3600",
-					Link: discoveryLinkHeader,
-					"X-Robots-Tag": "noindex"
-				} });
+				return createDocsCacheableResponse({
+					request,
+					content: readRootSkillDocument() ?? getGeneratedSkillDocument(url.origin, requestApiRoute),
+					headers: {
+						"Content-Type": "text/markdown; charset=utf-8",
+						"Cache-Control": "public, max-age=0, s-maxage=3600",
+						Link: discoveryLinkHeader,
+						"X-Robots-Tag": "noindex"
+					}
+				});
 			}
 			const robotsResponse = createDocsRobotsResponse({
 				agentCard: Boolean(options?.agent?.a2a),
@@ -3212,10 +3222,14 @@ function createDocsAPI(options) {
 						contentLength: selected.content.length
 					}
 				});
-				return new Response(selected.content, { headers: {
-					"Content-Type": "text/plain; charset=utf-8",
-					"Cache-Control": "public, max-age=3600"
-				} });
+				return createDocsCacheableResponse({
+					request,
+					content: selected.content,
+					headers: {
+						"Content-Type": "text/plain; charset=utf-8",
+						"Cache-Control": "public, max-age=3600"
+					}
+				});
 			}
 			const query = url.searchParams.get("query")?.trim();
 			const audience = resolveDocsSearchAudience(url.searchParams.get("audience"));
@@ -3402,6 +3416,7 @@ function createDocsAPI(options) {
 */
 function createDocsMCPAPI(options = {}) {
 	const rootDir = options.rootDir ?? process.cwd();
+	const readRootSkillDocument = createRootDocumentReader(rootDir, ["skill.md"]);
 	const entry = options.entry ?? readEntry(rootDir);
 	const appDir = getNextAppDir(rootDir);
 	const contentDir = options.contentDir ?? path.join(appDir, entry);
@@ -3426,7 +3441,7 @@ function createDocsMCPAPI(options = {}) {
 			async getSkills() {
 				const configured = await getConfiguredAgentSkills();
 				return [await resolveDocsPublishedAgentSkill({
-					preferredDocument: readRootSkillDocument(rootDir),
+					preferredDocument: readRootSkillDocument(),
 					fallbackDocument: `---\nname: docs\ndescription: Use the project documentation through MCP resources and tools.\n---\n\n# Documentation\n`
 				}), ...configured];
 			}

package/package.json

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