@farming-labs/theme 0.1.99 → 0.1.100

package/dist/docs-api.d.mts

@@ -1,4 +1,4 @@
-import { ChangelogConfig, DocsAnalyticsConfig, DocsAskAIMcpConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsRobotsConfig, DocsSearchConfig, DocsSitemapConfig, FeedbackConfig, LlmsTxtConfig, OrderingItem } from "@farming-labs/docs";
+import { ChangelogConfig, DocsAnalyticsConfig, DocsAskAIMcpConfig, DocsConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsRobotsConfig, DocsSearchConfig, DocsSitemapConfig, FeedbackConfig, LlmsTxtConfig, OrderingItem } from "@farming-labs/docs";
 
 //#region src/docs-api.d.ts
 interface AIProviderConfig {
@@ -60,6 +60,10 @@ interface DocsAPIOptions {
   sitemap?: boolean | DocsSitemapConfig;
   /** Robots.txt generation policy used for the agent discovery spec. */
   robots?: boolean | DocsRobotsConfig;
+  /** API reference / OpenAPI schema configuration used for agent discovery. */
+  apiReference?: DocsConfig["apiReference"];
+  /** Metadata used in generated OpenAPI documents. */
+  metadata?: DocsConfig["metadata"];
 }
 interface DocsMCPAPIOptions {
   rootDir?: string;

package/dist/docs-api.mjs

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
 import { buildDocsAskAIContext, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsRobotsResponse, createDocsSitemapResponse, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, formatDocsAskAIPackageHints, getDocsLlmsTxtMaxCharsIssue, getDocsMarkdownCanonicalLinkHeader, getDocsMarkdownVaryHeader, hasDocsMarkdownSignatureAgent, normalizeDocsRelated, performDocsSearch, renderDocsLlmsTxt, renderDocsMarkdownNotFound, renderDocsRelatedMarkdownLines, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsSitemapConfig, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent } from "@farming-labs/docs";
-import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveDocsMcpConfig } from "@farming-labs/docs/server";
+import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceConfig, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
 /**
@@ -181,7 +181,21 @@ function isRobotsDiscoveryEnabled(robots) {
 	if (robots && typeof robots === "object" && robots.enabled === false) return false;
 	return true;
 }
-function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, sitemap, robots }) {
+function isApiReferenceOpenApiRequest(url) {
+	return url.searchParams.get("format")?.trim() === "openapi";
+}
+function resolveApiReferenceOpenApiDiscovery(value) {
+	const apiReference = resolveApiReferenceConfig(value);
+	if (!apiReference.enabled) return { enabled: false };
+	return {
+		enabled: true,
+		url: `${DEFAULT_DOCS_API_ROUTE}?format=openapi`,
+		source: apiReference.specUrl ? "configured" : "generated",
+		specUrl: apiReference.specUrl,
+		apiReferencePath: `/${apiReference.path}`
+	};
+}
+function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, sitemap, robots, openapi }) {
 	const normalizedEntry = normalizePathSegment(entry) || "docs";
 	const localesEnabled = i18n !== null;
 	const searchEnabled = isSearchEnabled(search);
@@ -216,6 +230,8 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			sitemap: sitemapConfig.enabled,
 			robots: robotsEnabled,
 			structuredData: true,
+			apiReference: openapi.enabled,
+			openapi: openapi.enabled,
 			agentFeedback: feedback.enabled,
 			locales: localesEnabled
 		},
@@ -226,7 +242,8 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			agentSpecFallback: DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE,
 			agentSpecWellKnown: DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE,
 			agentSpecWellKnownJson: DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE,
-			agentSpecQuery: `${DEFAULT_DOCS_API_ROUTE}?agent=spec`
+			agentSpecQuery: `${DEFAULT_DOCS_API_ROUTE}?agent=spec`,
+			openapi: `${DEFAULT_DOCS_API_ROUTE}?format=openapi`
 		},
 		markdown: {
 			enabled: true,
@@ -291,6 +308,14 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 			canonicalUrlField: "url",
 			breadcrumbType: "BreadcrumbList"
 		},
+		openapi: {
+			enabled: openapi.enabled,
+			url: openapi.url ?? null,
+			source: openapi.source ?? null,
+			specUrl: openapi.specUrl ?? null,
+			apiReferencePath: openapi.apiReferencePath ?? null,
+			format: "OpenAPI 3.1"
+		},
 		search: {
 			enabled: searchEnabled,
 			endpoint: `${DEFAULT_DOCS_API_ROUTE}?query={query}`,
@@ -334,6 +359,7 @@ function buildAgentSpec({ origin, entry, i18n, search, mcp, feedback, llms, site
 		instructions: {
 			preferMarkdownRoutes: true,
 			useMcpWhenAvailable: true,
+			useOpenApiWhenAvailable: true,
 			readFeedbackSchemaBeforeSubmitting: true,
 			doNotAssumeFeedbackPayloadShape: true
 		}
@@ -948,7 +974,7 @@ function renderMarkdownDocument(page, options = {}) {
 	lines.push("", page.agentFallbackRawContent ?? page.rawContent ?? page.content);
 	return lines.join("\n");
 }
-function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitemap, robots }) {
+function renderSkillDocument({ origin, entry, search, 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;
@@ -969,6 +995,7 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitem
 	if (siteDescription) lines.push(`Description: ${siteDescription}`);
 	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 ${DEFAULT_AGENT_SPEC_ROUTE}.`, `- Fetch /${normalizedEntry}.md for the root docs page.`, `- Fetch /${normalizedEntry}/{slug}.md for page-specific context.`, "- You can also request text/markdown from normal page URLs.");
 	if (searchEnabled) lines.push(`- Search with ${DEFAULT_DOCS_API_ROUTE}?query={query} when you do not know the page.`);
+	if (openapi.enabled && openapi.url) lines.push(`- Fetch ${openapi.url} 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.`);
 		for (const section of llmsSections) lines.push(`- Use ${section.route} for the ${section.title} llms.txt section.`);
@@ -989,6 +1016,10 @@ function renderSkillDocument({ origin, entry, search, mcp, feedback, llms, sitem
 			lines.push(`- ${section.title} llms-full.txt: ${section.fullRoute}`);
 		}
 	}
+	if (openapi.enabled && openapi.url) {
+		lines.push(`- OpenAPI schema: ${openapi.url}`);
+		if (openapi.apiReferencePath) lines.push(`- API reference: ${openapi.apiReferencePath}`);
+	}
 	if (sitemapConfig.enabled) {
 		if (sitemapConfig.xml.enabled) lines.push(`- Sitemap XML: ${sitemapConfig.xml.route}`);
 		if (sitemapConfig.markdown.enabled) lines.push(`- Sitemap Markdown: ${sitemapConfig.markdown.route}`, `- Sitemap well-known alias: ${sitemapConfig.markdown.wellKnownRoute}`);
@@ -1597,6 +1628,37 @@ function readRobotsConfig(root) {
 		}
 	}
 }
+function readApiReferenceConfig(root) {
+	for (const ext of FILE_EXTS) {
+		const configPath = path.join(root, `docs.config.${ext}`);
+		if (!fs.existsSync(configPath)) continue;
+		try {
+			const content = fs.readFileSync(configPath, "utf-8");
+			if (!content.includes("apiReference")) return void 0;
+			if (/apiReference\s*:\s*false/.test(content)) return false;
+			if (/apiReference\s*:\s*true/.test(content)) return true;
+			const block = content.match(/apiReference\s*:\s*\{([\s\S]*?)\n\s*\}/)?.[1] ?? "";
+			const enabledMatch = block.match(/enabled\s*:\s*(true|false)/);
+			const pathMatch = block.match(/path\s*:\s*["']([^"']+)["']/);
+			const routeRootMatch = block.match(/routeRoot\s*:\s*["']([^"']+)["']/);
+			const specUrlMatch = block.match(/specUrl\s*:\s*["']([^"']+)["']/);
+			const rendererMatch = block.match(/renderer\s*:\s*["'](fumadocs|scalar)["']/);
+			const excludeMatch = block.match(/exclude\s*:\s*\[([\s\S]*?)\]/);
+			const exclude = excludeMatch?.[1] === void 0 ? void 0 : Array.from(excludeMatch[1].matchAll(/["']([^"']+)["']/g)).map((match) => match[1]).filter(Boolean);
+			const renderer = rendererMatch?.[1] === "fumadocs" || rendererMatch?.[1] === "scalar" ? rendererMatch[1] : void 0;
+			return {
+				enabled: enabledMatch ? enabledMatch[1] === "true" : true,
+				path: pathMatch?.[1],
+				routeRoot: routeRootMatch?.[1],
+				specUrl: specUrlMatch?.[1],
+				renderer,
+				exclude
+			};
+		} catch {
+			return;
+		}
+	}
+}
 function generateLlmsTxt(indexes, options) {
 	return renderDocsLlmsTxt(indexes, options);
 }
@@ -1639,6 +1701,13 @@ function createDocsAPI(options) {
 	const llmsConfig = resolveLlmsTxtConfig(options?.llmsTxt, readLlmsTxtConfig(root));
 	const sitemapConfig = options?.sitemap ?? readSitemapConfig(root);
 	const robotsConfig = options?.robots ?? readRobotsConfig(root);
+	const apiReferenceConfig = options?.apiReference ?? readApiReferenceConfig(root);
+	const apiReferenceDocsConfig = {
+		...options,
+		entry,
+		apiReference: apiReferenceConfig
+	};
+	const openapiDiscovery = resolveApiReferenceOpenApiDiscovery(apiReferenceConfig);
 	const mcpConfig = resolveDocsMcpConfig(options?.mcp ?? readMcpConfig(root), { defaultName: llmsConfig.siteTitle ?? "Documentation" });
 	function resolveDocsDirCandidates(locale) {
 		const relativeCandidates = /* @__PURE__ */ new Set();
@@ -1755,7 +1824,8 @@ function createDocsAPI(options) {
 			siteDescription: llmsConfig.siteDescription,
 			baseUrl: llmsConfig.baseUrl ?? "",
 			maxChars: llmsConfig.maxChars,
-			sections: llmsConfig.sections
+			sections: llmsConfig.sections,
+			openapi: openapiDiscovery
 		});
 		llmsCacheByLocale.set(key, next);
 		return next;
