@farming-labs/theme 0.2.115 → 0.2.117

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/docs-api.mjs +74 -18
  2. package/package.json +2 -2
package/dist/docs-api.mjs CHANGED
@@ -4,8 +4,8 @@ import { BoundedRouteCache } from "./bounded-route-cache.mjs";
4
4
  import fs from "node:fs";
5
5
  import path from "node:path";
6
6
  import matter from "gray-matter";
7
- import { DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_AGENT_MANIFEST_VERSION, DOCS_CONTENT_CHANGES_FORMAT, DOCS_CONTENT_CHANGES_RESPONSE_VALUE, DOCS_MARKDOWN_SECTION_INDEX_FORMAT, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, buildDocsSearchFacets, compactDocsAgentDiscoverySpec, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsCacheableResponse, createDocsContentChangeFeed, createDocsContentChangesHttpResponse, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsContentChangesRequest, isDocsDiagnosticsRequest, normalizeDocsOkfTrustMetadataInput, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, performDocsSearchWithMetadata, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsContentChangesConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, resolveDocsRetrievalLastModified, resolveDocsSearchAudience, resolveDocsSearchError, resolveDocsSearchRequest, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance } from "@farming-labs/docs";
8
- import { buildApiReferenceOpenApiDocumentAsync, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceConfig, resolveApiReferenceOpenApiDiscovery, resolveConfiguredAgentSkills, resolveDocsMcpConfig } from "@farming-labs/docs/server";
7
+ import { DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_AGENT_MANIFEST_VERSION, DOCS_CONTENT_CHANGES_FORMAT, DOCS_CONTENT_CHANGES_RESPONSE_VALUE, DOCS_MARKDOWN_SECTION_INDEX_FORMAT, acceptsDocsMarkdown, buildDocsAskAIContext, buildDocsConfigMap, buildDocsDiagnostics, buildDocsSearchFacets, compactDocsAgentDiscoverySpec, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsCacheableResponse, createDocsContentChangeFeed, createDocsContentChangesHttpResponse, createDocsMarkdownResponse, createDocsRobotsResponse, createDocsSitemapResponse, createDocsStandardsDiscoveryResponse, detectDocsMarkdownAgentRequest, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsTelemetryAgentSurfaceEvent, emitDocsTelemetryProjectEvent, formatDocsAskAIPackageHints, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, getDocsLlmsTxtMaxCharsIssue, getDocsMcpProtectedResourceMetadataRoutes, hasDocsMarkdownSignatureAgent, inferDocsTelemetryAgentSurface, isDocsConfigRequest, isDocsContentChangesRequest, isDocsDiagnosticsRequest, normalizeDocsOkfTrustMetadataInput, normalizeDocsRelated, normalizePageAgentFrontmatter, performDocsSearch, performDocsSearchWithMetadata, renderDocsLlmsTxt, renderDocsMarkdownDocument, resolveAskAISearchRequestConfig, resolveChangelogConfig, resolveDocsAgentContractMcpTools, resolveDocsAudienceMdxContent, resolveDocsContentChangesConfig, resolveDocsI18n, resolveDocsLlmsTxtRequest, resolveDocsLlmsTxtSections, resolveDocsLocale, resolveDocsMetadataBaseUrl, resolveDocsPublishedAgentSkill, resolveDocsRequestApiRoute, resolveDocsRetrievalLastModified, resolveDocsSearchAudience, resolveDocsSearchError, resolveDocsSearchRequest, resolveDocsSitemapConfig, resolveDocsStandardsDiscoveryRequest, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, selectDocsLlmsTxtContent, stripGeneratedAgentProvenance, withDocsOpenApiOperationCounts } from "@farming-labs/docs";
8
+ import { buildApiReferenceOpenApiDocumentAsync, buildApiReferenceOperationPagesAsync, createApiReferenceOperationMarkdownResponse, createDocsMcpHttpHandler, createFilesystemDocsMcpSource, readDocsSitemapManifest, resolveApiReferenceConfig, resolveApiReferenceOpenApiDiscovery, resolveConfiguredAgentSkills, resolveDocsMcpConfig } from "@farming-labs/docs/server";
9
9
 
