@farming-labs/farmjs 0.2.104 → 0.2.106

package/dist/server.js

@@ -4,10 +4,11 @@ import { PassThrough } from "node:stream";
 import matter from "gray-matter";
 import { createElement } from "react";
 import * as ReactDOMServer from "react-dom/server";
-import { applySidebarFolderIndexBehavior, buildDocsAskAIContext, buildDocsSearchFacets, buildDocsAgentDiscoverySpec, buildDocsConfigMap, buildDocsDiagnostics, createDocsContentChangeFeed, createDocsContentChangesHttpResponse, createDocsCacheableResponse, createDocsStandardsDiscoveryResponse, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, findDocsMarkdownPage, getDocsLlmsTxtMaxCharsIssue, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, isDocsAgentDiscoveryRequest, isDocsContentChangesRequest, isDocsAgentsRequest, isDocsConfigRequest, isDocsDiagnosticsRequest, isDocsSkillRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, normalizeDocsOkfTrustMetadataInput, parseDocsAgentFeedbackData, performDocsSearch, performDocsSearchWithMetadata, renderDocsMarkdownDocument, renderDocsLlmsTxt, renderDocsAgentsDocument, renderDocsSkillDocument, readDocsSitemapManifestFromContentMap, stripGeneratedAgentProvenance, resolveDocsAudienceMdxContent, resolveDocsAgentFeedbackConfig, resolveDocsAgentFeedbackRequest, resolvePageSidebarFolderIndexBehavior, resolveAskAISearchRequestConfig, resolveDocsSearchAudience, resolveDocsSearchError, resolveDocsSearchRequest, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsMetadataBaseUrl, resolveDocsContentChangesConfig, resolveDocsRequestApiRoute, resolveDocsRetrievalLastModified, resolveDocsPublishedAgentSkill, resolveDocsStandardsDiscoveryRequest, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSitemapPageLastmod, resolveDocsAgentsFormat, resolveDocsSkillFormat, inferDocsTelemetryAgentSurface, renderDocsPageStructuredDataJson, selectDocsLlmsTxtContent, validateDocsAgentFeedbackPayload, } from "@farming-labs/docs";
+import { applySidebarFolderIndexBehavior, buildDocsAskAIContext, buildDocsSearchFacets, buildDocsAgentDiscoverySpec, compactDocsAgentDiscoverySpec, buildDocsConfigMap, buildDocsDiagnostics, createDocsContentChangeFeed, createDocsContentChangesHttpResponse, createDocsCacheableResponse, createDocsStandardsDiscoveryResponse, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, findDocsMarkdownPage, getDocsLlmsTxtMaxCharsIssue, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, isDocsAgentDiscoveryRequest, isDocsContentChangesRequest, isDocsAgentsRequest, isDocsConfigRequest, isDocsDiagnosticsRequest, isDocsSkillRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, normalizeDocsOkfTrustMetadataInput, parseDocsAgentFeedbackData, performDocsSearch, performDocsSearchWithMetadata, renderDocsMarkdownDocument, renderDocsLlmsTxt, renderDocsAgentsDocument, renderDocsSkillDocument, readDocsSitemapManifestFromContentMap, stripGeneratedAgentProvenance, resolveDocsAudienceMdxContent, resolveDocsAgentFeedbackConfig, resolveDocsAgentFeedbackRequest, resolvePageSidebarFolderIndexBehavior, resolveAskAISearchRequestConfig, resolveDocsSearchAudience, resolveDocsSearchError, resolveDocsSearchRequest, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsMetadataBaseUrl, resolveDocsContentChangesConfig, resolveDocsRequestApiRoute, resolveDocsRetrievalLastModified, resolveDocsPublishedAgentSkill, resolveDocsStandardsDiscoveryRequest, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSitemapPageLastmod, resolveDocsAgentsFormat, resolveDocsSkillFormat, inferDocsTelemetryAgentSurface, renderDocsPageStructuredDataJson, selectDocsLlmsTxtContent, validateDocsAgentFeedbackPayload, } from "@farming-labs/docs";
 import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, readDocsSitemapManifest, resolveApiReferenceConfig, resolveApiReferenceOpenApiDiscovery, resolveDocsMcpConfig, resolveConfiguredAgentSkills, } from "@farming-labs/docs/server";
 import { loadDocsNavTree, loadDocsContent, flattenNavTree, normalizeDocsFrontmatterLastmod, readFarmDocsLastModifiedManifest, resolveFarmDocsLastModified, } from "./content.js";
 import farmDocsBrowserCss from "./browser-css.generated.js";
