@farming-labs/docs 0.2.120 → 0.2.121

package/dist/mcp-auth.d.mts

@@ -0,0 +1,14 @@
+import { DocsMcpConfig } from "./types.mjs";
+
+//#region src/mcp-auth.d.ts
+declare const DEFAULT_MCP_ROUTE = "/api/docs/mcp";
+declare const DEFAULT_MCP_PUBLIC_ROUTE = "/mcp";
+declare const DEFAULT_MCP_WELL_KNOWN_ROUTE = "/.well-known/mcp";
+declare const DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE = "/.well-known/oauth-protected-resource";
+declare function getDocsMcpResourcePaths(route?: string): string[];
+declare function buildDocsMcpProtectedResourceMetadataRoute(resourcePath: string): string;
+declare function getDocsMcpProtectedResourceMetadataRoutes(route?: string): string[];
+declare function hasDocsMcpProtectedResourceConfig(mcp?: boolean | DocsMcpConfig): boolean;
+declare function isDocsMcpRequest(url: URL, mcp?: boolean | DocsMcpConfig): boolean;
+//#endregion
+export { DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE, DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE, buildDocsMcpProtectedResourceMetadataRoute, getDocsMcpProtectedResourceMetadataRoutes, getDocsMcpResourcePaths, hasDocsMcpProtectedResourceConfig, isDocsMcpRequest };

package/dist/mcp-auth.mjs

