@farming-labs/docs 0.2.62 → 0.2.63

package/dist/server.d.mts

@@ -0,0 +1,343 @@
+import { A as DocsAgentGoldenTask, B as DocsAnalyticsEventInput, Bt as DocsSearchAdapterContext, C as DocsAgentEvaluationTaskInput, D as DocsAgentGoldenAnswerExpectation, Dt as DocsObservabilityConfig, F as DocsAgentTraceEventInput, I as DocsAgentTraceEventType, J as DocsAskAIFeedbackMessage, K as DocsAskAIFeedbackConfig, Kt as DocsSearchQuery, L as DocsAgentTraceStatus, M as DocsAgentGoldenTaskFilters, Mt as DocsReviewCiMode, Nt as DocsReviewConfig, O as DocsAgentGoldenExampleVerification, Ot as DocsObservabilityEvent, Pt as DocsReviewRulesConfig, R as DocsAnalyticsConfig, S as DocsAgentEvaluationSurface, Ut as DocsSearchConfig, Vt as DocsSearchAdapterFactory, Wt as DocsSearchDocument, X as DocsAskAIMcpConfig, Xt as DocsSitemapConfig, Y as DocsAskAIFeedbackValue, Yt as DocsSearchSourcePage, _ as DocsAgentEvaluationAnswerProvider, a as ApiReferenceRenderer, b as DocsAgentEvaluationAnswerRunner, g as DocsAgentEvaluationAnswerInput, it as DocsCodeBlocksPlannerProvider, j as DocsAgentGoldenTaskExpectation, k as DocsAgentGoldenExpectedExample, kt as DocsObservabilityEventInput, pn as McpDocsSearchConfig, q as DocsAskAIFeedbackData, qt as DocsSearchResult, st as DocsCodeBlocksValidateConfig, ut as DocsConfig, v as DocsAgentEvaluationAnswerRequest, x as DocsAgentEvaluationSourceReference, y as DocsAgentEvaluationAnswerResult, z as DocsAnalyticsEvent, zt as DocsSearchAdapter } from "./types-lMBIdZg0.mjs";
+import { n as resolveConfiguredAgentSkills, r as resolveConfiguredAgentSkillsSync, t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-CPja6Syt.mjs";
+import { renderDocsAgentSkillsBundle } from "./agent-skills-vite.mjs";
+import { i as isDocsCloudAskAIProvider, n as DocsCloudAskAIResponseOptions, r as createDocsCloudAskAIResponse, t as DocsCloudAskAIConfig } from "./cloud-ask-ai-zpwkdwnF.mjs";
+import { DocsCloudAskAIOptions, DocsCloudPublicConfig, DocsCloudRouteHandlerOptions, DocsCloudRouteHandlers, DocsCloudRuntimeEnv, DocsCloudRuntimeValue, DocsCloudServer, DocsCloudServerOptions, DocsCloudTrackEventOptions, createDocsCloudRouteHandler, createDocsCloudServer } from "./docs-cloud-server.mjs";
+import { A as resolveDocsSitemapPageLastmod, B as SerializedOpenDocsProvider, C as DocsSitemapResolvedConfig, D as renderDocsSitemapMarkdown, E as readDocsSitemapManifestFromContentMap, F as DEFAULT_OPEN_DOCS_TARGET, G as serializeDocsIcon, H as parsePromptStringArray, I as DEFAULT_PROMPT_PROVIDER_TEMPLATES, J as serializeOpenDocsProviders, K as serializeDocsIconRegistry, L as PromptAction, M as toDocsSitemapMarkdownUrl, N as DEFAULT_OPEN_DOCS_PROMPT, O as renderDocsSitemapXml, P as DEFAULT_OPEN_DOCS_PROVIDER_IDS, R as PromptProviderChoice, S as DocsSitemapPageInput, T as createDocsSitemapResponse, U as resolvePromptProviderChoices, V as normalizePromptProviderName, W as sanitizePromptText, _ as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, a as createMcpSearchAdapter, at as createDocsAgentTraceContext, b as DocsSitemapManifest, c as formatDocsAskAIPackageHints, ct as emitDocsAnalyticsEvent, d as resolveAskAISearchRequestConfig, dt as resolveDocsAnalyticsConfig, f as resolveDocsSearchAudience, ft as resolveDocsObservabilityConfig, g as DEFAULT_SITEMAP_MD_ROUTE, h as DEFAULT_SITEMAP_MD_DOCS_ROUTE, i as createCustomSearchAdapter, it as ResolvedDocsObservabilityConfig, j as resolveDocsSitemapRequest, k as resolveDocsSitemapConfig, l as inferDocsAskAIPackageHints, lt as emitDocsObservabilityEvent, m as DEFAULT_SITEMAP_MANIFEST_PATH, n as buildDocsSearchDocuments, nt as DocsAgentTraceContext, o as createSimpleSearchAdapter, ot as createDocsAgentTraceId, p as resolveSearchRequestConfig, q as serializeOpenDocsProvider, r as createAlgoliaSearchAdapter, rt as ResolvedDocsAnalyticsConfig, s as createTypesenseSearchAdapter, st as emitDocsAgentTraceEvent, t as buildDocsAskAIContext, tt as DOCS_AGENT_TRACE_EVENT_TYPES, u as performDocsSearch, ut as getDocsRequestAnalyticsProperties, v as DEFAULT_SITEMAP_XML_ROUTE, w as buildDocsSitemapManifest, x as DocsSitemapManifestPage, y as DocsSitemapFormat, z as SerializeOpenDocsProviderOptions } from "./search-CaSyi6H6.mjs";
+import { CreateDocsMcpServerOptions, DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, DOCS_CONFIG_SCHEMA_OPTIONS, DocsMcpAgentContractSummary, DocsMcpCodeExample, DocsMcpConfigSchema, DocsMcpConfigSchemaOption, DocsMcpContextResult, DocsMcpContextSource, DocsMcpDocsList, DocsMcpDocsPageSummary, DocsMcpDocsSection, DocsMcpHttpHandlers, DocsMcpNavigationNode, DocsMcpNavigationTree, DocsMcpPage, DocsMcpRequestContext, DocsMcpResolvedConfig, DocsMcpResolvedCorsConfig, DocsMcpResolvedProtectedResourceConfig, DocsMcpResolvedSecurityConfig, DocsMcpSource, DocsMcpTaskSummary, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, getDocsConfigSchema, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
+
+//#region src/code-group-mdx.d.ts
+interface MarkdownNode {
+  type: string;
+  name?: string;
+  children?: MarkdownNode[];
+  lang?: string | null;
+  meta?: string | null;
+}
+declare function remarkCodeGroup(): (tree: MarkdownNode) => void;
+//#endregion
+//#region src/api-reference.d.ts
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+type ApiReferenceFramework = "next" | "tanstack-start" | "sveltekit" | "astro" | "nuxt";
+interface ApiReferenceRoute {
+  title: string;
+  summary: string;
+  description?: string;
+  routePath: string;
+  sourceFile: string;
+  methods: HttpMethod[];
+  tag: string;
+  parameters: Array<Record<string, unknown>>;
+}
+interface ResolvedApiReferenceConfig {
+  enabled: boolean;
+  path: string;
+  specUrl?: string;
+  renderer?: ApiReferenceRenderer;
+  routeRoot: string;
+  exclude: string[];
+}
+interface ApiReferenceOpenApiDiscovery {
+  enabled: boolean;
+  url?: string;
+  urlSource?: "default" | "configured";
+  source?: "generated" | "configured";
+  specUrl?: string;
+  apiReferencePath?: string;
+}
+interface BuildApiReferenceOptions {
+  framework: ApiReferenceFramework;
+  rootDir?: string;
+  baseUrl?: string;
+}
+interface BuildApiReferenceHtmlOptions extends BuildApiReferenceOptions {
+  title?: string;
+}
+declare const DEFAULT_API_REFERENCE_OPENAPI_ROUTE = "/api/docs?format=openapi";
+declare function resolveApiReferenceConfig(value: DocsConfig["apiReference"]): ResolvedApiReferenceConfig;
+declare function resolveApiReferenceRenderer(value: DocsConfig["apiReference"], framework: ApiReferenceFramework): ApiReferenceRenderer;
+declare function resolveApiReferenceOpenApiDiscovery(value: DocsConfig["apiReference"], options?: {
+  route?: string;
+}): ApiReferenceOpenApiDiscovery;
+declare function isApiReferenceOpenApiRequest(url: URL): boolean;
+declare function buildApiReferencePageTitle(config: DocsConfig, title?: string): string;
+declare function buildApiReferenceScalarCss(config: DocsConfig): string;
+declare function buildApiReferenceOpenApiDocument(config: DocsConfig, options: BuildApiReferenceOptions): Record<string, unknown>;
+declare function buildApiReferenceOpenApiDocumentAsync(config: DocsConfig, options: BuildApiReferenceOptions): Promise<Record<string, unknown>>;
+declare function buildApiReferenceHtmlDocument(config: DocsConfig, options: BuildApiReferenceHtmlOptions): string;
+declare function buildApiReferenceHtmlDocumentAsync(config: DocsConfig, options: BuildApiReferenceHtmlOptions): Promise<string>;
+//#endregion
+//#region src/review.d.ts
+declare const DEFAULT_DOCS_REVIEW_WORKFLOW_PATH = ".github/workflows/docs-review.yml";
+declare const DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD = 80;
+interface ResolvedDocsReviewConfig {
+  enabled: boolean;
+  ci: {
+    enabled: boolean;
+    name: string;
+    mode: DocsReviewCiMode;
+    annotations: boolean;
+    comment: boolean;
+  };
+  score: {
+    threshold: number;
+    weights: {
+      error: number;
+      warn: number;
+      suggestion: number;
+    };
+  };
+  rules: Required<DocsReviewRulesConfig>;
+}
+interface DocsReviewWorkflowOptions {
+  packageManager?: "npm" | "pnpm" | "yarn" | "bun";
+  ciName?: string;
+  reusableWorkflow?: string;
+  pnpmVersion?: string;
+  projectDir?: string;
+  configPath?: string;
+  buildCommand?: string;
+  reviewCommand?: string;
+  pathFilters?: string[];
+}
+interface EnsureDocsReviewWorkflowOptions {
+  rootDir: string;
+  config?: DocsConfig;
+  configPath?: string;
+  configContent?: string;
+  workflowPath?: string;
+  log?: (message: string) => void;
+}
+type EnsureDocsReviewWorkflowResult = {
+  status: "created";
+  path: string;
+  relativePath: string;
+} | {
+  status: "exists";
+  path: string;
+  relativePath: string;
+} | {
+  status: "disabled";
+  path: string;
+  relativePath: string;
+};
+declare function resolveDocsReviewConfig(review?: boolean | DocsReviewConfig): ResolvedDocsReviewConfig;
+declare function buildDocsReviewWorkflow(options?: DocsReviewWorkflowOptions): string;
+declare function ensureDocsReviewWorkflow(options: EnsureDocsReviewWorkflowOptions): EnsureDocsReviewWorkflowResult;
+declare function readDocsReviewConfigFromSource(content?: string): boolean | DocsReviewConfig | undefined;
+declare function buildDocsReviewWorkflowPathFilters(options: {
+  rootDir: string;
+  repoRoot?: string;
+  config?: DocsConfig;
+  configPath?: string;
+  configContent?: string;
+}): string[];
+//#endregion
+//#region src/code-blocks.d.ts
+interface DocsCodeBlockTarget {
+  id: string;
+  filePath: string;
+  relativePath: string;
+  lineStart: number;
+  lineEnd: number;
+  language?: string;
+  title?: string;
+  framework?: string;
+  packageManager?: string;
+  runnable: boolean;
+  env: string[];
+  meta: Record<string, string | boolean>;
+  code: string;
+}
+interface DocsCodeBlockCommand {
+  cmd: string;
+  args: string[];
+}
+interface DocsCodeBlockExecutionPlan {
+  id: string;
+  target: DocsCodeBlockTarget;
+  action: "execute" | "validate-syntax" | "skip";
+  template: string;
+  runtime?: string;
+  filePath?: string;
+  command?: DocsCodeBlockCommand;
+  requiredEnv: string[];
+  reason?: string;
+  planner: DocsCodeBlocksPlannerProvider;
+}
+type DocsCodeBlockValidationStatus = "PLAN" | "PASS" | "SKIP" | "FAIL";
+interface DocsCodeBlockValidationResult {
+  id: string;
+  target: DocsCodeBlockTarget;
+  plan: DocsCodeBlockExecutionPlan;
+  status: DocsCodeBlockValidationStatus;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  reason?: string;
+}
+type OptionalModuleImporter = (specifier: string) => Promise<unknown>;
+declare global {
+  var __DOCS_CODE_BLOCKS_MODULE_IMPORTER__: OptionalModuleImporter | undefined;
+}
+//#endregion
+//#region src/agent-evals.d.ts
+type DocsGoldenEvaluationStatus = "unmeasured" | "passed" | "failed";
+type DocsGoldenTaskFilters = DocsAgentGoldenTaskFilters;
+type DocsGoldenExpectedExample = DocsAgentGoldenExpectedExample;
+type DocsGoldenTaskExpectation = DocsAgentGoldenTaskExpectation;
+type DocsGoldenTask = DocsAgentGoldenTask;
+interface DocsGoldenRetrievedSource {
+  rank: number;
+  url: string;
+  title: string;
+  framework?: string;
+  version?: string;
+  utf8Bytes: number;
+  relevant: boolean;
+  truncated: boolean;
+}
+interface DocsGoldenRetrievalMetrics {
+  expectedRelevant: number;
+  retrievedRelevant: number;
+  recallAtK: number;
+  firstRelevantRank: number | null;
+  reciprocalRank: number;
+  forbiddenSources: string[];
+  passed: boolean;
+}
+interface DocsGoldenCitationMetrics {
+  /** Where the citation evidence came from. Context/results are not model-answer citations. */
+  evidence: "context" | "results";
+  expected: string[];
+  actual: string[];
+  missing: string[];
+  unexpected: string[];
+  precision: number;
+  recall: number;
+  /** True when every rendered Source line maps one-to-one to a returned source record. */
+  integrity: boolean;
+  passed: boolean;
+}
+interface DocsGoldenSelectionMetrics {
+  requestedFramework?: string;
+  requestedVersion?: string;
+  requestedLocale?: string;
+  expectedFramework?: string;
+  expectedVersion?: string;
+  expectedLocale?: string;
+  firstFrameworkMatchRank: number | null;
+  firstVersionMatchRank: number | null;
+  firstLocaleMatchRank: number | null;
+  conflictingSources: string[];
+  ambiguousSources: string[];
+  passed: boolean;
+}
+interface DocsGoldenExampleResult {
+  expected: DocsGoldenExpectedExample;
+  matchedId?: string;
+  source?: string;
+  verification: "present" | "syntax" | "execute";
+  status: "passed" | "failed" | "skipped";
+  reason?: string;
+  syntaxValid: boolean;
+  executed: boolean;
+  executionStatus?: DocsCodeBlockValidationResult["status"];
+  /** @deprecated Static/planner executability signal retained for report compatibility. */
+  executable: boolean;
+  passed: boolean;
+}
+interface DocsGoldenExampleMetrics {
+  expected: number;
+  matched: number;
+  syntaxValid: number;
+  executed: number;
+  /** @deprecated Count of statically/planner-executable examples retained for compatibility. */
+  executable: number;
+  results: DocsGoldenExampleResult[];
+  passed: boolean;
+}
+interface DocsGoldenUsageMetrics {
+  budgetUnit: "utf8-bytes";
+  tokenBudget: number;
+  usedUtf8Bytes: number;
+  remainingUtf8Bytes: number;
+  estimatedTokens: number;
+  /** Exact conservative upper bound: one token per UTF-8 byte. */
+  conservativeTokenUpperBound: number;
+  usefulUtf8Bytes: number;
+  usefulByteRatio: number;
+  truncated: boolean;
+  withinBudget: boolean;
+  passed: boolean;
+}
+interface DocsGoldenAnswerMetrics {
+  evidence: "answer";
+  expected: boolean;
+  provided: boolean;
+  textIncludesMissing: string[];
+  textExcludesPresent: string[];
+  citations: string[];
+  requiredCitations: string[];
+  missingCitations: string[];
+  unexpectedCitations: string[];
+  forbiddenCitations: string[];
+  passed: boolean;
+}
+interface DocsGoldenTaskReport {
+  id: string;
+  query: string;
+  surface: DocsAgentEvaluationSurface;
+  provider: string;
+  status: "passed" | "failed";
+  passed: boolean;
+  score: number;
+  context: string;
+  sources: DocsGoldenRetrievedSource[];
+  retrieval: DocsGoldenRetrievalMetrics;
+  citations: DocsGoldenCitationMetrics;
+  answer: DocsGoldenAnswerMetrics;
+  selection: DocsGoldenSelectionMetrics;
+  examples: DocsGoldenExampleMetrics;
+  usage: DocsGoldenUsageMetrics;
+  issues: string[];
+}
+interface DocsGoldenTasksReport {
+  status: DocsGoldenEvaluationStatus;
+  passed: boolean | null;
+  score: number | null;
+  taskCount: number;
+  passedTaskCount: number;
+  failedTaskCount: number;
+  tasks: DocsGoldenTaskReport[];
+}
+interface RunDocsGoldenTasksOptions {
+  /** Default evaluation surface. Tasks may override this with `task.surface`. */
+  surface?: DocsAgentEvaluationSurface;
+  /** Search configuration used by configured-search and ask-ai-context. */
+  search?: boolean | DocsSearchConfig;
+  /** Production-resolved Ask AI retrieval config, including `ai.useMcp`. */
+  askAISearch?: boolean | DocsSearchConfig;
+  siteTitle?: string;
+  baseUrl?: string;
+  rootDir?: string;
+  /** Permit external configured search or HTTP answer calls. @default false */
+  allowNetwork?: boolean;
+  /** Per-task configured-search/Ask-AI retrieval timeout in milliseconds. @default 30000 */
+  searchTimeoutMs?: number;
+  /** Project code-block validation config used only by explicit execute expectations. */
+  codeBlocksValidate?: boolean | DocsCodeBlocksValidateConfig;
+  /** Optional actual-answer runner. No model or HTTP request is made when omitted. */
+  answer?: DocsAgentEvaluationAnswerProvider;
+}
+/**
+ * Run offline-by-default golden-task evaluations against MCP-ready docs pages.
+ * Configured external retrieval, HTTP answers, and runtime execution require explicit opt-in.
+ * An empty task list is intentionally unmeasured so CI cannot turn absent coverage into a pass.
+ */
+declare function runDocsGoldenTasks(pages: readonly DocsMcpPage[], tasks: readonly DocsGoldenTask[] | undefined, options?: RunDocsGoldenTasksOptions): Promise<DocsGoldenTasksReport>;
+//#endregion
+//#region src/sitemap-server.d.ts
+declare function readDocsSitemapManifest(rootDir: string, sitemap?: boolean | DocsSitemapConfig): DocsSitemapManifest | null;
+//#endregion
+export { type ApiReferenceFramework, type ApiReferenceOpenApiDiscovery, type ApiReferenceRenderer, type ApiReferenceRoute, type CreateDocsMcpServerOptions, DEFAULT_API_REFERENCE_OPENAPI_ROUTE, DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD, DEFAULT_DOCS_REVIEW_WORKFLOW_PATH, DEFAULT_OPEN_DOCS_PROMPT, DEFAULT_OPEN_DOCS_PROVIDER_IDS, DEFAULT_OPEN_DOCS_TARGET, DEFAULT_PROMPT_PROVIDER_TEMPLATES, DEFAULT_SITEMAP_MANIFEST_PATH, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DEFAULT_SITEMAP_MD_ROUTE, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, DEFAULT_SITEMAP_XML_ROUTE, DOCS_AGENT_TRACE_EVENT_TYPES, DOCS_CONFIG_SCHEMA_OPTIONS, type DocsAgentEvaluationAnswerInput, type DocsAgentEvaluationAnswerProvider, type DocsAgentEvaluationAnswerRequest, type DocsAgentEvaluationAnswerResult, type DocsAgentEvaluationAnswerRunner, type DocsAgentEvaluationSourceReference, type DocsAgentEvaluationSurface, type DocsAgentEvaluationTaskInput, type DocsAgentGoldenAnswerExpectation, type DocsAgentGoldenExampleVerification, type DocsAgentTraceContext, type DocsAgentTraceEventInput, type DocsAgentTraceEventType, type DocsAgentTraceStatus, type DocsAnalyticsConfig, type DocsAnalyticsEvent, type DocsAnalyticsEventInput, type DocsAskAIFeedbackConfig, type DocsAskAIFeedbackData, type DocsAskAIFeedbackMessage, type DocsAskAIFeedbackValue, type DocsAskAIMcpConfig, type DocsCloudAskAIConfig, type DocsCloudAskAIOptions, type DocsCloudAskAIResponseOptions, type DocsCloudPublicConfig, type DocsCloudRouteHandlerOptions, type DocsCloudRouteHandlers, type DocsCloudRuntimeEnv, type DocsCloudRuntimeValue, type DocsCloudServer, type DocsCloudServerOptions, type DocsCloudTrackEventOptions, type DocsGoldenAnswerMetrics, type DocsGoldenCitationMetrics, type DocsGoldenEvaluationStatus, type DocsGoldenExampleMetrics, type DocsGoldenExampleResult, type DocsGoldenExpectedExample, type DocsGoldenRetrievalMetrics, type DocsGoldenRetrievedSource, type DocsGoldenSelectionMetrics, type DocsGoldenTask, type DocsGoldenTaskExpectation, type DocsGoldenTaskFilters, type DocsGoldenTaskReport, type DocsGoldenTasksReport, type DocsGoldenUsageMetrics, type DocsMcpAgentContractSummary, type DocsMcpCodeExample, type DocsMcpConfigSchema, type DocsMcpConfigSchemaOption, type DocsMcpContextResult, type DocsMcpContextSource, type DocsMcpDocsList, type DocsMcpDocsPageSummary, type DocsMcpDocsSection, type DocsMcpHttpHandlers, type DocsMcpNavigationNode, type DocsMcpNavigationTree, type DocsMcpPage, type DocsMcpRequestContext, type DocsMcpResolvedConfig, type DocsMcpResolvedCorsConfig, type DocsMcpResolvedProtectedResourceConfig, type DocsMcpResolvedSecurityConfig, type DocsMcpSource, type DocsMcpTaskSummary, type DocsObservabilityConfig, type DocsObservabilityEvent, type DocsObservabilityEventInput, type DocsSearchAdapter, type DocsSearchAdapterContext, type DocsSearchAdapterFactory, type DocsSearchConfig, type DocsSearchDocument, type DocsSearchQuery, type DocsSearchResult, type DocsSearchSourcePage, type DocsSitemapFormat, type DocsSitemapManifest, type DocsSitemapManifestPage, type DocsSitemapPageInput, type DocsSitemapResolvedConfig, type McpDocsSearchConfig, type PromptAction, type PromptProviderChoice, type ResolveConfiguredAgentSkillsOptions, type ResolvedApiReferenceConfig, type ResolvedDocsAnalyticsConfig, type ResolvedDocsObservabilityConfig, type ResolvedDocsReviewConfig, type RunDocsGoldenTasksOptions, type SerializeOpenDocsProviderOptions, type SerializedOpenDocsProvider, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, buildDocsAskAIContext, buildDocsReviewWorkflow, buildDocsReviewWorkflowPathFilters, buildDocsSearchDocuments, buildDocsSitemapManifest, createAlgoliaSearchAdapter, createCustomSearchAdapter, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsCloudAskAIResponse, createDocsCloudRouteHandler, createDocsCloudServer, createDocsMcpHttpHandler, createDocsMcpServer, createDocsSitemapResponse, createFilesystemDocsMcpSource, createMcpSearchAdapter, createSimpleSearchAdapter, createTypesenseSearchAdapter, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsObservabilityEvent, ensureDocsReviewWorkflow, formatDocsAskAIPackageHints, getDocsConfigSchema, getDocsRequestAnalyticsProperties, inferDocsAskAIPackageHints, isApiReferenceOpenApiRequest, isDocsCloudAskAIProvider, normalizeDocsMcpRoute, normalizePromptProviderName, parsePromptStringArray, performDocsSearch, readDocsReviewConfigFromSource, readDocsSitemapManifest, readDocsSitemapManifestFromContentMap, remarkCodeGroup, renderDocsAgentSkillsBundle, renderDocsSitemapMarkdown, renderDocsSitemapXml, resolveApiReferenceConfig, resolveApiReferenceOpenApiDiscovery, resolveApiReferenceRenderer, resolveAskAISearchRequestConfig, resolveConfiguredAgentSkills, resolveConfiguredAgentSkillsSync, resolveDocsAnalyticsConfig, resolveDocsMcpConfig, resolveDocsObservabilityConfig, resolveDocsReviewConfig, resolveDocsSearchAudience, resolveDocsSitemapConfig, resolveDocsSitemapPageLastmod, resolveDocsSitemapRequest, resolvePromptProviderChoices, resolveSearchRequestConfig, runDocsGoldenTasks, runDocsMcpStdio, sanitizePromptText, serializeDocsIcon, serializeDocsIconRegistry, serializeOpenDocsProvider, serializeOpenDocsProviders, toDocsSitemapMarkdownUrl };

package/dist/server.mjs

@@ -0,0 +1,14 @@
+import { a as emitDocsAnalyticsEvent, c as resolveDocsAnalyticsConfig, i as emitDocsAgentTraceEvent, l as resolveDocsObservabilityConfig, n as createDocsAgentTraceContext, o as emitDocsObservabilityEvent, r as createDocsAgentTraceId, s as getDocsRequestAnalyticsProperties, t as DOCS_AGENT_TRACE_EVENT_TYPES } from "./analytics-Bx44lg6d.mjs";
+import { At as buildDocsSitemapManifest, Dt as DEFAULT_SITEMAP_MD_ROUTE, Et as DEFAULT_SITEMAP_MD_DOCS_ROUTE, Ft as resolveDocsSitemapConfig, It as resolveDocsSitemapPageLastmod, Lt as resolveDocsSitemapRequest, Mt as readDocsSitemapManifestFromContentMap, Nt as renderDocsSitemapMarkdown, Ot as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, Pt as renderDocsSitemapXml, Rt as toDocsSitemapMarkdownUrl, Tt as DEFAULT_SITEMAP_MANIFEST_PATH, jt as createDocsSitemapResponse, kt as DEFAULT_SITEMAP_XML_ROUTE } from "./agent-DKKptIgy.mjs";
+import "./standards-discovery-jkykaXq1.mjs";
+import { a as createMcpSearchAdapter, c as formatDocsAskAIPackageHints, d as resolveAskAISearchRequestConfig, f as resolveDocsSearchAudience, i as createCustomSearchAdapter, l as inferDocsAskAIPackageHints, n as buildDocsSearchDocuments, o as createSimpleSearchAdapter, p as resolveSearchRequestConfig, r as createAlgoliaSearchAdapter, s as createTypesenseSearchAdapter, t as buildDocsAskAIContext, u as performDocsSearch } from "./search-B6V6qtiI.mjs";
+import { C as resolveApiReferenceOpenApiDiscovery, S as resolveApiReferenceConfig, T as remarkCodeGroup, _ as buildApiReferenceOpenApiDocument, a as DEFAULT_PROMPT_PROVIDER_TEMPLATES, b as buildApiReferenceScalarCss, c as resolvePromptProviderChoices, d as serializeDocsIconRegistry, f as serializeOpenDocsProvider, g as buildApiReferenceHtmlDocumentAsync, h as buildApiReferenceHtmlDocument, i as DEFAULT_OPEN_DOCS_TARGET, l as sanitizePromptText, m as DEFAULT_API_REFERENCE_OPENAPI_ROUTE, n as DEFAULT_OPEN_DOCS_PROMPT, o as normalizePromptProviderName, p as serializeOpenDocsProviders, r as DEFAULT_OPEN_DOCS_PROVIDER_IDS, s as parsePromptStringArray, t as readDocsSitemapManifest, u as serializeDocsIcon, v as buildApiReferenceOpenApiDocumentAsync, w as resolveApiReferenceRenderer, x as isApiReferenceOpenApiRequest, y as buildApiReferencePageTitle } from "./sitemap-server-C_6Wes83.mjs";
+import { a as buildDocsReviewWorkflowPathFilters, c as resolveDocsReviewConfig, i as buildDocsReviewWorkflow, n as DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD, o as ensureDocsReviewWorkflow, r as DEFAULT_DOCS_REVIEW_WORKFLOW_PATH, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-B7MIxuEX.mjs";
+import { DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, DOCS_CONFIG_SCHEMA_OPTIONS, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, getDocsConfigSchema, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
+import { n as isDocsCloudAskAIProvider, t as createDocsCloudAskAIResponse } from "./cloud-ask-ai-sbpjOR2K.mjs";
+import { createDocsCloudRouteHandler, createDocsCloudServer } from "./docs-cloud-server.mjs";
+import "./code-blocks-DnNVNK2M.mjs";
+import { n as resolveConfiguredAgentSkillsSync, t as resolveConfiguredAgentSkills } from "./agent-skills-server-DraIb6FV.mjs";
+import { renderDocsAgentSkillsBundle } from "./agent-skills-vite.mjs";
+
+export { DEFAULT_API_REFERENCE_OPENAPI_ROUTE, DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD, DEFAULT_DOCS_REVIEW_WORKFLOW_PATH, DEFAULT_OPEN_DOCS_PROMPT, DEFAULT_OPEN_DOCS_PROVIDER_IDS, DEFAULT_OPEN_DOCS_TARGET, DEFAULT_PROMPT_PROVIDER_TEMPLATES, DEFAULT_SITEMAP_MANIFEST_PATH, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DEFAULT_SITEMAP_MD_ROUTE, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, DEFAULT_SITEMAP_XML_ROUTE, DOCS_AGENT_TRACE_EVENT_TYPES, DOCS_CONFIG_SCHEMA_OPTIONS, buildApiReferenceHtmlDocument, buildApiReferenceHtmlDocumentAsync, buildApiReferenceOpenApiDocument, buildApiReferenceOpenApiDocumentAsync, buildApiReferencePageTitle, buildApiReferenceScalarCss, buildDocsAskAIContext, buildDocsReviewWorkflow, buildDocsReviewWorkflowPathFilters, buildDocsSearchDocuments, buildDocsSitemapManifest, createAlgoliaSearchAdapter, createCustomSearchAdapter, createDocsAgentTraceContext, createDocsAgentTraceId, createDocsCloudAskAIResponse, createDocsCloudRouteHandler, createDocsCloudServer, createDocsMcpHttpHandler, createDocsMcpServer, createDocsSitemapResponse, createFilesystemDocsMcpSource, createMcpSearchAdapter, createSimpleSearchAdapter, createTypesenseSearchAdapter, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, emitDocsObservabilityEvent, ensureDocsReviewWorkflow, formatDocsAskAIPackageHints, getDocsConfigSchema, getDocsRequestAnalyticsProperties, inferDocsAskAIPackageHints, isApiReferenceOpenApiRequest, isDocsCloudAskAIProvider, normalizeDocsMcpRoute, normalizePromptProviderName, parsePromptStringArray, performDocsSearch, readDocsReviewConfigFromSource, readDocsSitemapManifest, readDocsSitemapManifestFromContentMap, remarkCodeGroup, renderDocsAgentSkillsBundle, renderDocsSitemapMarkdown, renderDocsSitemapXml, resolveApiReferenceConfig, resolveApiReferenceOpenApiDiscovery, resolveApiReferenceRenderer, resolveAskAISearchRequestConfig, resolveConfiguredAgentSkills, resolveConfiguredAgentSkillsSync, resolveDocsAnalyticsConfig, resolveDocsMcpConfig, resolveDocsObservabilityConfig, resolveDocsReviewConfig, resolveDocsSearchAudience, resolveDocsSitemapConfig, resolveDocsSitemapPageLastmod, resolveDocsSitemapRequest, resolvePromptProviderChoices, resolveSearchRequestConfig, runDocsGoldenTasks, runDocsMcpStdio, sanitizePromptText, serializeDocsIcon, serializeDocsIconRegistry, serializeOpenDocsProvider, serializeOpenDocsProviders, toDocsSitemapMarkdownUrl };

package/dist/sitemap-Cykpe3Tz.mjs

@@ -0,0 +1,249 @@
+import { At as buildDocsSitemapManifest, Ft as resolveDocsSitemapConfig, Nt as renderDocsSitemapMarkdown, Pt as renderDocsSitemapXml } from "./agent-DKKptIgy.mjs";
+import "./standards-discovery-jkykaXq1.mjs";
+import "./search-B6V6qtiI.mjs";
+import "./sitemap-server-C_6Wes83.mjs";
+import "./agent-evals-B7MIxuEX.mjs";
+import { createFilesystemDocsMcpSource } from "./mcp.mjs";
+import "./code-blocks-DnNVNK2M.mjs";
+import "./agent-skills-server-DraIb6FV.mjs";
+import "./server.mjs";
+import { _ as resolveDocsContentDir, a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { t as detectFramework } from "./utils-DpiIioYb.mjs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import pc from "picocolors";
+
+//#region src/cli/sitemap.ts
+function normalizePathSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "");
+}
+function parseInlineFlag(arg) {
+	const [rawKey, value] = arg.slice(2).split("=", 2);
+	return {
+		key: rawKey.trim(),
+		value
+	};
+}
+function parseSitemapGenerateArgs(argv) {
+	const parsed = {};
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "--public") {
+			parsed.public = true;
+			continue;
+		}
+		if (arg === "--manifest-only") {
+			parsed.manifestOnly = true;
+			continue;
+		}
+		if (arg === "--check") {
+			parsed.check = true;
+			continue;
+		}
+		if (arg.startsWith("--config=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --config.");
+			parsed.configPath = value;
+			continue;
+		}
+		if (arg === "--config") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --config.");
+			parsed.configPath = value;
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown sitemap generate flag: ${arg}.`);
+	}
+	return parsed;
+}
+function readLlmsBaseUrlFromConfig(content, config) {
+	if (config?.llmsTxt && typeof config.llmsTxt === "object") return config.llmsTxt.baseUrl;
+	const block = extractNestedObjectLiteral(content, ["llmsTxt"]);
+	return block ? readStringProperty(block, "baseUrl") : void 0;
+}
+function readSitemapConfigFromStatic(content) {
+	if (/\bsitemap\s*:\s*false/.test(content)) return false;
+	if (/\bsitemap\s*:\s*true/.test(content)) return true;
+	const block = extractNestedObjectLiteral(content, ["sitemap"]);
+	if (!block) return void 0;
+	return {
+		enabled: readBooleanProperty(block, "enabled") ?? true,
+		routePrefix: readStringProperty(block, "routePrefix"),
+		baseUrl: readStringProperty(block, "baseUrl"),
+		manifestPath: readStringProperty(block, "manifestPath")
+	};
+}
+function resolveConfiguredSitemap(content, config) {
+	if (config?.sitemap !== void 0) return config.sitemap;
+	return readSitemapConfigFromStatic(content) ?? true;
+}
+function formatDateOnly(value) {
+	const parsed = new Date(value);
+	if (Number.isNaN(parsed.getTime())) return void 0;
+	return parsed.toISOString().slice(0, 10);
+}
+function gitLastCommitDate(rootDir, sourcePath) {
+	if (!sourcePath) return void 0;
+	try {
+		return formatDateOnly(execFileSync("git", [
+			"log",
+			"-1",
+			"--format=%cI",
+			"--",
+			sourcePath
+		], {
+			cwd: rootDir,
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim());
+	} catch {
+		return;
+	}
+}
+function fileModifiedDate(rootDir, sourcePath) {
+	if (!sourcePath) return void 0;
+	const fullPath = path.isAbsolute(sourcePath) ? sourcePath : path.join(rootDir, sourcePath);
+	if (!existsSync(fullPath)) return void 0;
+	try {
+		return statSync(fullPath).mtime.toISOString().slice(0, 10);
+	} catch {
+		return;
+	}
+}
+function writeIfChanged(filePath, content, check) {
+	if ((existsSync(filePath) ? readFileSync(filePath, "utf-8") : void 0) === content) return false;
+	if (check) return true;
+	mkdirSync(path.dirname(filePath), { recursive: true });
+	writeFileSync(filePath, content, "utf-8");
+	return true;
+}
+function readExistingManifest(filePath) {
+	if (!existsSync(filePath)) return void 0;
+	try {
+		return JSON.parse(readFileSync(filePath, "utf-8"));
+	} catch {
+		return;
+	}
+}
+function comparableManifest(manifest) {
+	return {
+		...manifest,
+		generatedAt: ""
+	};
+}
+function preserveGeneratedAtWhenUnchanged(manifest, existing) {
+	if (!existing?.generatedAt) return manifest;
+	if (JSON.stringify(comparableManifest(manifest)) !== JSON.stringify(comparableManifest(existing))) return manifest;
+	return {
+		...manifest,
+		generatedAt: existing.generatedAt
+	};
+}
+function resolvePublicDir(rootDir) {
+	if (detectFramework(rootDir) === "sveltekit") return path.join(rootDir, "static");
+	return path.join(rootDir, "public");
+}
+function publicFilePath(rootDir, route) {
+	return path.join(resolvePublicDir(rootDir), route.replace(/^\/+/, ""));
+}
+async function generateSitemap(options = {}) {
+	const rootDir = process.cwd();
+	const loadedConfigModule = await loadDocsConfigModule(rootDir, options.configPath);
+	const configContent = readFileSync(loadedConfigModule?.path ?? resolveDocsConfigPath(rootDir, options.configPath), "utf-8");
+	const config = loadedConfigModule?.config;
+	const entry = normalizePathSegment(config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs") || "docs";
+	const contentDir = typeof config?.contentDir === "string" ? config.contentDir : resolveDocsContentDir(rootDir, configContent, entry);
+	const siteTitle = typeof config?.nav?.title === "string" ? config.nav.title : readNavTitle(configContent) ?? "Documentation";
+	const sitemapInput = resolveConfiguredSitemap(configContent, config);
+	if (sitemapInput === false) throw new Error("Sitemap generation is disabled by `sitemap: false`.");
+	const sitemap = resolveDocsSitemapConfig(sitemapInput, { baseUrl: (typeof sitemapInput === "object" ? sitemapInput.baseUrl : void 0) ?? readLlmsBaseUrlFromConfig(configContent, config) });
+	const source = createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle,
+		ordering: config?.ordering
+	});
+	const pages = await Promise.resolve(source.getPages());
+	if (pages.length === 0) throw new Error(`No docs content was found under ${contentDir}.`);
+	const builtManifest = buildDocsSitemapManifest({
+		pages,
+		entry,
+		siteTitle,
+		baseUrl: sitemap.baseUrl,
+		resolveLastmod(page) {
+			const gitDate = gitLastCommitDate(rootDir, page.sourcePath);
+			if (gitDate) return {
+				lastmod: gitDate,
+				lastmodSource: "git"
+			};
+			const fsDate = fileModifiedDate(rootDir, page.sourcePath);
+			if (fsDate) return {
+				lastmod: fsDate,
+				lastmodSource: "filesystem"
+			};
+		}
+	});
+	const manifestPath = path.resolve(rootDir, sitemap.manifestPath);
+	const manifest = preserveGeneratedAtWhenUnchanged(builtManifest, readExistingManifest(manifestPath));
+	const manifestChanged = writeIfChanged(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, options.check === true);
+	const shouldWritePublic = options.manifestOnly !== true;
+	const publicWrites = [];
+	if (shouldWritePublic) {
+		const xml = renderDocsSitemapXml(manifest, {
+			baseUrl: sitemap.baseUrl,
+			includeLastmod: sitemap.xml.includeLastmod
+		});
+		const markdown = renderDocsSitemapMarkdown(manifest, {
+			baseUrl: sitemap.baseUrl,
+			includeDescriptions: sitemap.markdown.includeDescriptions,
+			includeLastmod: sitemap.markdown.includeLastmod,
+			linkTarget: sitemap.markdown.linkTarget
+		});
+		if (sitemap.xml.enabled) {
+			const filePath = publicFilePath(rootDir, sitemap.xml.route);
+			if (writeIfChanged(filePath, xml, options.check === true)) publicWrites.push(filePath);
+		}
+		if (sitemap.markdown.enabled) for (const route of [
+			sitemap.markdown.route,
+			sitemap.markdown.docsRoute,
+			sitemap.markdown.wellKnownRoute
+		]) {
+			if (!route) continue;
+			const filePath = publicFilePath(rootDir, route);
+			if (writeIfChanged(filePath, markdown, options.check === true)) publicWrites.push(filePath);
+		}
+	}
+	if (options.check && (manifestChanged || publicWrites.length > 0)) throw new Error("Sitemap output is stale. Run `docs sitemap generate` to update it.");
+	console.log(pc.green(`Generated sitemap manifest for ${manifest.pages.length} page(s).`));
+	console.log(pc.dim(path.relative(rootDir, manifestPath)));
+	for (const filePath of publicWrites) console.log(pc.dim(path.relative(rootDir, filePath)));
+}
+function printSitemapGenerateHelp() {
+	console.log(`
+${pc.bold("docs sitemap generate")} — Generate sitemap metadata and static sitemap files.
+
+${pc.dim("Usage:")}
+  pnpm exec docs ${pc.cyan("sitemap generate")}
+
+${pc.dim("Options:")}
+  ${pc.cyan("--config <path>")}     Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
+  ${pc.cyan("--public")}            Explicitly write public sitemap.xml, sitemap.md, and docs/sitemap.md files
+  ${pc.cyan("--manifest-only")}     Only write the internal sitemap manifest
+  ${pc.cyan("--check")}             Fail if generated output is stale
+  ${pc.cyan("-h, --help")}          Show this help message
+`);
+}
+
+//#endregion
+export { generateSitemap, parseSitemapGenerateArgs, printSitemapGenerateHelp };