10
10
  //#region src/docs-api.ts
11
11
  /**
@@ -396,6 +396,10 @@ function buildAgentSpec({ origin, entry, apiRoute, apiCatalog, i18n, search, con
396
396
  source: openapi.source ?? null,
397
397
  specUrl: openapi.specUrl ?? null,
398
398
  apiReferencePath: openapi.apiReferencePath ?? null,
399
+ versions: openapi.versions?.map((version) => ({
400
+ ...version,
401
+ url: `${apiRoute}?format=openapi&version=${encodeURIComponent(version.id)}`
402
+ })) ?? [],
399
403
  format: "OpenAPI 3.1"
400
404
  },
401
405
  search: {
@@ -2511,11 +2515,11 @@ function readApiReferenceConfig(root) {
2511
2515
  const routeRootMatch = block.match(/routeRoot\s*:\s*["']([^"']+)["']/);
2512
2516
  const specUrlMatch = block.match(/specUrl\s*:\s*["']([^"']+)["']/);
2513
2517
  const catalogTargetsMatch = block.match(/catalogTargets\s*:\s*\[([\s\S]*?)\]/);
2514
- const rendererMatch = block.match(/renderer\s*:\s*["'](fumadocs|scalar)["']/);
2518
+ const rendererMatch = block.match(/renderer\s*:\s*["'](farming-labs|fumadocs|scalar)["']/);
2515
2519
  const excludeMatch = block.match(/exclude\s*:\s*\[([\s\S]*?)\]/);
2516
2520
  const catalogTargets = catalogTargetsMatch?.[1] === void 0 ? void 0 : Array.from(catalogTargetsMatch[1].matchAll(/["']([^"']+)["']/g)).map((match) => match[1]).filter(Boolean);
2517
2521
  const exclude = excludeMatch?.[1] === void 0 ? void 0 : Array.from(excludeMatch[1].matchAll(/["']([^"']+)["']/g)).map((match) => match[1]).filter(Boolean);
2518
- const renderer = rendererMatch?.[1] === "fumadocs" || rendererMatch?.[1] === "scalar" ? rendererMatch[1] : void 0;
2522
+ const renderer = rendererMatch?.[1] === "farming-labs" || rendererMatch?.[1] === "fumadocs" || rendererMatch?.[1] === "scalar" ? rendererMatch[1] : void 0;
2519
2523
  return {
2520
2524
  enabled: enabledMatch ? enabledMatch[1] === "true" : true,
2521
2525
  path: pathMatch?.[1],
@@ -2737,6 +2741,7 @@ function createDocsAPI(options) {
2737
2741
  };
2738
2742
  }
2739
2743
  const indexesByLocale = /* @__PURE__ */ new Map();
2744
+ const apiOperationPagesByLocale = /* @__PURE__ */ new Map();
2740
2745
  const llmsCache = new BoundedRouteCache(MAX_LLMS_CACHE_ROUTES_PER_LOCALE);
2741
2746
  const generatedAgentsCache = new BoundedRouteCache(MAX_LLMS_CACHE_ROUTES_PER_LOCALE);
2742
2747
  const generatedSkillCache = new BoundedRouteCache(MAX_LLMS_CACHE_ROUTES_PER_LOCALE);
@@ -2760,6 +2765,19 @@ function createDocsAPI(options) {
2760
2765
  indexesByLocale.set(key, next);
2761
2766
  return next;
2762
2767
  }
2768
+ function getApiOperationSearchPages(ctx, baseUrl) {
2769
+ const key = `${ctx.locale ?? "__default__"}\0${baseUrl}`;
2770
+ const cached = apiOperationPagesByLocale.get(key);
2771
+ if (cached) return cached;
2772
+ const next = buildApiReferenceOperationPagesAsync(apiReferenceDocsConfig, {
2773
+ framework: "next",
2774
+ rootDir: root,
2775
+ baseUrl,
2776
+ locale: ctx.locale
2777
+ });
2778
+ apiOperationPagesByLocale.set(key, next);
2779
+ return next;
2780
+ }
2763
2781
  function getMarkdownSources(ctx) {
2764
2782
  const key = ctx.locale ?? "__default__";
2765
2783
  const cached = markdownSourcesByLocale.get(key);
@@ -2818,10 +2836,12 @@ function createDocsAPI(options) {
2818
2836
  };
2819
2837
  return null;
2820
2838
  }