@@ -0,0 +1,99 @@
+//#region src/mcp-auth.ts
+const DEFAULT_MCP_ROUTE = "/api/docs/mcp";
+const DEFAULT_MCP_PUBLIC_ROUTE = "/mcp";
+const DEFAULT_MCP_WELL_KNOWN_ROUTE = "/.well-known/mcp";
+const DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE = "/.well-known/oauth-protected-resource";
+function normalizeDocsMcpEndpointPath(route, fallback = DEFAULT_MCP_ROUTE) {
+	const normalized = `/${route?.trim().split(/[?#]/, 1)[0] || fallback}`.replace(/\/+/g, "/");
+	return normalized !== "/" ? normalized.replace(/\/+$/, "") : fallback;
+}
+function getDocsMcpResourcePaths(route) {
+	return Array.from(new Set([
+		normalizeDocsMcpEndpointPath(route),
+		DEFAULT_MCP_PUBLIC_ROUTE,
+		DEFAULT_MCP_WELL_KNOWN_ROUTE
+	]));
+}
+function buildDocsMcpProtectedResourceMetadataRoute(resourcePath) {
+	const candidate = resourcePath.trim().split(/[?#]/, 1)[0] || "/";
+	const trailingSlash = candidate.length > 1 && candidate.endsWith("/");
+	const normalized = candidate === "/" ? "/" : normalizeDocsMcpEndpointPath(candidate);
+	return normalized === "/" ? DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE : `${DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE}${normalized}${trailingSlash ? "/" : ""}`;
+}
+function getDocsMcpProtectedResourceMetadataRoutes(route) {
+	return getDocsMcpResourcePaths(route).map(buildDocsMcpProtectedResourceMetadataRoute);
+}
+function hasDocsMcpProtectedResourceConfig(mcp) {
+	if (!mcp || typeof mcp !== "object" || mcp.enabled === false || typeof mcp.security?.authenticate !== "function") return false;
+	return normalizeDocsMcpAuthorizationServerUrls(mcp.security?.protectedResource?.authorizationServers).length > 0;
+}
+function normalizeDocsMcpAuthorizationServerUrls(values) {
+	if (!Array.isArray(values)) return [];
+	return Array.from(new Set(values.filter((value) => typeof value === "string").map((value) => value.trim()).filter(isAbsoluteHttpUrl)));
+}
+function isDocsMcpOAuthScopeToken(value) {
+	return typeof value === "string" && /^[\x21\x23-\x5B\x5D-\x7E]+$/u.test(value);
+}
+function isDocsMcpRequest(url, mcp) {
+	const route = typeof mcp === "object" ? mcp.route : void 0;
+	if (isDocsMcpResourcePath(url.pathname, route)) return true;
+	return hasDocsMcpProtectedResourceConfig(mcp) && isDocsMcpProtectedResourceMetadataRequestPath(url.pathname, route);
+}
+function isDocsMcpResourcePath(pathname, route) {
+	return isCanonicalResourcePath(pathname, getDocsMcpResourcePaths(route));
+}
+function resolveDocsMcpResourceLocation(request, route) {
+	const requestUrl = new URL(request.url);
+	const allowedPaths = getDocsMcpResourcePaths(route);
+	const normalizedRequestPath = normalizeRequestPath(requestUrl.pathname);
+	const resourcePath = isCanonicalResourcePath(requestUrl.pathname, allowedPaths) ? requestUrl.pathname : normalizedRequestPath;
+	const resourceUrl = new URL(requestUrl);
+	resourceUrl.pathname = resourcePath;
+	const metadataUrl = new URL(resourceUrl);
+	metadataUrl.pathname = buildDocsMcpProtectedResourceMetadataRoute(resourcePath);
+	return {
+		resourceUrl,
+		metadataUrl
+	};
+}
+function resolveDocsMcpProtectedResourceMetadataLocation(request, route) {
+	const rawUrl = new URL(request.url);
+	const allowedPaths = getDocsMcpResourcePaths(route);
+	if (!rawUrl.pathname.startsWith(`${DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE}/`)) return;
+	const requestedResourcePath = rawUrl.pathname.slice(37);
+	if (!isCanonicalResourcePath(requestedResourcePath, allowedPaths)) return void 0;
+	const metadataUrl = new URL(rawUrl);
+	const resourceUrl = new URL(metadataUrl);
+	resourceUrl.pathname = requestedResourcePath;
+	return {
+		resourceUrl,
+		metadataUrl
+	};
+}
+function isDocsMcpProtectedResourceMetadataPath(pathname) {
+	const normalized = normalizeRequestPath(pathname);
+	return normalized === DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE || normalized.startsWith(`${DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE}/`);
+}
+function normalizeRequestPath(pathname) {
+	const normalized = `/${pathname}`.replace(/\/+/g, "/");
+	return normalized === "/" ? normalized : normalized.replace(/\/+$/, "");
+}
+function isCanonicalResourcePath(pathname, resourcePaths) {
+	return resourcePaths.some((resourcePath) => pathname === resourcePath || resourcePath !== "/" && pathname === `${resourcePath}/`);
+}
+function isDocsMcpProtectedResourceMetadataRequestPath(pathname, route) {
+	if (!pathname.startsWith(`${DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE}/`)) return false;
+	return isCanonicalResourcePath(pathname.slice(37), getDocsMcpResourcePaths(route));
+}
+function isAbsoluteHttpUrl(value) {
+	try {
+		const url = new URL(value);
+		const loopbackHttp = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]");
+		return (url.protocol === "https:" || loopbackHttp) && !url.username && !url.password && !url.search && !url.hash;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { DEFAULT_MCP_PROTECTED_RESOURCE_METADATA_ROUTE, DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE, buildDocsMcpProtectedResourceMetadataRoute, getDocsMcpProtectedResourceMetadataRoutes, getDocsMcpResourcePaths, hasDocsMcpProtectedResourceConfig, isDocsMcpOAuthScopeToken, isDocsMcpProtectedResourceMetadataPath, isDocsMcpRequest, isDocsMcpResourcePath, normalizeDocsMcpAuthorizationServerUrls, normalizeDocsMcpEndpointPath, resolveDocsMcpProtectedResourceMetadataLocation, resolveDocsMcpResourceLocation };

package/dist/mcp.d.mts

@@ -1,6 +1,8 @@
-import { Ar as FeedbackConfig, B as DocsAgentContentChangesConfig, Cr as DocsTelemetryConfig, En as DocsOpenApiMcpConfig, Kr as OrderingItem, Mn as DocsRetrievalSourceProvenance, Or as DocsTelemetryFramework, Xn as DocsSearchConfig, Y as DocsAgentEvaluationsConfig, bn as DocsOkfConfig, ei as PageAgentFrontmatter, gn as DocsObservabilityConfig, in as DocsMcpAuthenticate, nn as DocsMcpAllowedOrigins, rn as DocsMcpAuthPrincipal, sn as DocsMcpConfig, vr as DocsSearchSourcePage, vt as DocsAnalyticsConfig, wn as DocsOkfTrustMetadataInput } from "./types-BJFeMXWZ.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-BHPc7YIX.mjs";
-import { a as DocsContentChangeHydrationResponse, c as HydrateDocsContentChangesOptions, d as hydrateDocsContentChanges, h as DocsContentChangeFeed, i as DocsContentChangeHydrationContent, l as MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, n as DOCS_CONTENT_CHANGE_HYDRATION_FORMAT, o as DocsContentChangeHydrationSection, r as DocsContentChangeHydrationBudget, s as DocsContentChangeHydrationTombstone, sn as DocsMarkdownSectionIndex, t as DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, u as MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET } from "./content-change-hydration-wqXIZHp6.mjs";
+import { DocsAgentContentChangesConfig, DocsAgentEvaluationsConfig, DocsAnalyticsConfig, DocsMcpAllowedOrigins, DocsMcpAuthPrincipal, DocsMcpAuthenticate, DocsMcpConfig, DocsObservabilityConfig, DocsOkfConfig, DocsOkfTrustMetadataInput, DocsOpenApiMcpConfig, DocsRetrievalSourceProvenance, DocsSearchConfig, DocsSearchSourcePage, DocsTelemetryConfig, DocsTelemetryFramework, FeedbackConfig, OrderingItem, PageAgentFrontmatter } from "./types.mjs";
+import { DocsPublishedAgentSkill } from "./standards-discovery.mjs";
+import { DocsMarkdownSectionIndex } from "./agent.mjs";
+import { DocsContentChangeFeed } from "./content-changes.mjs";
+import { DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, DOCS_CONTENT_CHANGE_HYDRATION_FORMAT, DocsContentChangeHydrationBudget, DocsContentChangeHydrationContent, DocsContentChangeHydrationResponse, DocsContentChangeHydrationSection, DocsContentChangeHydrationTombstone, HydrateDocsContentChangesOptions, MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, hydrateDocsContentChanges } from "./content-change-hydration.mjs";
 import { McpServer } from "@modelcontextprotocol/server";
 
 //#region src/mcp.d.ts

package/dist/mcp.mjs

@@ -1,12 +1,24 @@
-import "./http-body-DkAPk6D5.mjs";
-import { C as filterDocsPagesByAccess, S as upsertPageAgentContractMarkdown, _ as hasStructuredPageAgentContract, o as findDocsMarkdownSection, s as parseDocsMarkdownSections, v as normalizePageAgentFrontmatter, y as renderPageAgentContractMarkdown } from "./markdown-sections-9Oxr33b-.mjs";
-import { a as emitDocsAnalyticsEvent, i as emitDocsAgentTraceEvent, n as createDocsAgentTraceContext, r as createDocsAgentTraceId } from "./analytics-p8Vhhu2P.mjs";
-import { $n as isDocsMcpResourcePath, An as agentVersionConstraintMatches, Bn as normalizeDocsRelated, Dn as resolveDocsAudienceMdxContent, E as DOCS_MARKDOWN_SECTION_INDEX_FORMAT, Et as validateDocsAgentFeedbackPayload, Gt as DocsContentChangesRequestError, In as DocsPaginationCursorError, Jt as isDocsContentChangeGeneration, Kt as createDocsContentChangeFeed, Mn as normalizeAgentFramework, Nn as normalizeAgentLocale, P as buildDocsMarkdownSectionIndex, Pn as normalizeAgentScopeValues, Rn as paginateDocsItems, Tt as toDocsMarkdownUrl, Vn as renderDocsRelatedMarkdownLines, Xn as isDocsMcpOAuthScopeToken, Xt as resolveDocsContentChangesConfig, Zn as isDocsMcpProtectedResourceMetadataPath, cr as normalizeDocsOkfTrustMetadataInput, er as normalizeDocsMcpAuthorizationServerUrls, fn as normalizeDocsSearchFilters, jn as agentVersionConstraintsOverlap, lr as resolveDocsOkfConfig, mn as performDocsSearchWithMetadata, nr as resolveDocsMcpProtectedResourceMetadataLocation, pn as performDocsSearch, rn as buildDocsSearchFacets, rr as resolveDocsMcpResourceLocation, sr as buildDocsOkfBundle, tr as normalizeDocsMcpEndpointPath, ut as resolveDocsAgentFeedbackConfig, xn as resolveLocalDocsMcpSearchConfig } from "./agent-DkAidqtV.mjs";
-import { r as isDocsRetrievalCanonicalUrl } from "./retrieval-digest-CT-eIEcp.mjs";
-import "./standards-discovery-sSEojU80.mjs";
-import { a as emitDocsTelemetryAgentSurfaceEvent, l as emitDocsTelemetryProjectEvent, n as resolvePageSidebarFolderIndexBehavior, s as emitDocsTelemetryMcpToolEvent } from "./sidebar-CFHBj29f.mjs";
-import { a as DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, c as MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, g as stripGeneratedAgentProvenance, i as resolveDocsOpenApiMcpOperations, l as hydrateDocsContentChanges, n as readDocsOpenApiMcpResponse, o as DOCS_CONTENT_CHANGE_HYDRATION_FORMAT, r as resolveDocsOpenApiMcpBaseUrl, s as MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, t as acquireDocsOpenApiMcpBudget } from "./openapi-mcp-BIOTLiA7.mjs";
-import { t as validateDocsOpenApiMcpUrl } from "./openapi-mcp-node-C4jUpZG6.mjs";
+import { filterDocsPagesByAccess } from "./access.mjs";
+import { createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent } from "./analytics.mjs";
+import { toDocsMarkdownUrl } from "./urls.mjs";
+import { buildDocsOkfBundle, normalizeDocsOkfTrustMetadataInput, resolveDocsOkfConfig } from "./okf.mjs";
+import { isDocsMcpOAuthScopeToken, isDocsMcpProtectedResourceMetadataPath, isDocsMcpResourcePath, normalizeDocsMcpAuthorizationServerUrls, normalizeDocsMcpEndpointPath, resolveDocsMcpProtectedResourceMetadataLocation, resolveDocsMcpResourceLocation } from "./mcp-auth.mjs";
+import { hasStructuredPageAgentContract, normalizePageAgentFrontmatter, renderPageAgentContractMarkdown, upsertPageAgentContractMarkdown } from "./agent-contract.mjs";
+import { normalizeDocsRelated, renderDocsRelatedMarkdownLines } from "./related.mjs";
+import { findDocsMarkdownSection, parseDocsMarkdownSections } from "./markdown-sections.mjs";
+import { isDocsRetrievalCanonicalUrl } from "./retrieval-digest.mjs";
+import { DocsPaginationCursorError, paginateDocsItems } from "./pagination.mjs";
+import { agentVersionConstraintMatches, agentVersionConstraintsOverlap, normalizeAgentFramework, normalizeAgentLocale, normalizeAgentScopeValues } from "./agent-scope.mjs";
+import { resolveDocsAudienceMdxContent } from "./audience.mjs";
+import { buildDocsSearchFacets, normalizeDocsSearchFilters, performDocsSearch, performDocsSearchWithMetadata, resolveLocalDocsMcpSearchConfig } from "./search.mjs";
+import { DocsContentChangesRequestError, createDocsContentChangeFeed, isDocsContentChangeGeneration, resolveDocsContentChangesConfig } from "./content-changes.mjs";
+import { DOCS_MARKDOWN_SECTION_INDEX_FORMAT, buildDocsMarkdownSectionIndex, resolveDocsAgentFeedbackConfig, validateDocsAgentFeedbackPayload } from "./agent.mjs";
+import { emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryMcpToolEvent, emitDocsTelemetryProjectEvent } from "./telemetry.mjs";
+import { resolvePageSidebarFolderIndexBehavior } from "./sidebar.mjs";
+import { stripGeneratedAgentProvenance } from "./agent-provenance.mjs";
+import { DEFAULT_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, DOCS_CONTENT_CHANGE_HYDRATION_FORMAT, MAX_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, MIN_DOCS_CONTENT_CHANGE_HYDRATION_TOKEN_BUDGET, hydrateDocsContentChanges } from "./content-change-hydration.mjs";
+import { acquireDocsOpenApiMcpBudget, readDocsOpenApiMcpResponse, resolveDocsOpenApiMcpBaseUrl, resolveDocsOpenApiMcpOperations } from "./openapi-mcp.mjs";
+import { validateDocsOpenApiMcpUrl } from "./openapi-mcp-node.mjs";
 import matter from "gray-matter";
 import fs from "node:fs";
 import path from "node:path";

package/dist/mdx.d.mts

@@ -0,0 +1,6 @@
+import { toDocsMarkdownUrl } from "./urls.mjs";
+import { applyDocsMarkdownHeadingAnchors, withDocsMarkdownRenderableHeadings } from "./markdown-sections.mjs";
+import { encodeDocsHeadingTocUrls } from "./heading-toc.mjs";
+import { isolateDocsMarkdownPromptReferences } from "./prompt-references.mjs";
+import { remarkCodeGroup } from "./code-group-mdx.mjs";
+export { applyDocsMarkdownHeadingAnchors, encodeDocsHeadingTocUrls, isolateDocsMarkdownPromptReferences, remarkCodeGroup, toDocsMarkdownUrl, withDocsMarkdownRenderableHeadings };

package/dist/mdx.mjs

@@ -0,0 +1,7 @@
+import { toDocsMarkdownUrl } from "./urls.mjs";
+import { applyDocsMarkdownHeadingAnchors, withDocsMarkdownRenderableHeadings } from "./markdown-sections.mjs";
+import { encodeDocsHeadingTocUrls } from "./heading-toc.mjs";
+import { isolateDocsMarkdownPromptReferences } from "./prompt-references.mjs";
+import { remarkCodeGroup } from "./code-group-mdx.mjs";
+
+export { applyDocsMarkdownHeadingAnchors, encodeDocsHeadingTocUrls, isolateDocsMarkdownPromptReferences, remarkCodeGroup, toDocsMarkdownUrl, withDocsMarkdownRenderableHeadings };

package/dist/metadata.d.mts

@@ -0,0 +1,60 @@
+import { DocsConfig, DocsMetadata, OGConfig, PageAgentFrontmatter, PageFrontmatter, PageOpenGraph, PageTwitter } from "./types.mjs";
+
+//#region src/metadata.d.ts
+interface DocsStructuredDataBreadcrumb {
+  name: string;
+  url: string;
+}
+interface DocsPageStructuredDataInput {
+  title: string;
+  description?: string;
+  url: string;
+  baseUrl?: string;
+  entry?: string;
+  dateModified?: string;
+  breadcrumbs?: DocsStructuredDataBreadcrumb[];
+  /** Optional actionable page contract represented as a Schema.org HowTo. */
+  agent?: PageAgentFrontmatter;
+}
+/**
+ * Resolve page title using metadata titleTemplate.
+ * %s is replaced with page title.
+ */
+declare function resolveTitle(pageTitle: string, metadata?: DocsMetadata): string;
+/**
+ * Resolve OG image URL for a page.
+ * Prefers page.openGraph.images[0], then page.ogImage, then config endpoint/default.
+ */
+declare function resolveOGImage(page: PageFrontmatter, ogConfig?: OGConfig, baseUrl?: string): string | undefined;
+/**
+ * Build the Open Graph metadata object for a page.
+ * When the page has openGraph in frontmatter, uses it (with title/description filled from page if omitted).
+ * Otherwise uses ogImage or config (dynamic endpoint / defaultImage).
+ */
+declare function buildPageOpenGraph(page: Pick<PageFrontmatter, "title" | "description" | "ogImage" | "openGraph">, ogConfig?: OGConfig, baseUrl?: string): PageOpenGraph | undefined;
+/**
+ * Build the Twitter card metadata object for a page.
+ * When the page has twitter in frontmatter, uses it.
+ * Otherwise builds from ogImage or config (dynamic endpoint).
+ */
+declare function buildPageTwitter(page: Pick<PageFrontmatter, "title" | "description" | "ogImage" | "openGraph" | "twitter">, ogConfig?: OGConfig, baseUrl?: string): PageTwitter | undefined;
+/**
+ * Resolve the public docs site URL from existing agent-facing config.
+ *
+ * The framework intentionally reuses `sitemap.baseUrl`, `llmsTxt.baseUrl`,
+ * `robots.baseUrl`, or `ai.docsUrl` instead of requiring another setting.
+ */
+declare function resolveDocsMetadataBaseUrl(config: DocsConfig): string | undefined;
+/**
+ * Build Schema.org JSON-LD for a docs page.
+ *
+ * The shape follows Vercel's agent readability guidance: a `TechArticle`
+ * with title, description, canonical URL, freshness, and breadcrumbs.
+ */
+declare function buildDocsPageStructuredData(input: DocsPageStructuredDataInput): Record<string, unknown>;
+/**
+ * Serialize Schema.org JSON-LD for safe insertion into a `<script>` tag.
+ */
+declare function renderDocsPageStructuredDataJson(input: DocsPageStructuredDataInput): string;
+//#endregion
+export { DocsPageStructuredDataInput, DocsStructuredDataBreadcrumb, buildDocsPageStructuredData, buildPageOpenGraph, buildPageTwitter, renderDocsPageStructuredDataJson, resolveDocsMetadataBaseUrl, resolveOGImage, resolveTitle };

package/dist/{metadata-BOHn0Y5K.mjs → metadata.mjs}

@@ -1,4 +1,4 @@
-import { _ as hasStructuredPageAgentContract, v as normalizePageAgentFrontmatter } from "./markdown-sections-9Oxr33b-.mjs";
+import { hasStructuredPageAgentContract, normalizePageAgentFrontmatter } from "./agent-contract.mjs";
 
 //#region src/metadata.ts
 /**
@@ -234,4 +234,4 @@ function renderDocsPageStructuredDataJson(input) {
 }
 
 //#endregion
-export { resolveDocsMetadataBaseUrl as a, renderDocsPageStructuredDataJson as i, buildPageOpenGraph as n, resolveOGImage as o, buildPageTwitter as r, resolveTitle as s, buildDocsPageStructuredData as t };
+export { buildDocsPageStructuredData, buildPageOpenGraph, buildPageTwitter, renderDocsPageStructuredDataJson, resolveDocsMetadataBaseUrl, resolveOGImage, resolveTitle };