@farming-labs/farmjs 0.2.98 → 0.2.101

package/dist/server.js

@@ -1,10 +1,45 @@
 import fs from "node:fs";
 import path from "node:path";
+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, 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, resolveApiReferenceOpenApiDiscovery, resolveDocsMcpConfig, resolveConfiguredAgentSkills, } from "@farming-labs/docs/server";
 import { loadDocsNavTree, loadDocsContent, flattenNavTree, normalizeDocsFrontmatterLastmod, } from "./content.js";
+import farmDocsBrowserCss from "./browser-css.generated.js";
 export { createFarmjsApiReference } from "./api-reference.js";
+const FARM_DOCS_BROWSER_CSS_PATH = "/__farm_docs/browser.css";
+function loadFarmDocsBrowserCss() {
+    return farmDocsBrowserCss;
+}
+async function renderFarmDocsMarkup(element) {
+    const server = ReactDOMServer;
+    if (server.renderToReadableStream) {
+        const stream = await server.renderToReadableStream(element);
+        await stream.allReady;
+        return new Response(stream).text();
+    }
+    return new Promise((resolve, reject) => {
+        const destination = new PassThrough();
+        const chunks = [];
+        destination.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        destination.on("error", reject);
+        destination.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        const renderer = server.renderToPipeableStream(element, {
+            onAllReady() {
+                renderer.pipe(destination);
+            },
+            onShellError(error) {
+                reject(error);
+            },
+            onError(error) {
+                if (!destination.readableEnded)
+                    destination.destroy(error);
+            },
+        });
+    });
+}
 function isApiReferenceOpenApiRequest(url) {
     return url.searchParams.get("format")?.trim() === "openapi";
 }
@@ -37,6 +72,64 @@ function safeUrlOrigin(value) {
         return value;
     }
 }
