@farming-labs/docs 0.2.62 → 0.2.64

package/dist/search-CaSyi6H6.d.mts

@@ -0,0 +1,279 @@
+import { k as DocsDiscoveryApiRouteOptions } from "./standards-discovery-C4HUqMd2.mjs";
+import { B as DocsAnalyticsEventInput, Dt as DocsObservabilityConfig, F as DocsAgentTraceEventInput, Ht as DocsSearchChunkingConfig, Ot as DocsObservabilityEvent, Pn as ResolvedDocsRelatedLink, R as DocsAnalyticsConfig, Ut as DocsSearchConfig, Vt as DocsSearchAdapterFactory, Wn as TypesenseDocsSearchConfig, Wt as DocsSearchDocument, X as DocsAskAIMcpConfig, Xt as DocsSitemapConfig, Yt as DocsSearchSourcePage, f as CustomDocsSearchConfig, gn as OpenDocsProvider, kt as DocsObservabilityEventInput, pn as McpDocsSearchConfig, qt as DocsSearchResult, r as AlgoliaDocsSearchConfig, yn as OpenDocsTarget, z as DocsAnalyticsEvent, zt as DocsSearchAdapter } from "./types-lMBIdZg0.mjs";
+
+//#region src/analytics.d.ts
+declare const DOCS_AGENT_TRACE_EVENT_TYPES: readonly ["run.start", "run.end", "run.error", "user.input", "prompt.build", "retrieval.query", "retrieval.result", "retrieval.error", "model.call", "model.response", "model.stream", "model.error", "tool.call", "tool.result", "tool.error", "retry", "timeout", "error", "agent.final"];
+interface DocsAgentTraceContext {
+  traceId: string;
+  name: string;
+  startedAt: string;
+  startedMs: number;
+}
+interface ResolvedDocsAnalyticsConfig {
+  enabled: boolean;
+  console: false | "log" | "info" | "debug";
+  includeInputs: boolean;
+  onEvent?: (event: DocsAnalyticsEvent) => void | Promise<void>;
+}
+interface ResolvedDocsObservabilityConfig {
+  enabled: boolean;
+  console: false | "log" | "info" | "debug";
+  includeInputs: boolean;
+  onEvent?: (event: DocsObservabilityEvent) => void | Promise<void>;
+}
+declare function createDocsAgentTraceId(prefix?: string): string;
+declare function createDocsAgentTraceContext(name?: string): DocsAgentTraceContext;
+declare function getDocsRequestAnalyticsProperties(request: Request): Record<string, unknown>;
+declare function resolveDocsAnalyticsConfig(analytics?: boolean | DocsAnalyticsConfig): ResolvedDocsAnalyticsConfig;
+declare function resolveDocsObservabilityConfig(observability?: boolean | DocsObservabilityConfig): ResolvedDocsObservabilityConfig;
+declare function emitDocsAnalyticsEvent(analytics: boolean | DocsAnalyticsConfig | undefined, event: DocsAnalyticsEventInput): Promise<void>;
+declare function emitDocsObservabilityEvent(observability: boolean | DocsObservabilityConfig | undefined, event: DocsObservabilityEventInput): Promise<void>;
+declare function emitDocsAgentTraceEvent(observability: boolean | DocsObservabilityConfig | undefined, event: DocsAgentTraceEventInput): Promise<void>;
+//#endregion
+//#region src/audience.d.ts
+/** The two content projections emitted by the docs framework. */
+type DocsContentAudience = "human" | "agent";
+/** Resolve whether content with an optional audience restriction is visible. */
+declare function resolveDocsAudienceExposure(only: unknown, audience: DocsContentAudience): boolean;
+interface DocsAudienceMdxIssue {
+  code: "missing-only" | "invalid-only" | "dynamic-only" | "ignored-agent-only" | "ignored-human-only";
+  index: number;
+  message: string;
+}
+/** Find audience declarations that cannot be projected consistently at build time. */
+declare function findDocsAudienceMdxIssues(content: string): DocsAudienceMdxIssue[];
+/**
+ * Resolve MDX into its human or agent projection.
+ *
+ * `<Agent>` is shorthand for `<Audience only="agent">`, while `<Human>` is
+ * shorthand for `<Audience only="human">`. Unknown `Audience.only` values are
+ * treated as shared content so an authoring typo never silently deletes content.
+ * These primitives shape content for each surface; they are not an access-control boundary.
+ */
+declare function resolveDocsAudienceMdxContent(content: string, audience: DocsContentAudience): string;
+/** Backwards-compatible name retained for existing integrations. */
+declare function resolveDocsAgentMdxContent(content: string, audience: DocsContentAudience): string;
+//#endregion
+//#region src/prompt-utils.d.ts
+type PromptAction = "copy" | "open";
+interface SerializedOpenDocsProvider {
+  name: string;
+  iconHtml?: string;
+  urlTemplate: string;
+  promptUrlTemplate?: string;
+  target?: OpenDocsTarget;
+  prompt?: string;
+}
+interface PromptProviderChoice {
+  name: string;
+  iconHtml?: string;
+  urlTemplate: string;
+}
+type PromptProviderInput = Pick<SerializedOpenDocsProvider, "name" | "iconHtml"> & Partial<Pick<SerializedOpenDocsProvider, "promptUrlTemplate" | "urlTemplate">>;
+interface SerializeOpenDocsProviderOptions {
+  target?: OpenDocsTarget;
+  prompt?: string;
+}
+declare const DEFAULT_PROMPT_PROVIDER_TEMPLATES: Record<string, string>;
+declare const DEFAULT_OPEN_DOCS_TARGET: OpenDocsTarget;
+declare const DEFAULT_OPEN_DOCS_PROMPT = "Read this documentation: {url}";
+declare const DEFAULT_OPEN_DOCS_PROVIDER_IDS: readonly ["chatgpt", "claude"];
+declare function normalizePromptProviderName(name: string): string;
+declare function serializeDocsIcon(icon: unknown): string | undefined;
+declare function serializeDocsIconRegistry(icons?: Record<string, unknown>): Record<string, string> | undefined;
+declare function serializeOpenDocsProviders(providers?: OpenDocsProvider[], options?: SerializeOpenDocsProviderOptions): SerializedOpenDocsProvider[] | undefined;
+declare function serializeOpenDocsProvider(provider: OpenDocsProvider, options?: SerializeOpenDocsProviderOptions): SerializedOpenDocsProvider | undefined;
+declare function parsePromptStringArray(value: unknown): string[] | undefined;
+declare function resolvePromptProviderChoices(availableProviders?: PromptProviderInput[], preferredNames?: string[]): PromptProviderChoice[];
+declare function sanitizePromptText(text: string): string;
+//#endregion
+//#region src/sitemap.d.ts
+declare const DEFAULT_SITEMAP_XML_ROUTE = "/sitemap.xml";
+declare const DEFAULT_SITEMAP_MD_ROUTE = "/sitemap.md";
+declare const DEFAULT_SITEMAP_MD_DOCS_ROUTE = "/docs/sitemap.md";
+declare const DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE = "/.well-known/sitemap.md";
+declare const DEFAULT_SITEMAP_MANIFEST_PATH = ".farming-labs/sitemap-manifest.json";
+type DocsSitemapFormat = "xml" | "markdown";
+interface DocsSitemapPageInput {
+  slug?: string;
+  url: string;
+  /** Override the public Markdown representation URL when it differs from `${url}.md`. */
+  markdownUrl?: string;
+  title: string;
+  description?: string;
+  related?: ResolvedDocsRelatedLink[];
+  sourcePath?: string;
+  lastmod?: string;
+  lastModified?: string;
+}
+interface DocsSitemapManifestPage {
+  url: string;
+  absoluteUrl?: string;
+  markdownUrl: string;
+  title: string;
+  description?: string;
+  sourcePath?: string;
+  lastmod?: string;
+  lastmodSource?: "git" | "filesystem" | "frontmatter" | "manifest" | "unknown";
+  related?: string[];
+}
+interface DocsSitemapManifest {
+  version: 1;
+  generatedAt: string;
+  baseUrl?: string;
+  entry: string;
+  siteTitle?: string;
+  pages: DocsSitemapManifestPage[];
+}
+interface DocsSitemapResolvedConfig {
+  enabled: boolean;
+  routePrefix: string;
+  baseUrl?: string;
+  manifestPath: string;
+  xml: {
+    enabled: boolean;
+    includeLastmod: boolean;
+    route: string;
+  };
+  markdown: {
+    enabled: boolean;
+    includeDescriptions: boolean;
+    includeLastmod: boolean;
+    linkTarget: "html" | "markdown" | "both";
+    route: string;
+    docsRoute?: string;
+    wellKnownRoute: string;
+  };
+}
+interface CreateDocsSitemapResponseOptions extends DocsDiscoveryApiRouteOptions {
+  request: Request;
+  sitemap?: boolean | DocsSitemapConfig;
+  entry?: string;
+  siteTitle?: string;
+  baseUrl?: string;
+  pages: DocsSitemapPageInput[];
+  manifest?: DocsSitemapManifest | null;
+}
+declare function resolveDocsSitemapConfig(sitemap?: boolean | DocsSitemapConfig, defaults?: {
+  baseUrl?: string;
+}): DocsSitemapResolvedConfig;
+declare function resolveDocsSitemapRequest(url: URL, sitemap?: boolean | DocsSitemapConfig, options?: DocsDiscoveryApiRouteOptions): DocsSitemapFormat | null;
+declare function toDocsSitemapMarkdownUrl(url: string): string;
+declare function buildDocsSitemapManifest(options: {
+  pages: DocsSitemapPageInput[];
+  entry?: string;
+  siteTitle?: string;
+  baseUrl?: string;
+  generatedAt?: string;
+  resolveLastmod?: (page: DocsSitemapPageInput) => {
+    lastmod?: string;
+    lastmodSource?: DocsSitemapManifestPage["lastmodSource"];
+  } | undefined;
+}): DocsSitemapManifest;
+declare function renderDocsSitemapXml(manifest: DocsSitemapManifest, options?: {
+  baseUrl?: string;
+  includeLastmod?: boolean;
+}): string;
+declare function renderDocsSitemapMarkdown(manifest: DocsSitemapManifest, options?: {
+  baseUrl?: string;
+  includeDescriptions?: boolean;
+  includeLastmod?: boolean;
+  linkTarget?: "html" | "markdown" | "both";
+}): string;
+declare function readDocsSitemapManifestFromContentMap(contentMap?: Record<string, string> | null): DocsSitemapManifest | null;
+declare function resolveDocsSitemapPageLastmod(manifest: DocsSitemapManifest | null | undefined, url: string): string | undefined;
+declare function createDocsSitemapResponse({
+  request,
+  apiRoute,
+  sitemap,
+  entry,
+  siteTitle,
+  baseUrl,
+  pages,
+  manifest
+}: CreateDocsSitemapResponseOptions): Response | null;
+//#endregion
+//#region src/search.d.ts
+interface DocsAskAIContextResult extends DocsSearchResult {
+  title: string;
+  contextContent: string;
+}
+interface DocsAskAIContext {
+  context: string;
+  /** Structured production context blocks; avoids reparsing markdown horizontal rules. */
+  blocks: Array<{
+    text: string;
+    result: DocsAskAIContextResult;
+  }>;
+  results: DocsAskAIContextResult[];
+  searchResults: DocsSearchResult[];
+  packageHints: DocsAskAIPackageHints;
+}
+interface DocsAskAIPackageHints {
+  packages: string[];
+  imports: string[];
+  installCommands: string[];
+}
+declare function inferDocsAskAIPackageHints(content: string): DocsAskAIPackageHints;
+declare function formatDocsAskAIPackageHints(hints: DocsAskAIPackageHints, packageName?: string): string | undefined;
+declare function buildDocsSearchDocuments(pages: DocsSearchSourcePage[], chunking?: DocsSearchChunkingConfig, audience?: DocsContentAudience): DocsSearchDocument[];
+declare function createSimpleSearchAdapter(): DocsSearchAdapter;
+declare function createTypesenseSearchAdapter(config: TypesenseDocsSearchConfig): DocsSearchAdapter;
+declare function resolveSearchRequestConfig(search: boolean | DocsSearchConfig | undefined, requestUrl?: string): boolean | DocsSearchConfig | undefined;
+/**
+ * Resolve the public search audience without allowing malformed values to opt into agent content.
+ * Human search remains the default for omitted, legacy, and unknown query values.
+ */
+declare function resolveDocsSearchAudience(value: string | null | undefined): DocsContentAudience;
+declare function resolveAskAISearchRequestConfig(options: {
+  search: boolean | DocsSearchConfig | undefined;
+  useMcp?: boolean | DocsAskAIMcpConfig;
+  mcpEndpoint?: string;
+  mcpEnabled?: boolean;
+  mcpSearchEnabled?: boolean;
+  requestUrl?: string;
+}): boolean | DocsSearchConfig | undefined;
+declare function createMcpSearchAdapter(config: McpDocsSearchConfig): DocsSearchAdapter;
+declare function createAlgoliaSearchAdapter(config: AlgoliaDocsSearchConfig): DocsSearchAdapter;
+declare function performDocsSearch(options: {
+  pages: DocsSearchSourcePage[];
+  query: string;
+  search?: boolean | DocsSearchConfig; /** Selects which audience projection is searchable. Public site search defaults to human. */
+  audience?: DocsContentAudience;
+  locale?: string;
+  pathname?: string;
+  siteTitle?: string; /** Canonical docs URL used to distinguish same-site absolute hits from foreign MCP results. */
+  baseUrl?: string;
+  limit?: number;
+  /**
+   * Controls provider failures. Runtime search keeps the resilient `fallback` default;
+   * diagnostics can request `throw` so a broken configured provider cannot be scored as
+   * successful simple search.
+   */
+  failureMode?: "fallback" | "throw";
+  /**
+   * Whether non-simple provider hits are supplemented with exact/local simple results.
+   * Runtime search defaults to true; provider diagnostics can disable supplementation.
+   */
+  supplementExternalResults?: boolean; /** Fail closed on absolute provider hits when no canonical docs origin is available. */
+  strictExternalOrigins?: boolean; /** Optional cancellation signal forwarded to adapters and their managed requests. */
+  signal?: AbortSignal;
+}): Promise<DocsSearchResult[]>;
+declare function buildDocsAskAIContext(options: {
+  pages: DocsSearchSourcePage[];
+  query: string;
+  search?: boolean | DocsSearchConfig;
+  locale?: string;
+  pathname?: string;
+  siteTitle?: string;
+  baseUrl?: string;
+  limit?: number;
+  maxContextChars?: number;
+  maxResultChars?: number; /** See `performDocsSearch.failureMode`. Defaults to resilient runtime fallback. */
+  searchFailureMode?: "fallback" | "throw"; /** See `performDocsSearch.strictExternalOrigins`. */
+  strictExternalOrigins?: boolean; /** Optional cancellation signal forwarded to the configured search provider. */
+  signal?: AbortSignal;
+}): Promise<DocsAskAIContext>;
+declare function createCustomSearchAdapter(adapter: DocsSearchAdapter | DocsSearchAdapterFactory): CustomDocsSearchConfig;
+//#endregion
+export { resolveDocsAudienceExposure as $, resolveDocsSitemapPageLastmod as A, SerializedOpenDocsProvider as B, DocsSitemapResolvedConfig as C, renderDocsSitemapMarkdown as D, readDocsSitemapManifestFromContentMap as E, DEFAULT_OPEN_DOCS_TARGET as F, serializeDocsIcon as G, parsePromptStringArray as H, DEFAULT_PROMPT_PROVIDER_TEMPLATES as I, serializeOpenDocsProviders as J, serializeDocsIconRegistry as K, PromptAction as L, toDocsSitemapMarkdownUrl as M, DEFAULT_OPEN_DOCS_PROMPT as N, renderDocsSitemapXml as O, DEFAULT_OPEN_DOCS_PROVIDER_IDS as P, resolveDocsAgentMdxContent as Q, PromptProviderChoice as R, DocsSitemapPageInput as S, createDocsSitemapResponse as T, resolvePromptProviderChoices as U, normalizePromptProviderName as V, sanitizePromptText as W, DocsContentAudience as X, DocsAudienceMdxIssue as Y, findDocsAudienceMdxIssues as Z, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE as _, createMcpSearchAdapter as a, createDocsAgentTraceContext as at, DocsSitemapManifest as b, formatDocsAskAIPackageHints as c, emitDocsAnalyticsEvent as ct, resolveAskAISearchRequestConfig as d, resolveDocsAnalyticsConfig as dt, resolveDocsAudienceMdxContent as et, resolveDocsSearchAudience as f, resolveDocsObservabilityConfig as ft, DEFAULT_SITEMAP_MD_ROUTE as g, DEFAULT_SITEMAP_MD_DOCS_ROUTE as h, createCustomSearchAdapter as i, ResolvedDocsObservabilityConfig as it, resolveDocsSitemapRequest as j, resolveDocsSitemapConfig as k, inferDocsAskAIPackageHints as l, emitDocsObservabilityEvent as lt, DEFAULT_SITEMAP_MANIFEST_PATH as m, buildDocsSearchDocuments as n, DocsAgentTraceContext as nt, createSimpleSearchAdapter as o, createDocsAgentTraceId as ot, resolveSearchRequestConfig as p, serializeOpenDocsProvider as q, createAlgoliaSearchAdapter as r, ResolvedDocsAnalyticsConfig as rt, createTypesenseSearchAdapter as s, emitDocsAgentTraceEvent as st, buildDocsAskAIContext as t, DOCS_AGENT_TRACE_EVENT_TYPES as tt, performDocsSearch as u, getDocsRequestAnalyticsProperties as ut, DEFAULT_SITEMAP_XML_ROUTE as v, buildDocsSitemapManifest as w, DocsSitemapManifestPage as x, DocsSitemapFormat as y, SerializeOpenDocsProviderOptions as z };