+import { FARM_DOCS_NAVIGATION_HEADER } from "./runtime.js";
 export { createFarmjsApiReference } from "./api-reference.js";
 const FARM_DOCS_BROWSER_CSS_PATH = "/__farm_docs/browser.css";
 function loadFarmDocsBrowserCss() {
@@ -87,7 +88,8 @@ function navTreeFromNavigation(config, entry) {
     const configured = config.navigation?.sidebar;
     if (!Array.isArray(configured) || configured.length === 0)
         return null;
-    const defaultOpen = config.theme?.name === "fumadocs-pixel-border";
+    const flat = config.sidebar?.flat === true;
+    const defaultOpen = flat || config.theme?.name === "fumadocs-pixel-border";
     function toNode(item) {
         const children = item.children ?? item.items ?? [];
         const name = navigationItemName(item);
@@ -98,6 +100,7 @@ function navTreeFromNavigation(config, entry) {
                 type: "folder",
                 name,
                 ...(defaultOpen ? { defaultOpen: true } : {}),
+                ...(flat ? { collapsible: false } : {}),
                 ...(item.icon ? { icon: item.icon } : {}),
                 ...(url
                     ? {
@@ -204,27 +207,29 @@ function toSourcePath(contentDir, relPath, rootDir) {
     return `/${joinPathParts(base, toPosixPath(relPath))}`;
 }
 function navTreeFromMap(contentMap, dirPrefix, entry, ordering) {
-    const dirs = [];
+    const pages = [];
     for (const key of Object.keys(contentMap)) {
         if (!key.startsWith(dirPrefix))
             continue;
         const rel = key.slice(dirPrefix.length);
         const segments = rel.split("/");
         const fileName = segments.pop();
-        const base = fileName.replace(/\.(md|mdx)$/, "");
-        if (base !== "page" && base !== "index")
+        if (fileName === "agent.md" || (!fileName.endsWith(".md") && !fileName.endsWith(".mdx"))) {
             continue;
+        }
+        const base = fileName.replace(/\.(md|mdx)$/, "");
+        const isIndex = base === "page" || base === "index";
         const { data } = matter(contentMap[key]);
-        const dirParts = segments;
-        const slug = dirParts.join("/");
+        const pageParts = isIndex ? segments : [...segments, base];
+        const slug = pageParts.join("/");
         const url = slug ? `/${entry}/${slug}` : `/${entry}`;
-        const fallbackTitle = dirParts.length > 0
-            ? dirParts[dirParts.length - 1]
+        const fallbackTitle = pageParts.length > 0
+            ? pageParts[pageParts.length - 1]
                 .replace(/-/g, " ")
                 .replace(/\b\w/g, (char) => char.toUpperCase())
             : "Documentation";
-        dirs.push({
-            parts: dirParts,
+        pages.push({
+            parts: pageParts,
             title: data.title ?? fallbackTitle,
             url,
             icon: data.icon,
@@ -232,13 +237,13 @@ function navTreeFromMap(contentMap, dirPrefix, entry, ordering) {
             order: typeof data.order === "number" ? data.order : Infinity,
         });
     }
-    dirs.sort((a, b) => {
+    pages.sort((a, b) => {
         if (a.parts.length !== b.parts.length)
             return a.parts.length - b.parts.length;
         return a.parts.join("/").localeCompare(b.parts.join("/"));
     });
     const children = [];
-    const rootInfo = dirs.find((dir) => dir.parts.length === 0);
+    const rootInfo = pages.find((page) => page.parts.length === 0);
     if (rootInfo) {
         children.push({
             type: "page",
@@ -261,14 +266,25 @@ function navTreeFromMap(contentMap, dirPrefix, entry, ordering) {
     }
     function buildLevel(parentParts) {
         const depth = parentParts.length;
-        const directChildren = dirs.filter((dir) => {
-            if (dir.parts.length !== depth + 1)
+        const directSlugs = Array.from(new Set(pages
+            .filter((page) => {
+            if (page.parts.length <= depth)
                 return false;
-            for (let index = 0; index < depth; index++) {
-                if (dir.parts[index] !== parentParts[index])
-                    return false;
-            }
-            return true;
+            return parentParts.every((part, index) => page.parts[index] === part);
+        })
+            .map((page) => page.parts[depth])));
+        const directChildren = directSlugs.map((slug) => {
+            const parts = [...parentParts, slug];
+            const page = pages.find((candidate) => candidate.parts.length === parts.length &&
+                candidate.parts.every((part, index) => part === parts[index]));
+            return {
+                parts,
+                title: page?.title ?? slug.replace(/-/g, " ").replace(/\b\w/g, (char) => char.toUpperCase()),
+                url: page?.url,
+                icon: page?.icon,
+                folderIndexBehavior: page?.folderIndexBehavior,
+                order: page?.order ?? Infinity,
+            };
         });
         const slugOrder = findSlugOrder(parentParts);
         if (slugOrder) {
@@ -284,17 +300,26 @@ function navTreeFromMap(contentMap, dirPrefix, entry, ordering) {
                     ordered.push(child);
             }
             return ordered.map((child) => {
-                const hasGrandChildren = dirs.some((dir) => {
-                    if (dir.parts.length <= child.parts.length)
+                const hasGrandChildren = pages.some((page) => {
+                    if (page.parts.length <= child.parts.length)
                         return false;
-                    return child.parts.every((part, index) => dir.parts[index] === part);
+                    return child.parts.every((part, index) => page.parts[index] === part);
                 });
                 if (hasGrandChildren) {
                     return {
                         type: "folder",
                         name: child.title,
                         icon: child.icon,
-                        index: { type: "page", name: child.title, url: child.url, icon: child.icon },
+                        ...(child.url
+                            ? {
+                                index: {
+                                    type: "page",
+                                    name: child.title,
+                                    url: child.url,
+                                    icon: child.icon,
+                                },
+                            }
+                            : {}),
                         folderIndexBehavior: child.folderIndexBehavior,
                         children: buildLevel(child.parts),
                     };
@@ -311,17 +336,26 @@ function navTreeFromMap(contentMap, dirPrefix, entry, ordering) {
             directChildren.sort((a, b) => a.order - b.order);
         }
         return directChildren.map((child) => {
-            const hasGrandChildren = dirs.some((dir) => {
-                if (dir.parts.length <= child.parts.length)
+            const hasGrandChildren = pages.some((page) => {
+                if (page.parts.length <= child.parts.length)
                     return false;
-                return child.parts.every((part, index) => dir.parts[index] === part);
+                return child.parts.every((part, index) => page.parts[index] === part);
             });
             if (hasGrandChildren) {
                 return {
                     type: "folder",
                     name: child.title,
                     icon: child.icon,
-                    index: { type: "page", name: child.title, url: child.url, icon: child.icon },
+                    ...(child.url
+                        ? {
+                            index: {
+                                type: "page",
+                                name: child.title,
+                                url: child.url,
+                                icon: child.icon,
+                            },
+                        }
+                        : {}),
                     folderIndexBehavior: child.folderIndexBehavior,
                     children: buildLevel(child.parts),
                 };
@@ -814,6 +848,7 @@ export function createDocsServer(config) {
                     okf: config.agent?.okf,
                 }),
                 lastModified: resolveDocsRetrievalLastModified(page, "agent"),
+                access: page.agent?.access,
             }
             : null;
     }
@@ -901,7 +936,7 @@ export function createDocsServer(config) {
         if (standardsDiscoveryResponse)
             return standardsDiscoveryResponse;
         if (isDocsAgentDiscoveryRequest(url, { apiRoute: discoveryApiRoute })) {
-            const content = `${JSON.stringify(buildDocsAgentDiscoverySpec({
+            const fullSpec = buildDocsAgentDiscoverySpec({
                 ...discoveryOptions,
                 publishedSkills: [
                     await resolveDocsPublishedAgentSkill({
@@ -911,13 +946,16 @@ export function createDocsServer(config) {
                     ...(await getPublishedAgentSkills()),
                 ],
                 agentCard: config.agent?.a2a,
-            }), null, 2)}\n`;
+            });
+            const compact = url.searchParams.get("profile") === "compact";
+            const spec = compact ? compactDocsAgentDiscoverySpec(fullSpec) : fullSpec;
+            const content = `${JSON.stringify(spec, null, compact ? undefined : 2)}\n`;
             return createDocsCacheableResponse({
                 request: event.request,
                 content,
                 headers: {
                     "Content-Type": "application/json; charset=utf-8",
-                    "Cache-Control": "public, max-age=0, s-maxage=3600",
+                    "Cache-Control": "public, max-age=0, s-maxage=3600, stale-while-revalidate=86400",
                     "X-Robots-Tag": "noindex",
                     Link: agentManifestLinkHeader,
                 },
@@ -1056,6 +1094,7 @@ export function createDocsServer(config) {
                 origin: markdownOrigin,
                 locale: ctx.locale,
                 lastModified: representation?.lastModified,
+                access: representation?.access,
                 pages: getSearchIndex(ctx),
                 sitemap: config.sitemap,
             });
@@ -1899,7 +1938,7 @@ function normalizedPublicRoute(value, fallback) {
         return "/";
     return `/${normalized.replace(/^\/+|\/+$/g, "")}`;
 }
-function isHtmlDocsPageRequest(config, request) {
+function isDocsPageRequest(config, request) {
     const method = request.method.toUpperCase();
     if (method !== "GET" && method !== "HEAD")
         return false;
@@ -1909,7 +1948,10 @@ function isHtmlDocsPageRequest(config, request) {
     const isPagePath = docsPath === "/"
         ? !pathname.endsWith(".md")
         : pathname === docsPath || pathname.startsWith(`${docsPath}/`);
-    if (!isPagePath || pathname.endsWith(".md"))
+    return isPagePath && !pathname.endsWith(".md");
+}
+function isHtmlDocsPageRequest(config, request) {
+    if (!isDocsPageRequest(config, request))
         return false;
     const accept = request.headers.get("accept")?.toLowerCase() ?? "";
     return !accept.includes("text/markdown");
@@ -1947,6 +1989,17 @@ function runtimeFontPreloads(fonts) {
             .join(", "),
     };
 }
+function resolveDefaultTheme(config) {
+    const toggle = config.themeToggle;
+    const value = toggle && typeof toggle === "object" ? toggle.default : undefined;
+    return value === "light" || value === "dark" || value === "system" ? value : "system";
+}
+function renderThemeBootstrap(config) {
+    const defaultTheme = resolveDefaultTheme(config);
+    const toggle = config.themeToggle;
+    const allowStoredTheme = toggle !== false && !(toggle && typeof toggle === "object" && toggle.enabled === false);
+    return `<script>(()=>{try{const fallback=${JSON.stringify(defaultTheme)};const stored=${allowStoredTheme ? 'localStorage.getItem("theme")' : "null"};const selected=stored==="light"||stored==="dark"||stored==="system"?stored:fallback;const resolved=selected==="system"?(matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"):selected;const root=document.documentElement;root.classList.remove("light","dark");root.classList.add(resolved);root.style.colorScheme=resolved}catch{}})()</script>`;
+}
 function renderFarmDocsDocument(input) {
     const { config, data } = input;
     const description = data.description ?? config.metadata?.description;
@@ -1955,8 +2008,10 @@ function renderFarmDocsDocument(input) {
     const rootClasses = runtimeFontClasses(input.fonts);
     const rootStyle = runtimeFontStyle(input.fonts);
     const fontPreloads = runtimeFontPreloads(input.fonts).markup;
+    const defaultTheme = resolveDefaultTheme(config);
+    const fallbackTheme = defaultTheme === "dark" ? "dark" : "light";
     return `<!doctype html>
-<html class="dark" lang="${escapeDocumentText(data.locale ?? "en")}" data-docs-theme="${escapeDocumentText(themeName)}" data-farm-docs-runtime="true">
+<html class="${fallbackTheme}" lang="${escapeDocumentText(data.locale ?? "en")}" data-docs-theme="${escapeDocumentText(themeName)}" data-farm-docs-runtime="true">
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -1964,6 +2019,7 @@ function renderFarmDocsDocument(input) {
   <title>${escapeDocumentText(data.title)}</title>
   ${description ? `<meta name="description" content="${escapeDocumentText(description)}">` : ""}
   ${favicon ? `<link rel="icon" href="${escapeDocumentText(favicon)}">` : ""}
+  ${renderThemeBootstrap(config)}
   ${fontPreloads}
   <link rel="stylesheet" href="${FARM_DOCS_BROWSER_CSS_PATH}">
   ${input.stylesheets
@@ -2001,6 +2057,30 @@ export function createFarmDocsRuntimeHandler(config, options = {}) {
                 },
             });
         }
+        if (request.method.toUpperCase() === "GET" &&
+            request.headers.get(FARM_DOCS_NAVIGATION_HEADER) === "1" &&
+            isDocsPageRequest(runtimeConfig, request)) {
+            try {
+                const data = await docsServer.load({ pathname: url.pathname });
+                return Response.json({ data }, {
+                    headers: {
+                        "Cache-Control": "no-store",
+                        Vary: FARM_DOCS_NAVIGATION_HEADER,
+                    },
+                });
+            }
+            catch (error) {
+                const status = error &&
+                    typeof error === "object" &&
+                    typeof error.status === "number"
+                    ? error.status
+                    : 500;
+                if (status === 404) {
+                    return Response.json({ error: "Documentation page not found." }, { status });
+                }
+                throw error;
+            }
+        }
         if (!isHtmlDocsPageRequest(runtimeConfig, request)) {
             return docsServer.handle(request);
         }