+function navigationItemName(item) {
+    return item.label?.trim() || item.title?.trim() || item.slug?.trim() || "Documentation";
+}
+function navigationItemUrl(item, entry) {
+    if (item.href?.trim())
+        return item.href.trim();
+    if (typeof item.slug !== "string")
+        return undefined;
+    const slug = item.slug.replace(/^\/+|\/+$/g, "");
+    return slug ? `/${entry}/${slug}` : `/${entry}`;
+}
+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";
+    function toNode(item) {
+        const children = item.children ?? item.items ?? [];
+        const name = navigationItemName(item);
+        const url = navigationItemUrl(item, entry);
+        if (children.length > 0) {
+            const mappedChildren = children.map(toNode).filter((node) => node !== null);
+            return {
+                type: "folder",
+                name,
+                ...(defaultOpen ? { defaultOpen: true } : {}),
+                ...(item.icon ? { icon: item.icon } : {}),
+                ...(url
+                    ? {
+                        index: {
+                            type: "page",
+                            name,
+                            url,
+                            ...(item.icon ? { icon: item.icon } : {}),
+                        },
+                    }
+                    : {}),
+                children: mappedChildren,
+            };
+        }
+        if (!url)
+            return null;
+        return {
+            type: "page",
+            name,
+            url,
+            ...(item.icon ? { icon: item.icon } : {}),
+        };
+    }
+    return {
+        name: typeof config.nav?.title === "string" && config.nav.title.trim()
+            ? config.nav.title.trim()
+            : "Docs",
+        children: configured
+            .map((item) => toNode(item))
+            .filter((node) => node !== null),
+    };
+}
 function resolvePreloadedContent(value) {
     if (!value || typeof value !== "object")
         return null;
@@ -74,6 +167,17 @@ function stripMarkdownText(content) {
         .replace(/\n{3,}/g, "\n\n")
         .trim();
 }
+function markdownStartsWithDescription(content, description) {
+    if (!description?.trim())
+        return false;
+    const withoutLeadingTitle = content
+        .trimStart()
+        .replace(/^#\s+[^\r\n]+(?:\r?\n|$)/, "")
+        .trimStart();
+    const firstBlock = withoutLeadingTitle.split(/\r?\n\s*\r?\n/, 1)[0] ?? "";
+    const normalize = (value) => stripMarkdownText(value).replace(/\s+/g, " ").trim();
+    return normalize(firstBlock) === normalize(description);
+}
 function normalizePathSegment(value) {
     return value.replace(/^\/+|\/+$/g, "");
 }
@@ -400,7 +504,7 @@ export function createDocsServer(config) {
         ? githubRaw.replace(/\/$/, "")
         : githubRaw?.url.replace(/\/$/, "");
     const githubBranch = typeof githubRaw === "object" ? (githubRaw.branch ?? "main") : "main";
-    const githubContentPath = typeof githubRaw === "object" ? githubRaw.directory?.replace(/^\/|\/$/g, "") : undefined;
+    const githubDirectory = typeof githubRaw === "object" ? githubRaw.directory?.replace(/^\/|\/$/g, "") : undefined;
     const readingTimeOptions = resolveReadingTimeOptions(config.readingTime);
     const aiConfig = { enabled: false, ...config.ai };
     if (config.apiKey && !aiConfig.apiKey) {
@@ -471,9 +575,11 @@ export function createDocsServer(config) {
     async function load({ pathname, locale }) {
         const resolvedLocale = (i18n && locale && i18n.locales.includes(locale) ? locale : undefined) ?? i18n?.defaultLocale;
         const ctx = resolveContextFromPath(pathname, resolvedLocale);
-        const tree = applySidebarFolderIndexBehavior(preloaded
-            ? navTreeFromMap(preloaded, ctx.dirPrefix, entry, ordering)
-            : loadDocsNavTree(ctx.contentDirAbs, entry, ordering), {
+        const configuredNavigation = navTreeFromNavigation(config, entry);
+        const tree = applySidebarFolderIndexBehavior(configuredNavigation ??
+            (preloaded
+                ? navTreeFromMap(preloaded, ctx.dirPrefix, entry, ordering)
+                : loadDocsNavTree(ctx.contentDirAbs, entry, ordering)), {
             sidebar: config.sidebar,
             defaultBehavior: "link",
         });
@@ -560,16 +666,24 @@ export function createDocsServer(config) {
         const previousPage = currentIndex > 0 ? flatPages[currentIndex - 1] : null;
         const nextPage = currentIndex < flatPages.length - 1 ? flatPages[currentIndex + 1] : null;
         let editOnGithub;
-        if (githubRepo && githubContentPath) {
-            const trimmed = githubContentPath.replace(/\/+$/, "");
-            const localePrefix = ctx.locale ? `${ctx.locale}/` : "";
-            editOnGithub = `${githubRepo}/blob/${githubBranch}/${trimmed}/${localePrefix}${toPosixPath(relPath)}`;
+        if (githubRepo) {
+            const contentPath = normalizePathSegment(path.isAbsolute(ctx.contentDirRel)
+                ? toPosixPath(path.relative(rootDir, ctx.contentDirRel))
+                : toPosixPath(ctx.contentDirRel));
+            const configuredDirectory = normalizePathSegment(githubDirectory ?? "");
+            const sourceDirectory = configuredDirectory &&
+                (contentPath === configuredDirectory || contentPath.startsWith(`${configuredDirectory}/`))
+                ? contentPath
+                : joinPathParts(configuredDirectory, contentPath);
+            const sourcePath = joinPathParts(sourceDirectory, toPosixPath(relPath));
+            editOnGithub = `${githubRepo}/edit/${githubBranch}/${sourcePath}`;
         }
         const fallbackTitle = isIndex
             ? "Documentation"
             : (slug.split("/").pop()?.replace(/-/g, " ") ?? "Documentation");
         const title = data.title ?? fallbackTitle;
         const description = data.description;
+        const descriptionInBody = markdownStartsWithDescription(humanRawContent, description);
         const structuredData = renderDocsPageStructuredDataJson({
             title,
             description,
@@ -585,6 +699,7 @@ export function createDocsServer(config) {
             url: currentUrl,
             title,
             description,
+            descriptionInBody,
             rawContent: humanRawContent,
             readingTime,
             readingTimeFormat: readingTimeOptions.format,
@@ -1598,9 +1713,10 @@ export function createDocsServer(config) {
             },
             getNavigation(locale) {
                 const ctx = resolveContextFromPath(`/${entry}`, resolveLocaleForMcp(locale));
-                return applySidebarFolderIndexBehavior(preloaded
-                    ? navTreeFromMap(preloaded, ctx.dirPrefix, entry, ordering)
-                    : loadDocsNavTree(ctx.contentDirAbs, entry, ordering), {
+                return applySidebarFolderIndexBehavior(navTreeFromNavigation(config, entry) ??
+                    (preloaded
+                        ? navTreeFromMap(preloaded, ctx.dirPrefix, entry, ordering)
+                        : loadDocsNavTree(ctx.contentDirAbs, entry, ordering)), {
                     sidebar: config.sidebar,
                     defaultBehavior: "link",
                 });
@@ -1722,4 +1838,193 @@ export function createDocsServer(config) {
     }
     return { load, GET, HEAD, POST, MCP, handle };
 }
+function escapeDocumentText(value) {
+    return String(value ?? "")
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function serializeInlineJson(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+function createClientDocsConfig(config) {
+    const { apiKey: _apiKey, rootDir: _rootDir, contentDir: _contentDir, _preloadedContent, _preloadedAgentSkills, socialImage, ...clientConfig } = config;
+    const ai = clientConfig.ai && typeof clientConfig.ai === "object"
+        ? {
+            ...clientConfig.ai,
+            apiKey: undefined,
+            providers: clientConfig.ai.providers && typeof clientConfig.ai.providers === "object"
+                ? Object.fromEntries(Object.entries(clientConfig.ai.providers).map(([name, provider]) => [
+                    name,
+                    provider && typeof provider === "object"
+                        ? { ...provider, apiKey: undefined }
+                        : provider,
+                ]))
+                : clientConfig.ai.providers,
+        }
+        : clientConfig.ai;
+    return {
+        ...clientConfig,
+        ...(ai ? { ai } : {}),
+        ...(socialImage === false ? { socialImage: false } : {}),
+    };
+}
+function normalizedPublicRoute(value, fallback) {
+    const normalized = typeof value === "string" && value.trim() ? value.trim() : fallback;
+    if (normalized === "/")
+        return "/";
+    return `/${normalized.replace(/^\/+|\/+$/g, "")}`;
+}
+function isHtmlDocsPageRequest(config, request) {
+    const method = request.method.toUpperCase();
+    if (method !== "GET" && method !== "HEAD")
+        return false;
+    const url = new URL(request.url);
+    const pathname = url.pathname === "/" ? "/" : url.pathname.replace(/\/+$/, "");
+    const docsPath = normalizedPublicRoute(config.docsPath, `/${config.entry ?? "docs"}`);
+    const isPagePath = docsPath === "/"
+        ? !pathname.endsWith(".md")
+        : pathname === docsPath || pathname.startsWith(`${docsPath}/`);
+    if (!isPagePath || pathname.endsWith(".md"))
+        return false;
+    const accept = request.headers.get("accept")?.toLowerCase() ?? "";
+    return !accept.includes("text/markdown");
+}
+function runtimeFontClasses(fonts) {
+    return Array.from(new Set([fonts?.body?.className, fonts?.body?.variable, fonts?.code?.variable].filter((value) => typeof value === "string" && value.length > 0))).join(" ");
+}
+function runtimeFontStyle(fonts) {
+    const declarations = [];
+    const bodyFontFamily = fonts?.body?.style?.fontFamily?.trim();
+    const codeFontFamily = fonts?.code?.style?.fontFamily?.trim();
+    if (bodyFontFamily) {
+        declarations.push(`--font-sans:${bodyFontFamily}`, `--fd-font-sans:${bodyFontFamily}`);
+    }
+    if (codeFontFamily) {
+        declarations.push(`--font-mono:${codeFontFamily}`, `--fd-font-mono:${codeFontFamily}`);
+    }
+    return declarations.join(";");
+}
+function runtimeFontPreloads(fonts) {
+    const seen = new Set();
+    const values = [fonts?.body, fonts?.code].flatMap((font) => font?.preloads ?? []);
+    const unique = values.filter(({ href }) => {
+        if (seen.has(href))
+            return false;
+        seen.add(href);
+        return true;
+    });
+    return {
+        markup: unique
+            .map(({ href, type }) => `<link rel="preload" href="${escapeDocumentText(href)}" as="font" type="${escapeDocumentText(type)}" crossorigin>`)
+            .join("\n  "),
+        header: unique
+            .map(({ href, type }) => `<${href}>; rel=preload; as=font; type=${type}; crossorigin`)
+            .join(", "),
+    };
+}
+function renderFarmDocsDocument(input) {
+    const { config, data } = input;
+    const description = data.description ?? config.metadata?.description;
+    const themeName = config.theme?.name ?? "default";
+    const favicon = typeof config.favicon === "string" ? config.favicon : undefined;
+    const rootClasses = runtimeFontClasses(input.fonts);
+    const rootStyle = runtimeFontStyle(input.fonts);
+    const fontPreloads = runtimeFontPreloads(input.fonts).markup;
+    return `<!doctype html>
+<html class="dark" 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">
+  <meta name="generator" content="@farming-labs/farmjs">
+  <title>${escapeDocumentText(data.title)}</title>
+  ${description ? `<meta name="description" content="${escapeDocumentText(description)}">` : ""}
+  ${favicon ? `<link rel="icon" href="${escapeDocumentText(favicon)}">` : ""}
+  ${fontPreloads}
+  <link rel="stylesheet" href="${FARM_DOCS_BROWSER_CSS_PATH}">
+  ${input.stylesheets
+        .map((href) => `<link rel="stylesheet" href="${escapeDocumentText(href)}">`)
+        .join("\n  ")}
+</head>
+<body>
+  <div id="root"><div id="farm-docs-root"${rootClasses ? ` class="${escapeDocumentText(rootClasses)}"` : ""}${rootStyle ? ` style="${escapeDocumentText(rootStyle)}"` : ""}>${input.markup}</div></div>
+  <script>window.__FARM_DOCS_ADAPTER__={config:${serializeInlineJson(createClientDocsConfig(config))},data:${serializeInlineJson(data)}};</script>
+  <script type="module" src="${escapeDocumentText(input.clientEntry)}"></script>
+</body>
+</html>`;
+}
+/**
+ * Create the complete Farm docs runtime owned by this adapter.
+ *
+ * Farm core supplies host assets and module loading; this adapter owns route
+ * classification, docs APIs, content loading, React rendering, and hydration
+ * state for every documentation request.
+ */
+export function createFarmDocsRuntimeHandler(config, options = {}) {
+    const runtimeConfig = {
+        ...config,
+        rootDir: options.rootDir ?? config.rootDir ?? process.cwd(),
+    };
+    const docsServer = createDocsServer(runtimeConfig);
+    return async function handleFarmDocsRuntimeRequest(request) {
+        const url = new URL(request.url);
+        if (url.pathname === FARM_DOCS_BROWSER_CSS_PATH) {
+            return new Response(request.method.toUpperCase() === "HEAD" ? null : loadFarmDocsBrowserCss(), {
+                status: 200,
+                headers: {
+                    "Content-Type": "text/css; charset=utf-8",
+                    "Cache-Control": "public, max-age=31536000, immutable",
+                },
+            });
+        }
+        if (!isHtmlDocsPageRequest(runtimeConfig, request)) {
+            return docsServer.handle(request);
+        }
+        let data;
+        try {
+            data = await docsServer.load({ pathname: url.pathname });
+        }
+        catch (error) {
+            const status = error &&
+                typeof error === "object" &&
+                typeof error.status === "number"
+                ? error.status
+                : 500;
+            if (status === 404)
+                return null;
+            throw error;
+        }
+        const reactModule = options.loadReactModule
+            ? await options.loadReactModule()
+            : (await import("./react.js"));
+        const markup = await renderFarmDocsMarkup(createElement(reactModule.FarmDocsPage, {
+            config: runtimeConfig,
+            data,
+        }));
+        const fonts = await options.resolveLayoutFonts?.(url.pathname);
+        const fontPreloadHeader = runtimeFontPreloads(fonts).header;
+        const html = renderFarmDocsDocument({
+            config: runtimeConfig,
+            data,
+            markup,
+            clientEntry: options.clientEntry ?? "/farm-client.js",
+            stylesheets: options.stylesheets ?? [],
+            fonts,
+        });
+        return new Response(request.method.toUpperCase() === "HEAD" ? null : html, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/html; charset=utf-8",
+                "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
+                "X-Farm-Docs-Adapter": "@farming-labs/farmjs",
+                ...(fontPreloadHeader ? { Link: fontPreloadHeader } : {}),
+            },
+        });
+    };
+}
 //# sourceMappingURL=server.js.map