package/dist/search-DSjCeOk7.mjs

@@ -0,0 +1,104 @@
+import "./agent-DKKptIgy.mjs";
+import "./standards-discovery-jkykaXq1.mjs";
+import { n as buildDocsSearchDocuments, r as createAlgoliaSearchAdapter, s as createTypesenseSearchAdapter } from "./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, c as loadProjectEnv, g as resolveDocsConfigPath, h as readTopLevelStringProperty } from "./config-Wcdj-D0a.mjs";
+import { readFileSync } from "node:fs";
+import pc from "picocolors";
+
+//#region src/cli/search.ts
+function getEnvValue(loadedEnv, key) {
+	return process.env[key] ?? loadedEnv[key];
+}
+function resolveSearchSyncProvider(options, loadedEnv) {
+	if (options.typesense && options.algolia) throw new Error("Use only one provider flag: --typesense or --algolia.");
+	if (options.typesense) return "typesense";
+	if (options.algolia) return "algolia";
+	if (options.provider === "typesense" || options.provider === "algolia") return options.provider;
+	if (options.provider) throw new Error(`Unsupported search provider: ${options.provider}.`);
+	if (options.baseUrl || getEnvValue(loadedEnv, "TYPESENSE_URL")) return "typesense";
+	if (options.appId || getEnvValue(loadedEnv, "ALGOLIA_APP_ID")) return "algolia";
+	throw new Error("Could not determine a search provider. Use --typesense, --algolia, or --provider <name>.");
+}
+function resolveTypesenseSyncConfig(options, loadedEnv) {
+	const baseUrl = options.baseUrl ?? getEnvValue(loadedEnv, "TYPESENSE_URL") ?? getEnvValue(loadedEnv, "TYPESENSE_BASE_URL");
+	const collection = options.collection ?? getEnvValue(loadedEnv, "TYPESENSE_COLLECTION") ?? "docs";
+	const apiKey = options.apiKey ?? getEnvValue(loadedEnv, "TYPESENSE_SEARCH_API_KEY") ?? getEnvValue(loadedEnv, "TYPESENSE_API_KEY");
+	const adminApiKey = options.adminApiKey ?? getEnvValue(loadedEnv, "TYPESENSE_ADMIN_API_KEY") ?? getEnvValue(loadedEnv, "TYPESENSE_API_KEY");
+	const mode = options.mode === "hybrid" ? "hybrid" : "keyword";
+	const ollamaModel = options.ollamaModel ?? getEnvValue(loadedEnv, "TYPESENSE_OLLAMA_MODEL");
+	const ollamaBaseUrl = options.ollamaBaseUrl ?? getEnvValue(loadedEnv, "TYPESENSE_OLLAMA_BASE_URL");
+	if (!baseUrl) throw new Error("Missing Typesense base URL. Set TYPESENSE_URL or pass --base-url.");
+	if (!apiKey) throw new Error("Missing Typesense API key. Set TYPESENSE_API_KEY or pass --api-key.");
+	if (!adminApiKey) throw new Error("Missing Typesense admin-capable key for sync. Set TYPESENSE_ADMIN_API_KEY or pass --admin-api-key.");
+	return {
+		provider: "typesense",
+		baseUrl,
+		collection,
+		apiKey,
+		adminApiKey,
+		mode,
+		...mode === "hybrid" ? ollamaModel ? { embeddings: {
+			provider: "ollama",
+			model: ollamaModel,
+			baseUrl: ollamaBaseUrl
+		} } : (() => {
+			throw new Error("Typesense hybrid sync needs an embeddings model. Set TYPESENSE_OLLAMA_MODEL or pass --ollama-model.");
+		})() : {}
+	};
+}
+function resolveAlgoliaSyncConfig(options, loadedEnv) {
+	const appId = options.appId ?? getEnvValue(loadedEnv, "ALGOLIA_APP_ID");
+	const indexName = options.indexName ?? getEnvValue(loadedEnv, "ALGOLIA_INDEX_NAME") ?? "docs";
+	const adminApiKey = options.adminApiKey ?? getEnvValue(loadedEnv, "ALGOLIA_ADMIN_API_KEY");
+	const searchApiKey = options.searchApiKey ?? getEnvValue(loadedEnv, "ALGOLIA_SEARCH_API_KEY") ?? adminApiKey;
+	if (!appId) throw new Error("Missing Algolia app id. Set ALGOLIA_APP_ID or pass --app-id.");
+	if (!adminApiKey) throw new Error("Missing Algolia admin API key for sync. Set ALGOLIA_ADMIN_API_KEY or pass --admin-api-key.");
+	if (!searchApiKey) throw new Error("Missing Algolia search API key. Set ALGOLIA_SEARCH_API_KEY or pass --search-api-key.");
+	return {
+		provider: "algolia",
+		appId,
+		indexName,
+		searchApiKey,
+		adminApiKey
+	};
+}
+async function syncSearch(options = {}) {
+	const rootDir = process.cwd();
+	const configContent = readFileSync(resolveDocsConfigPath(rootDir, options.configPath), "utf-8");
+	const loadedEnv = loadProjectEnv(rootDir);
+	const provider = resolveSearchSyncProvider(options, loadedEnv);
+	const entry = readTopLevelStringProperty(configContent, "entry") ?? "docs";
+	const contentDir = resolveDocsContentDir(rootDir, configContent, entry);
+	const source = createFilesystemDocsMcpSource({
+		rootDir,
+		entry,
+		contentDir,
+		siteTitle: "Documentation"
+	});
+	const pages = await source.getPages();
+	const documents = buildDocsSearchDocuments(pages);
+	const context = {
+		pages,
+		documents,
+		siteTitle: source.siteTitle
+	};
+	if (documents.length === 0) throw new Error(`No docs content was found under ${contentDir}.`);
+	if (provider === "typesense") {
+		const config = resolveTypesenseSyncConfig(options, loadedEnv);
+		await createTypesenseSearchAdapter(config).index?.(context);
+		console.log(pc.green(`Synced ${documents.length} docs search documents to Typesense collection "${config.collection}".`));
+		return;
+	}
+	const config = resolveAlgoliaSyncConfig(options, loadedEnv);
+	await createAlgoliaSearchAdapter(config).index?.(context);
+	console.log(pc.green(`Synced ${documents.length} docs search documents to Algolia index "${config.indexName}".`));
+}
+
+//#endregion
+export { syncSearch };