2821
- function getLlmsContent(ctx, apiRoute) {
2822
- const cached = llmsCache.get(ctx.locale, apiRoute);
2839
+ async function getLlmsContent(ctx, apiRoute, baseUrl) {
2840
+ const cacheKey = `${apiRoute}\0${baseUrl}`;
2841
+ const cached = llmsCache.get(ctx.locale, cacheKey);
2823
2842
  if (cached) return cached;
2824
- const next = generateLlmsTxt(getIndexes(ctx), {
2843
+ const operationPages = await getApiOperationSearchPages(ctx, baseUrl);
2844
+ const next = generateLlmsTxt([...getIndexes(ctx), ...operationPages], {
2825
2845
  siteTitle: llmsConfig.siteTitle ?? "Documentation",
2826
2846
  siteDescription: llmsConfig.siteDescription,
2827
2847
  baseUrl: llmsConfig.baseUrl ?? "",
@@ -2829,9 +2849,9 @@ function createDocsAPI(options) {
2829
2849
  maxChars: llmsConfig.maxChars,
2830
2850
  sections: llmsConfig.sections,
2831
2851
  apiCatalog: apiCatalogEnabled,
2832
- openapi: openapiDiscovery
2852
+ openapi: withDocsOpenApiOperationCounts(openapiDiscovery, operationPages)
2833
2853
  });
2834
- llmsCache.set(ctx.locale, apiRoute, next);
2854
+ llmsCache.set(ctx.locale, cacheKey, next);
2835
2855
  return next;
2836
2856
  }
2837
2857
  function getGeneratedAgentsDocument(origin, apiRoute) {
@@ -2877,13 +2897,14 @@ function createDocsAPI(options) {
2877
2897
  generatedSkillCache.set(void 0, cacheKey, next);
2878
2898
  return next;
2879
2899
  }
2880
- async function resolveStandardsResponse(request, url) {
2900
+ async function resolveStandardsResponse(request, url, ctx) {
2881
2901
  const apiRoute = resolveDocsRequestApiRoute(url, configuredApiRouteInput);
2882
2902
  const resolved = resolveDocsStandardsDiscoveryRequest(url, { apiRoute });
2883
2903
  if (!resolved) return null;
2884
2904
  const method = request.method.toUpperCase();
2885
2905
  const needsSkill = (method === "GET" || method === "HEAD") && resolved.kind !== "api-catalog";
2886
2906
  const fallbackSkillDocument = needsSkill ? getGeneratedSkillDocument(url.origin, apiRoute) : "";
2907
+ const operationPages = ctx && resolved.kind === "api-catalog" ? await getApiOperationSearchPages(ctx, markdownMetadataBaseUrl || url.origin) : [];
2887
2908
  return createDocsStandardsDiscoveryResponse({
2888
2909
  request,
2889
2910
  preferredSkillDocument: needsSkill ? readRootSkillDocument() : null,
@@ -2903,7 +2924,7 @@ function createDocsAPI(options) {
2903
2924
  llms: llmsConfig,
2904
2925
  sitemap: sitemapConfig,
2905
2926
  robots: robotsConfig,
2906
- openapi: openapiDiscovery,
2927
+ openapi: resolved.kind === "api-catalog" ? withDocsOpenApiOperationCounts(openapiDiscovery, operationPages) : openapiDiscovery,
2907
2928
  markdown: {
2908
2929
  acceptHeader: true,
2909
2930
  signatureAgentHeader: true
@@ -2936,7 +2957,7 @@ function createDocsAPI(options) {
2936
2957
  "Cache-Control": "public, max-age=0, s-maxage=3600",
2937
2958
  "X-Robots-Tag": "noindex"
2938
2959
  } });
2939
- const standardsResponse = await resolveStandardsResponse(request, url);
2960
+ const standardsResponse = await resolveStandardsResponse(request, url, ctx);
2940
2961
  if (standardsResponse) return standardsResponse;
2941
2962
  if (resolveAgentSpecRequest(url)) {
2942
2963
  await emitDocsAnalyticsEvent(analytics, {
@@ -2950,6 +2971,7 @@ function createDocsAPI(options) {
2950
2971
  method: requestMethod
2951
2972
  }
2952
2973
  });
2974
+ const operationPages = await getApiOperationSearchPages(ctx, markdownMetadataBaseUrl || url.origin);
2953
2975
  const fullSpec = buildAgentSpec({
2954
2976
  origin: url.origin,
2955
2977
  entry,
@@ -2963,7 +2985,7 @@ function createDocsAPI(options) {
2963
2985
  llms: llmsConfig,
2964
2986
  sitemap: sitemapConfig,
2965
2987
  robots: robotsConfig,
2966
- openapi: openapiDiscovery,
2988
+ openapi: withDocsOpenApiOperationCounts(openapiDiscovery, operationPages),
2967
2989
  publishedSkills: [await resolveDocsPublishedAgentSkill({
2968
2990
  preferredDocument: readRootSkillDocument(),
2969
2991
  fallbackDocument: getGeneratedSkillDocument(url.origin, requestApiRoute)
@@ -3016,7 +3038,8 @@ function createDocsAPI(options) {
3016
3038
  const document = await buildApiReferenceOpenApiDocumentAsync(apiReferenceDocsConfig, {
3017
3039
  framework: "next",
3018
3040
  rootDir: root,
3019
- baseUrl: url.origin
3041
+ baseUrl: url.origin,
3042
+ version: url.searchParams.get("version")?.trim() || void 0
3020
3043
  });
3021
3044
  return new Response(JSON.stringify(document, null, 2), { headers: {
3022
3045
  "Content-Type": "application/json; charset=utf-8",
@@ -3114,6 +3137,20 @@ function createDocsAPI(options) {
3114
3137
  manifest: readDocsSitemapManifest(root, sitemapConfig)
3115
3138
  });
3116
3139
  if (sitemapResponse) return sitemapResponse;
3140
+ const operationMarkdownResponse = await createApiReferenceOperationMarkdownResponse(apiReferenceDocsConfig, {
3141
+ request,
3142
+ framework: "next",
3143
+ rootDir: root,
3144
+ baseUrl: url.origin,
3145
+ origin: markdownMetadataBaseUrl || url.origin,
3146
+ locale: ctx.locale,
3147
+ apiRoute: requestApiRoute,
3148
+ pages: getIndexes(ctx).map((page) => withPublicDocsUrl(page, ctx)),
3149
+ operationPages: () => getApiOperationSearchPages(ctx, markdownMetadataBaseUrl || url.origin),
3150
+ sitemap: sitemapConfig,
3151
+ okf: options?.agent?.okf
3152
+ });
3153
+ if (operationMarkdownResponse) return operationMarkdownResponse;
3117
3154
  const markdownRequest = resolveMarkdownRequest(entry, url, request) ?? resolvePublicMarkdownRequest(entry, docsPath, url, request);
3118
3155
  if (markdownRequest) {
3119
3156
  const markdownOrigin = markdownMetadataBaseUrl || url.origin;
@@ -3216,7 +3253,7 @@ function createDocsAPI(options) {
3216
3253
  "X-Robots-Tag": "noindex"
3217
3254
  }
3218
3255
  });
3219
- const selected = selectDocsLlmsTxtContent(getLlmsContent(ctx, requestApiRoute), llmsRequest);
3256
+ const selected = selectDocsLlmsTxtContent(await getLlmsContent(ctx, requestApiRoute, markdownMetadataBaseUrl || url.origin), llmsRequest);
3220
3257
  if (!selected) return new Response("Not Found", {
3221
3258
  status: 404,
3222
3259
  headers: {
@@ -3267,8 +3304,9 @@ function createDocsAPI(options) {
3267
3304
  }
3268
3305
  const { filters, structured, explain, facets, facet, cursor, limit } = searchRequest;
3269
3306
  if (!query && !structured && !facets) return new Response("[]", { headers: { "Content-Type": "application/json" } });
3307
+ const operationPages = await getApiOperationSearchPages(ctx, markdownMetadataBaseUrl || url.origin);
3270
3308
  const searchOptions = {
3271
- pages: getIndexes(ctx),
3309
+ pages: [...getIndexes(ctx), ...operationPages],
3272
3310
  query: query ?? "",
3273
3311
  search: resolveSearchRequestConfig(searchConfig, request.url, { localMcp: rawMcpConfig }),
3274
3312
  audience,
@@ -3404,7 +3442,8 @@ function createDocsAPI(options) {
3404
3442
  return Response.json({ error: "AI is not enabled. Set `ai: { enabled: true }` in your docs.config to enable it." }, { status: 404 });
3405
3443
  }
3406
3444
  const ctx = resolveContextFromRequest(request);
3407
- return handleAskAI(request, getIndexes(ctx), aiConfig, cloudConfig, resolveAskAISearchRequestConfig({
3445
+ const operationPages = await getApiOperationSearchPages(ctx, markdownMetadataBaseUrl || url.origin);
3446
+ return handleAskAI(request, [...getIndexes(ctx), ...operationPages], aiConfig, cloudConfig, resolveAskAISearchRequestConfig({
3408
3447
  search: searchConfig,
3409
3448
  useMcp: aiConfig.useMcp,
3410
3449
  mcpEndpoint: mcpConfig.route,
@@ -3469,9 +3508,26 @@ function createDocsMCPAPI(options = {}) {
3469
3508
  }), ...configured];
3470
3509
  }
3471
3510
  };
3511
+ const apiReferenceBaseUrl = options.baseUrl?.trim() || resolveDocsMetadataBaseUrl(options) || void 0;
3512
+ const apiOperationPagesByBaseUrl = /* @__PURE__ */ new Map();
3513
+ function getApiOperationPages(baseUrl) {
3514
+ const key = baseUrl ?? "__default__";
3515
+ const cached = apiOperationPagesByBaseUrl.get(key);
3516
+ if (cached) return cached;
3517
+ const pages = buildApiReferenceOperationPagesAsync(options, {
3518
+ framework: "next",
3519
+ rootDir,
3520
+ baseUrl
3521
+ });
3522
+ apiOperationPagesByBaseUrl.set(key, pages);
3523
+ return pages;
3524
+ }
3472
3525
  const mcpApiReference = resolveApiReferenceConfig(options.apiReference).mcp;
3473
3526
  const handlers = createDocsMcpHttpHandler({
3474
3527
  source,
3528
+ apiReference: { getPages(_locale, context) {
3529
+ return getApiOperationPages(apiReferenceBaseUrl || (context?.request ? new URL(context.request.url).origin : void 0));
3530
+ } },
3475
3531
  mcp: mcpConfig,
3476
3532
  okf: options.agent?.okf,
3477
3533
  openapi: mcpApiReference ? {
@@ -3479,7 +3535,7 @@ function createDocsMCPAPI(options = {}) {
3479
3535
  document: () => buildApiReferenceOpenApiDocumentAsync(options, {
3480
3536
  framework: "next",
3481
3537
  rootDir,
3482
- baseUrl: options.baseUrl?.trim() || resolveDocsMetadataBaseUrl(options) || void 0
3538
+ baseUrl: apiReferenceBaseUrl
3483
3539
  })
3484
3540
  } : void 0,
3485
3541
  contentChanges: options.agent?.contentChanges,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@farming-labs/theme",
3
- "version": "0.2.115",
3
+ "version": "0.2.117",
4
4
  "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
5
5
  "keywords": [
6
6
  "docs",
@@ -161,7 +161,7 @@
161
161
  "tsdown": "^0.20.3",
162
162
  "typescript": "^5.9.3",
163
163
  "vitest": "^4.1.8",
164
- "@farming-labs/docs": "0.2.115"
164
+ "@farming-labs/docs": "0.2.117"
165
165
  },
166
166
  "peerDependencies": {
167
167
  "@farming-labs/docs": ">=0.0.1",