@farming-labs/docs 0.2.62 → 0.2.63

package/dist/agents-XWZBub6f.mjs

@@ -0,0 +1,221 @@
+import { $ as renderDocsAgentsDocument, a as DEFAULT_AGENT_MD_ROUTE, at as resolveDocsAgentFeedbackConfig, b as DEFAULT_OPENAPI_SCHEMA_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE } from "./agent-DKKptIgy.mjs";
+import "./standards-discovery-jkykaXq1.mjs";
+import "./search-B6V6qtiI.mjs";
+import { S as resolveApiReferenceConfig } from "./sitemap-server-C_6Wes83.mjs";
+import "./agent-evals-B7MIxuEX.mjs";
+import { resolveDocsMcpConfig } from "./mcp.mjs";
+import "./code-blocks-DnNVNK2M.mjs";
+import "./agent-skills-server-DraIb6FV.mjs";
+import "./server.mjs";
+import { 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, writeFileSync } from "node:fs";
+import path from "node:path";
+import pc from "picocolors";
+
+//#region src/cli/agents.ts
+const AGENTS_GENERATED_MARKER = "<!-- Generated by @farming-labs/docs agents generate. -->";
+function parseInlineFlag(arg) {
+	const [rawKey, value] = arg.slice(2).split("=", 2);
+	return {
+		key: rawKey.trim(),
+		value
+	};
+}
+function parseAgentsGenerateArgs(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 === "--force") {
+			parsed.force = 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;
+		}
+		if (arg.startsWith("--path=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --path.");
+			parsed.path = value;
+			continue;
+		}
+		if (arg === "--path") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --path.");
+			parsed.path = value;
+			index += 1;
+			continue;
+		}
+		if (!arg.startsWith("--") && !parsed.path) {
+			parsed.path = arg;
+			continue;
+		}
+		throw new Error(`Unknown agents generate flag: ${arg}.`);
+	}
+	return parsed;
+}
+function readTopLevelBooleanProperty(content, key) {
+	const match = content.match(new RegExp(`\\b${key}\\b\\s*:\\s*(true|false)`));
+	return match ? match[1] === "true" : void 0;
+}
+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 readSitemapBaseUrlFromConfig(content, config) {
+	if (config?.sitemap && typeof config.sitemap === "object") return config.sitemap.baseUrl;
+	const block = extractNestedObjectLiteral(content, ["sitemap"]);
+	return block ? readStringProperty(block, "baseUrl") : void 0;
+}
+function readCloudApiRouteFromConfig(content, config) {
+	if (typeof config?.cloud?.apiRoute === "string") return config.cloud.apiRoute;
+	const block = extractNestedObjectLiteral(content, ["cloud"]);
+	return block ? readStringProperty(block, "apiRoute") : void 0;
+}
+function readRobotsConfigFromStatic(content) {
+	const topLevelBoolean = readTopLevelBooleanProperty(content, "robots");
+	if (typeof topLevelBoolean === "boolean") return topLevelBoolean;
+	const block = extractNestedObjectLiteral(content, ["robots"]);
+	if (!block) return void 0;
+	return { enabled: readBooleanProperty(block, "enabled") ?? true };
+}
+function resolvePublicDir(rootDir) {
+	if (detectFramework(rootDir) === "sveltekit") return path.join(rootDir, "static");
+	return path.join(rootDir, "public");
+}
+function resolveAgentsPath(rootDir, options) {
+	if (options.path) return path.isAbsolute(options.path) ? options.path : path.resolve(rootDir, options.path);
+	return path.join(rootDir, "AGENTS.md");
+}
+function publicFilePath(rootDir, route) {
+	return path.join(resolvePublicDir(rootDir), route.replace(/^\/+/, ""));
+}
+function normalizeGeneratedContent(content) {
+	return `${AGENTS_GENERATED_MARKER}\n${content.trimEnd()}\n`;
+}
+function normalizeCustomContent(content) {
+	return content.endsWith("\n") ? content : `${content}\n`;
+}
+function isManagedAgentsFile(content) {
+	return content.includes(AGENTS_GENERATED_MARKER);
+}
+function writeIfNeeded(filePath, content, options) {
+	const current = existsSync(filePath) ? readFileSync(filePath, "utf-8") : void 0;
+	if (current === content) return "current";
+	if (current !== void 0 && !options.force && !isManagedAgentsFile(current)) return "kept";
+	if (options.check) return "changed";
+	mkdirSync(path.dirname(filePath), { recursive: true });
+	writeFileSync(filePath, content, "utf-8");
+	return "changed";
+}
+function resolveOpenApiDiscovery(config) {
+	const apiReference = resolveApiReferenceConfig(config?.apiReference);
+	if (!apiReference.enabled) return { enabled: false };
+	return {
+		enabled: true,
+		url: DEFAULT_OPENAPI_SCHEMA_ROUTE,
+		urlSource: "default",
+		source: apiReference.specUrl ? "configured" : "generated",
+		specUrl: apiReference.specUrl,
+		apiReferencePath: `/${apiReference.path}`
+	};
+}
+async function generateAgents(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 = config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
+	const siteTitle = typeof config?.nav?.title === "string" ? config.nav.title : readNavTitle(configContent) ?? "Documentation";
+	const siteDescription = typeof config?.metadata?.description === "string" ? config.metadata.description : void 0;
+	const baseUrl = readLlmsBaseUrlFromConfig(configContent, config) ?? readSitemapBaseUrlFromConfig(configContent, config);
+	const apiRoute = readCloudApiRouteFromConfig(configContent, config);
+	const llmsTxt = config?.llmsTxt;
+	const llmsEnabled = llmsTxt === false ? false : typeof llmsTxt === "object" ? llmsTxt.enabled ?? true : true;
+	const llmsConfig = typeof llmsTxt === "object" ? llmsTxt : void 0;
+	const robotsInput = config?.robots ?? readRobotsConfigFromStatic(configContent) ?? true;
+	const rootAgentsPath = resolveAgentsPath(rootDir, options);
+	const generatedContent = normalizeGeneratedContent(renderDocsAgentsDocument({
+		origin: baseUrl ?? "http://localhost",
+		entry,
+		apiRoute,
+		search: config?.search,
+		mcp: resolveDocsMcpConfig(config?.mcp),
+		feedback: resolveDocsAgentFeedbackConfig(config?.feedback),
+		llms: {
+			enabled: llmsEnabled,
+			baseUrl,
+			siteTitle,
+			siteDescription,
+			maxChars: llmsConfig?.maxChars,
+			sections: llmsConfig?.sections
+		},
+		sitemap: config?.sitemap,
+		robots: robotsInput,
+		openapi: resolveOpenApiDiscovery(config),
+		markdown: { acceptHeader: false }
+	}));
+	const existingRoot = existsSync(rootAgentsPath) ? readFileSync(rootAgentsPath, "utf-8") : null;
+	const sourceContent = existingRoot !== null && !options.force && !isManagedAgentsFile(existingRoot) ? normalizeCustomContent(existingRoot) : generatedContent;
+	const writes = [];
+	const kept = [];
+	const rootStatus = writeIfNeeded(rootAgentsPath, sourceContent, options);
+	if (rootStatus === "changed") writes.push(rootAgentsPath);
+	if (rootStatus === "kept") kept.push(rootAgentsPath);
+	for (const route of [
+		DEFAULT_AGENTS_MD_ROUTE,
+		DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE,
+		DEFAULT_AGENT_MD_ROUTE,
+		DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE
+	]) {
+		const filePath = publicFilePath(rootDir, route);
+		const status = writeIfNeeded(filePath, sourceContent, options);
+		if (status === "changed") writes.push(filePath);
+		if (status === "kept") kept.push(filePath);
+	}
+	if (options.check && writes.length > 0) throw new Error("AGENTS.md output is stale. Run `docs agents generate` to update it.");
+	const relativeRoot = path.relative(rootDir, rootAgentsPath).replace(/\\/g, "/");
+	console.log(writes.length > 0 ? pc.green(`Generated agent instructions at ${relativeRoot}.`) : pc.green(`Agent instructions are current at ${relativeRoot}.`));
+	for (const filePath of writes) {
+		if (filePath === rootAgentsPath) continue;
+		console.log(pc.dim(path.relative(rootDir, filePath).replace(/\\/g, "/")));
+	}
+	for (const filePath of kept) console.log(pc.yellow(`Kept user-owned ${path.relative(rootDir, filePath).replace(/\\/g, "/")}.`));
+}
+function printAgentsGenerateHelp() {
+	console.log(`
+${pc.bold("docs agents generate")} — Generate AGENTS.md instructions for coding agents.
+
+${pc.dim("Usage:")}
+  pnpm exec docs ${pc.cyan("agents generate")} ${pc.dim("[path]")}
+
+${pc.dim("Options:")}
+  ${pc.cyan("--path <path>")}       Write the root instructions file; defaults to ${pc.dim("AGENTS.md")}
+  ${pc.cyan("--force")}             Replace existing AGENTS.md/static files
+  ${pc.cyan("--check")}             Fail if generated output would change
+  ${pc.cyan("--config <path>")}     Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
+  ${pc.cyan("-h, --help")}          Show this help message
+`);
+}
+
+//#endregion
+export { generateAgents, parseAgentsGenerateArgs, printAgentsGenerateHelp };

