@farming-labs/svelte 0.2.64 → 0.2.65

package/README.md

@@ -42,13 +42,13 @@ const contentFiles = import.meta.glob("/docs/**/*.{md,mdx,svx}", {
   eager: true,
 }) as Record<string, string>;
 
-export const { load, GET, POST, MCP } = createDocsServer({
+export const { load, GET, HEAD, POST, MCP } = createDocsServer({
   ...config,
   _preloadedContent: contentFiles,
 });
 ```
 
-Re-export `load` from the docs `+layout.server.ts` and `GET`/`POST` from the docs API route. Use
+Re-export `load` from the docs `+layout.server.ts` and `GET`/`HEAD`/`POST` from the docs API route. Use
 `DocsLayout` and `DocsContent` from `@farming-labs/svelte-theme` for presentation. The CLI
 generates all of these files, including public agent and MCP forwarding.
 

package/dist/server.d.ts

@@ -16,7 +16,7 @@
  *   query: "?raw", import: "default", eager: true,
  * }) as Record<string, string>;
  *
- * export const { load, GET, POST } = createDocsServer({
+ * export const { load, GET, HEAD, POST, MCP } = createDocsServer({
  *   ...config,
  *   _preloadedContent: contentFiles,
  * });
@@ -58,6 +58,7 @@ export interface DocsServer {
         structuredData: string;
     }>;
     GET: (event: RequestEvent) => Promise<Response>;
+    HEAD: (event: RequestEvent) => Promise<Response>;
     POST: (event: RequestEvent) => Promise<Response>;
     MCP: DocsMcpHttpHandlers;
 }

package/dist/server.js

@@ -16,7 +16,7 @@
  *   query: "?raw", import: "default", eager: true,
  * }) as Record<string, string>;
  *
- * export const { load, GET, POST } = createDocsServer({
+ * export const { load, GET, HEAD, POST, MCP } = createDocsServer({
  *   ...config,
  *   _preloadedContent: contentFiles,
  * });
@@ -30,7 +30,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { applySidebarFolderIndexBehavior, buildDocsAskAIContext, buildDocsAgentDiscoverySpec, buildDocsConfigMap, buildDocsDiagnostics, createDocsStandardsDiscoveryResponse, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, findDocsMarkdownPage, getDocsLlmsTxtMaxCharsIssue, getDocsDiscoveryLinkHeader, isDocsAgentDiscoveryRequest, isDocsAgentsRequest, isDocsConfigRequest, isDocsDiagnosticsRequest, isDocsSkillRequest, isDocsStandardsDiscoveryRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, parseDocsAgentFeedbackData, performDocsSearch, renderDocsMarkdownDocument, renderDocsLlmsTxt, renderDocsAgentsDocument, renderDocsSkillDocument, readDocsSitemapManifestFromContentMap, stripGeneratedAgentProvenance, resolveDocsAudienceMdxContent, resolveDocsAgentFeedbackConfig, resolveDocsAgentFeedbackRequest, resolvePageSidebarFolderIndexBehavior, resolveAskAISearchRequestConfig, resolveDocsSearchAudience, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsMetadataBaseUrl, resolveDocsRequestApiRoute, resolveDocsPublishedAgentSkill, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSitemapPageLastmod, resolveDocsAgentsFormat, resolveDocsSkillFormat, inferDocsTelemetryAgentSurface, renderDocsPageStructuredDataJson, selectDocsLlmsTxtContent, validateDocsAgentFeedbackPayload, } from "@farming-labs/docs";
+import { applySidebarFolderIndexBehavior, buildDocsAskAIContext, buildDocsAgentDiscoverySpec, buildDocsConfigMap, buildDocsDiagnostics, createDocsStandardsDiscoveryResponse, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, findDocsMarkdownPage, getDocsLlmsTxtMaxCharsIssue, getDocsDiscoveryLinkHeader, isDocsAgentDiscoveryRequest, isDocsAgentsRequest, isDocsConfigRequest, isDocsDiagnosticsRequest, isDocsSkillRequest, normalizeDocsRelated, normalizePageAgentFrontmatter, parseDocsAgentFeedbackData, performDocsSearch, renderDocsMarkdownDocument, renderDocsLlmsTxt, renderDocsAgentsDocument, renderDocsSkillDocument, readDocsSitemapManifestFromContentMap, stripGeneratedAgentProvenance, resolveDocsAudienceMdxContent, resolveDocsAgentFeedbackConfig, resolveDocsAgentFeedbackRequest, resolvePageSidebarFolderIndexBehavior, resolveAskAISearchRequestConfig, resolveDocsSearchAudience, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsMetadataBaseUrl, resolveDocsRequestApiRoute, resolveDocsPublishedAgentSkill, resolveDocsStandardsDiscoveryRequest, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSitemapPageLastmod, resolveDocsAgentsFormat, resolveDocsSkillFormat, inferDocsTelemetryAgentSurface, renderDocsPageStructuredDataJson, selectDocsLlmsTxtContent, validateDocsAgentFeedbackPayload, } from "@farming-labs/docs";
 import { buildApiReferenceOpenApiDocumentAsync, createDocsCloudAskAIResponse, createDocsMcpHttpHandler, isDocsCloudAskAIProvider, readDocsSitemapManifest, resolveApiReferenceConfig, resolveDocsMcpConfig, resolveConfiguredAgentSkills, serializeDocsIconRegistry, serializeOpenDocsProviders, } from "@farming-labs/docs/server";
 import { loadDocsNavTree, loadDocsContent, flattenNavTree } from "./content.js";
 import { renderMarkdown } from "./markdown.js";
@@ -405,9 +405,13 @@ export function createDocsServer(config = {}) {
     const observability = config.observability;
     const contentDirBase = config.contentDir ?? entry;
     const rootDir = path.resolve(config.rootDir ?? process.cwd());
-    const publishedAgentSkills = Array.isArray(config._preloadedAgentSkills)
-        ? Promise.resolve(config._preloadedAgentSkills)
-        : resolveConfiguredAgentSkills(config.agent?.skills, { rootDir });
+    let publishedAgentSkills;
+    function getPublishedAgentSkills() {
+        publishedAgentSkills ??= Array.isArray(config._preloadedAgentSkills)
+            ? Promise.resolve(config._preloadedAgentSkills)
+            : resolveConfiguredAgentSkills(config.agent?.skills, { rootDir });
+        return publishedAgentSkills;
+    }
     const i18n = resolveDocsI18n(config.i18n);
     const githubRaw = config.github;
     const github = typeof githubRaw === "string" ? { url: githubRaw } : (githubRaw ?? null);
@@ -713,10 +717,56 @@ export function createDocsServer(config = {}) {
             }
             : null;
     }
+    function createDiscoveryOptions(origin, apiRoute) {
+        return {
+            origin,
+            entry,
+            apiRoute,
+            docsPath: config.docsPath,
+            apiCatalog: apiCatalogEnabled,
+            i18n,
+            search: config.search,
+            mcp: mcpConfig,
+            feedback: agentFeedbackDiscovery,
+            llms: {
+                enabled: llmsEnabled,
+                apiCatalog: apiCatalogEnabled,
+                baseUrl: llmsBaseUrl || undefined,
+                siteTitle: llmsTitle,
+                siteDescription: llmsDesc,
+                maxChars: typeof llmsTxtConfig === "object" ? llmsTxtConfig.maxChars : undefined,
+                sections: typeof llmsTxtConfig === "object" ? llmsTxtConfig.sections : undefined,
+            },
+            sitemap: config.sitemap,
+            robots: config.robots,
+            openapi: openapiDiscovery,
+            markdown: {
+                acceptHeader: true,
+            },
+        };
+    }
+    async function resolveStandardsResponse(request, url, discoveryOptions) {
+        const resolved = resolveDocsStandardsDiscoveryRequest(url, {
+            apiRoute: discoveryOptions.apiRoute,
+        });
+        if (!resolved)
+            return null;
+        const method = request.method.toUpperCase();
+        const needsSkill = (method === "GET" || method === "HEAD") && resolved.kind !== "api-catalog";
+        return createDocsStandardsDiscoveryResponse({
+            request,
+            ...discoveryOptions,
+            preferredSkillDocument: needsSkill ? readRootSkillDocument(preloaded, rootDir) : null,
+            fallbackSkillDocument: needsSkill ? renderDocsSkillDocument(discoveryOptions) : "",
+            publishedSkills: needsSkill ? await getPublishedAgentSkills() : [],
+            agentCard: config.agent?.a2a,
+        });
+    }
     // ─── GET /api/docs?query=… | ?format=llms | ?format=llms-full ──
     async function GET(event) {
         trackTelemetryRequest(event.request);
         const ctx = resolveContextFromRequest(event.request);
+        const isHeadRequest = event.request.method.toUpperCase() === "HEAD";
         const requestApiRoute = resolveDocsRequestApiRoute(event.url, configuredApiRoute);
         if (isDocsConfigRequest(event.url)) {
             return new Response(JSON.stringify(buildDocsConfigMap(config), null, 2), {
@@ -745,56 +795,24 @@ export function createDocsServer(config = {}) {
             });
         }
         const discoveryApiRoute = requestApiRoute;
-        const discoveryOptions = {
-            origin: event.url.origin,
-            entry,
-            apiRoute: discoveryApiRoute,
-            docsPath: config.docsPath,
-            apiCatalog: apiCatalogEnabled,
-            i18n,
-            search: config.search,
-            mcp: mcpConfig,
-            feedback: agentFeedbackDiscovery,
-            llms: {
-                enabled: llmsEnabled,
-                apiCatalog: apiCatalogEnabled,
-                baseUrl: llmsBaseUrl || undefined,
-                siteTitle: llmsTitle,
-                siteDescription: llmsDesc,
-                maxChars: typeof llmsTxtConfig === "object" ? llmsTxtConfig.maxChars : undefined,
-                sections: typeof llmsTxtConfig === "object" ? llmsTxtConfig.sections : undefined,
-            },
-            sitemap: config.sitemap,
-            robots: config.robots,
-            openapi: openapiDiscovery,
-            markdown: {
-                acceptHeader: true,
-            },
-        };
-        if (isDocsStandardsDiscoveryRequest(event.url, { apiRoute: discoveryApiRoute })) {
-            const standardsDiscoveryResponse = await createDocsStandardsDiscoveryResponse({
-                request: event.request,
-                ...discoveryOptions,
-                preferredSkillDocument: readRootSkillDocument(preloaded, rootDir),
-                fallbackSkillDocument: renderDocsSkillDocument(discoveryOptions),
-                publishedSkills: await publishedAgentSkills,
-                agentCard: config.agent?.a2a,
-            });
-            if (standardsDiscoveryResponse)
-                return standardsDiscoveryResponse;
-        }
+        const discoveryOptions = createDiscoveryOptions(event.url.origin, discoveryApiRoute);
+        const standardsDiscoveryResponse = await resolveStandardsResponse(event.request, event.url, discoveryOptions);
+        if (standardsDiscoveryResponse)
+            return standardsDiscoveryResponse;
         if (isDocsAgentDiscoveryRequest(event.url, { apiRoute: discoveryApiRoute })) {
-            return new Response(JSON.stringify(buildDocsAgentDiscoverySpec({
-                ...discoveryOptions,
-                publishedSkills: [
-                    await resolveDocsPublishedAgentSkill({
-                        preferredDocument: readRootSkillDocument(preloaded, rootDir),
-                        fallbackDocument: renderDocsSkillDocument(discoveryOptions),
-                    }),
-                    ...(await publishedAgentSkills),
-                ],
-                agentCard: config.agent?.a2a,
-            }), null, 2), {
+            return new Response(isHeadRequest
+                ? null
+                : JSON.stringify(buildDocsAgentDiscoverySpec({
+                    ...discoveryOptions,
+                    publishedSkills: [
+                        await resolveDocsPublishedAgentSkill({
+                            preferredDocument: readRootSkillDocument(preloaded, rootDir),
+                            fallbackDocument: renderDocsSkillDocument(discoveryOptions),
+                        }),
+                        ...(await getPublishedAgentSkills()),
+                    ],
+                    agentCard: config.agent?.a2a,
+                }), null, 2), {
                 headers: {
                     "Content-Type": "application/json; charset=utf-8",
                     "Cache-Control": "public, max-age=0, s-maxage=3600",
@@ -813,6 +831,15 @@ export function createDocsServer(config = {}) {
                     },
                 });
             }
+            if (isHeadRequest) {
+                return new Response(null, {
+                    headers: {
+                        "Content-Type": "application/json; charset=utf-8",
+                        "Cache-Control": "public, max-age=0, s-maxage=3600",
+                        "X-Robots-Tag": "noindex",
+                    },
+                });
+            }
             const document = await buildApiReferenceOpenApiDocumentAsync(config, {
                 framework: "sveltekit",
                 rootDir,
@@ -837,7 +864,7 @@ export function createDocsServer(config = {}) {
                     },
                 });
             }
-            return new Response(JSON.stringify(agentFeedbackConfig.schema, null, 2), {
+            return new Response(isHeadRequest ? null : JSON.stringify(agentFeedbackConfig.schema, null, 2), {
                 headers: {
                     "Content-Type": "application/schema+json; charset=utf-8",
                     "Cache-Control": "public, max-age=0, s-maxage=3600",
@@ -847,7 +874,10 @@ export function createDocsServer(config = {}) {
         }
         if (isDocsAgentsRequest(event.url, { apiRoute: discoveryApiRoute }) ||
             resolveDocsAgentsFormat(event.url) === "agents") {
-            return new Response(readRootAgentsDocument(preloaded, rootDir) ?? renderDocsAgentsDocument(discoveryOptions), {
+            return new Response(isHeadRequest
+                ? null
+                : (readRootAgentsDocument(preloaded, rootDir) ??
+                    renderDocsAgentsDocument(discoveryOptions)), {
                 headers: {
                     "Content-Type": "text/markdown; charset=utf-8",
                     "Cache-Control": "public, max-age=0, s-maxage=3600",
@@ -858,7 +888,10 @@ export function createDocsServer(config = {}) {
         }
         if (isDocsSkillRequest(event.url, { apiRoute: discoveryApiRoute }) ||
             resolveDocsSkillFormat(event.url) === "skill") {
-            return new Response(readRootSkillDocument(preloaded, rootDir) ?? renderDocsSkillDocument(discoveryOptions), {
+            return new Response(isHeadRequest
+                ? null
+                : (readRootSkillDocument(preloaded, rootDir) ??
+                    renderDocsSkillDocument(discoveryOptions)), {
                 headers: {
                     "Content-Type": "text/markdown; charset=utf-8",
                     "Cache-Control": "public, max-age=0, s-maxage=3600",
@@ -1018,6 +1051,9 @@ export function createDocsServer(config = {}) {
     async function POST(event) {
         trackTelemetryRequest(event.request);
         const requestUrl = new URL(event.request.url);
+        const standardsDiscoveryResponse = await resolveStandardsResponse(event.request, requestUrl, createDiscoveryOptions(requestUrl.origin, resolveDocsRequestApiRoute(requestUrl, configuredApiRoute)));
+        if (standardsDiscoveryResponse)
+            return standardsDiscoveryResponse;
         const agentFeedbackRequest = resolveDocsAgentFeedbackRequest(requestUrl, agentFeedbackConfig);
         if (agentFeedbackRequest) {
             if (agentFeedbackRequest.kind === "schema") {
@@ -1566,7 +1602,7 @@ export function createDocsServer(config = {}) {
                     preferredDocument: readRootSkillDocument(preloaded, rootDir),
                     fallbackDocument: renderDocsSkillDocument(skillOptions),
                 });
-                return [rootSkill, ...(await publishedAgentSkills)];
+                return [rootSkill, ...(await getPublishedAgentSkills())];
             },
         },
         mcp: config.mcp,
@@ -1576,5 +1612,13 @@ export function createDocsServer(config = {}) {
         observability,
         defaultName: mcpSiteTitle,
     });
-    return { load, GET, POST, MCP };
+    async function HEAD(event) {
+        const response = await GET(event);
+        return new Response(null, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    }
+    return { load, GET, HEAD, POST, MCP };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/svelte",
-  "version": "0.2.64",
+  "version": "0.2.65",
   "description": "SvelteKit adapter for @farming-labs/docs — content loading and navigation utilities",
   "keywords": [
     "docs",
@@ -56,7 +56,7 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.9.3",
-    "@farming-labs/docs": "0.2.64"
+    "@farming-labs/docs": "0.2.65"
   },
   "peerDependencies": {
     "@farming-labs/docs": "*"