@@ -1782,12 +1852,32 @@ function createDocsAPI(options) {
 					feedback: agentFeedbackConfig,
 					llms: llmsConfig,
 					sitemap: sitemapConfig,
-					robots: robotsConfig
+					robots: robotsConfig,
+					openapi: openapiDiscovery
 				}), { headers: {
 					"Cache-Control": "public, max-age=0, s-maxage=3600",
 					"X-Robots-Tag": "noindex"
 				} });
 			}
+			if (isApiReferenceOpenApiRequest(url)) {
+				if (!openapiDiscovery.enabled) return new Response("Not Found", {
+					status: 404,
+					headers: {
+						"Content-Type": "text/plain; charset=utf-8",
+						"X-Robots-Tag": "noindex"
+					}
+				});
+				const document = await buildApiReferenceOpenApiDocumentAsync(apiReferenceDocsConfig, {
+					framework: "next",
+					rootDir: root,
+					baseUrl: url.origin
+				});
+				return new Response(JSON.stringify(document, null, 2), { headers: {
+					"Content-Type": "application/json; charset=utf-8",
+					"Cache-Control": "public, max-age=0, s-maxage=3600",
+					"X-Robots-Tag": "noindex"
+				} });
+			}
 			const agentFeedbackRequest = resolveAgentFeedbackRequest(url, agentFeedbackConfig);
 			if (agentFeedbackRequest) {
 				if (agentFeedbackRequest.kind === "submit") return Response.json({ error: "Method Not Allowed" }, {
@@ -1826,7 +1916,8 @@ function createDocsAPI(options) {
 					feedback: agentFeedbackConfig,
 					llms: llmsConfig,
 					sitemap: sitemapConfig,
-					robots: robotsConfig
+					robots: robotsConfig,
+					openapi: openapiDiscovery
 				}), { headers: {
 					"Content-Type": "text/markdown; charset=utf-8",
 					"Cache-Control": "public, max-age=0, s-maxage=3600",

package/package.json

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