package/dist/analytics-Bx44lg6d.mjs

@@ -0,0 +1,177 @@
+import { n as sendDocsCloudAnalyticsEvent, t as resolveDocsCloudAnalyticsOptions } from "./cloud-analytics-CSyFE6SS.mjs";
+
+//#region src/analytics.ts
+const ANALYTICS_LOG_PREFIX = "[@farming-labs/docs:analytics]";
+const OBSERVABILITY_LOG_PREFIX = "[@farming-labs/docs:observability]";
+const DOCS_AGENT_TRACE_EVENT_TYPES = [
+	"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"
+];
+function composeAnalyticsHandlers(userOnEvent, cloudOnEvent) {
+	if (typeof userOnEvent !== "function" && !cloudOnEvent) return;
+	return async (event) => {
+		let userError;
+		if (typeof userOnEvent === "function") try {
+			await userOnEvent(event);
+		} catch (error) {
+			userError = error;
+		}
+		if (cloudOnEvent) try {
+			await cloudOnEvent(event);
+		} catch {}
+		if (typeof userError !== "undefined") throw userError;
+	};
+}
+function resolveConsoleLevel(value, hasEventHandler) {
+	if (value === false) return false;
+	if (value === true) return "info";
+	if (value === "log" || value === "info" || value === "debug") return value;
+	return hasEventHandler ? false : "info";
+}
+function createDocsAgentTraceId(prefix = "trace") {
+	return `${prefix.replace(/[^a-zA-Z0-9_-]/g, "_") || "trace"}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function createDocsAgentTraceContext(name = "agent.run") {
+	return {
+		traceId: createDocsAgentTraceId("run"),
+		name,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		startedMs: Date.now()
+	};
+}
+function getDocsRequestAnalyticsProperties(request) {
+	const userAgent = request.headers.get("user-agent")?.trim();
+	return userAgent ? { userAgent } : {};
+}
+function resolveDocsAnalyticsConfig(analytics) {
+	if (analytics === false) return {
+		enabled: false,
+		console: false,
+		includeInputs: false
+	};
+	const cloudOptions = resolveDocsCloudAnalyticsOptions(analytics);
+	const cloudOnEvent = cloudOptions ? async (event) => {
+		await sendDocsCloudAnalyticsEvent(cloudOptions, event);
+	} : void 0;
+	if (!analytics) {
+		if (!cloudOnEvent) return {
+			enabled: false,
+			console: false,
+			includeInputs: false
+		};
+		return {
+			enabled: true,
+			console: false,
+			includeInputs: false,
+			onEvent: cloudOnEvent
+		};
+	}
+	if (analytics === true) return {
+		enabled: true,
+		console: "info",
+		includeInputs: false,
+		onEvent: cloudOnEvent
+	};
+	const userOnEvent = analytics.onEvent;
+	const hasEventHandler = typeof userOnEvent === "function" || Boolean(cloudOnEvent);
+	const onEvent = composeAnalyticsHandlers(userOnEvent, cloudOnEvent);
+	return {
+		enabled: analytics.enabled !== false,
+		console: resolveConsoleLevel(analytics.console, hasEventHandler),
+		includeInputs: analytics.includeInputs === true,
+		onEvent
+	};
+}
+function resolveDocsObservabilityConfig(observability) {
+	if (!observability) return {
+		enabled: false,
+		console: false,
+		includeInputs: false
+	};
+	if (observability === true) return {
+		enabled: true,
+		console: "info",
+		includeInputs: false
+	};
+	const hasEventHandler = typeof observability.onEvent === "function";
+	return {
+		enabled: observability.enabled !== false,
+		console: resolveConsoleLevel(observability.console, hasEventHandler),
+		includeInputs: observability.includeInputs === true,
+		onEvent: observability.onEvent
+	};
+}
+function normalizeAnalyticsEvent(event, config) {
+	const normalized = {
+		...event,
+		source: event.source ?? "server",
+		timestamp: event.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+	};
+	if (!config.includeInputs && normalized.input) delete normalized.input;
+	return normalized;
+}
+function normalizeObservabilityEvent(event, config) {
+	const normalized = {
+		...event,
+		source: event.source ?? "server",
+		timestamp: event.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+	};
+	if (!config.includeInputs && normalized.input) delete normalized.input;
+	return normalized;
+}
+async function emitDocsAnalyticsEvent(analytics, event) {
+	const resolved = resolveDocsAnalyticsConfig(analytics);
+	if (!resolved.enabled) return;
+	const normalized = normalizeAnalyticsEvent(event, resolved);
+	if (resolved.console) (console[resolved.console] ?? console.info).call(console, ANALYTICS_LOG_PREFIX, normalized);
+	if (!resolved.onEvent) return;
+	try {
+		await resolved.onEvent(normalized);
+	} catch (error) {
+		if (resolved.console !== false) console.warn(`${ANALYTICS_LOG_PREFIX} onEvent failed`, error);
+	}
+}
+async function emitDocsObservabilityEvent(observability, event) {
+	const resolved = resolveDocsObservabilityConfig(observability);
+	if (!resolved.enabled) return;
+	const normalized = normalizeObservabilityEvent(event, resolved);
+	if (resolved.console) (console[resolved.console] ?? console.info).call(console, OBSERVABILITY_LOG_PREFIX, normalized);
+	if (!resolved.onEvent) return;
+	try {
+		await resolved.onEvent(normalized);
+	} catch (error) {
+		if (resolved.console !== false) console.warn(`${OBSERVABILITY_LOG_PREFIX} onEvent failed`, error);
+	}
+}
+async function emitDocsAgentTraceEvent(observability, event) {
+	const timestamp = event.timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
+	await emitDocsObservabilityEvent(observability, {
+		...event,
+		timestamp,
+		source: event.source ?? "server",
+		traceId: event.traceId ?? createDocsAgentTraceId("run"),
+		spanId: event.spanId ?? createDocsAgentTraceId("span"),
+		startedAt: event.startedAt ?? timestamp,
+		status: event.status ?? "success"
+	});
+}
+
+//#endregion
+export { emitDocsAnalyticsEvent as a, resolveDocsAnalyticsConfig as c, emitDocsAgentTraceEvent as i, resolveDocsObservabilityConfig as l, createDocsAgentTraceContext as n, emitDocsObservabilityEvent as o, createDocsAgentTraceId as r, getDocsRequestAnalyticsProperties as s, DOCS_AGENT_TRACE_EVENT_TYPES as t };

package/dist/cli/index.d.mts

@@ -0,0 +1,15 @@
+//#region src/cli/errors.d.ts
+declare function formatCliError(error: unknown): string;
+//#endregion
+//#region src/cli/index.d.ts
+declare const UPGRADE_TAGS: readonly ["latest", "beta"];
+type UpgradeTag = (typeof UPGRADE_TAGS)[number];
+/** Normalize command aliases like `upgrade@beta` into the base command + dist-tag. */
+declare function parseCommandAlias(rawCommand?: string): {
+  command?: string;
+  tag?: UpgradeTag;
+};
+/** Parse flags like --template next, --name my-docs, --theme concrete, --entry docs, --framework astro (exported for tests). */
+declare function parseFlags(argv: string[]): Record<string, string | boolean | undefined>;
+//#endregion
+export { formatCliError, parseCommandAlias, parseFlags };