@farming-labs/docs 0.1.123 → 0.1.125

package/dist/{agent-cmkIPvWo.mjs → agent-CBhuGaVu.mjs}

@@ -1,9 +1,9 @@
-import "./reading-time-Io7iRZ7S.mjs";
+import "./reading-time-HpTq-0VB.mjs";
 import "./search-BL7o2rXk.mjs";
 import "./agent-BS39vnhS.mjs";
 import "./robots-B2BfoyVM.mjs";
 import "./sitemap-server-BZHoJHqC.mjs";
-import "./config-BHRL4R2v.mjs";
-import { a as readPageTokenBudget, i as printAgentCompactHelp, n as inspectAgentCompactionState, o as scanDocsPageTargets, r as parseAgentCompactArgs, t as compactAgentDocs } from "./agents-B3kj54S3.mjs";
+import "./config-B8wA38OC.mjs";
+import { a as readPageTokenBudget, i as printAgentCompactHelp, n as inspectAgentCompactionState, o as scanDocsPageTargets, r as parseAgentCompactArgs, t as compactAgentDocs } from "./codeblocks-B4QzFqNC.mjs";
 
 export { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp };

package/dist/agents-BPX4YRPs.mjs

@@ -0,0 +1,209 @@
+import "./search-BL7o2rXk.mjs";
+import { K as resolveDocsAgentFeedbackConfig, V as renderDocsAgentsDocument, a as DEFAULT_AGENT_MD_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, y as DEFAULT_OPENAPI_SCHEMA_ROUTE } from "./agent-BS39vnhS.mjs";
+import { S as resolveApiReferenceConfig } from "./sitemap-server-BZHoJHqC.mjs";
+import { resolveDocsMcpConfig } from "./mcp.mjs";
+import "./server.mjs";
+import { c as readNavTitle, d as readTopLevelStringProperty, f as resolveDocsConfigPath, i as loadDocsConfigModule, o as readBooleanProperty, t as extractNestedObjectLiteral, u as readStringProperty } from "./config-B8wA38OC.mjs";
+import { t as detectFramework } from "./utils-x5EtYWjC.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 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,
+		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 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,
+		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/cli/index.mjs

@@ -77,16 +77,16 @@ async function main() {
 		searchApiKey: typeof flags["search-api-key"] === "string" ? flags["search-api-key"] : void 0
 	};
 	if (!parsedCommand.command || parsedCommand.command === "init") {
-		const { init } = await import("../init-_HAuo5Dv.mjs");
+		const { init } = await import("../init-DzQWiVN1.mjs");
 		await init(initOptions);
 	} else if (parsedCommand.command === "dev") {
-		const { dev } = await import("../dev-C03tUSTz.mjs");
+		const { dev } = await import("../dev-1VFeAWUi.mjs");
 		await dev(devOptions);
 	} else if (parsedCommand.command === "mcp") {
-		const { runMcp } = await import("../mcp-veym29Yc.mjs");
+		const { runMcp } = await import("../mcp-BvERlrP_.mjs");
 		await runMcp(mcpOptions);
 	} else if (parsedCommand.command === "agent" && subcommand === "compact") {
-		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-cmkIPvWo.mjs");
+		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-CBhuGaVu.mjs");
 		const agentCompactOptions = parseAgentCompactArgs(args.slice(2));
 		if (agentCompactOptions.help) {
 			printAgentCompactHelp();
@@ -96,11 +96,11 @@ async function main() {
 	} else if (parsedCommand.command === "agent") {
 		console.error(pc.red(`Unknown agent subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printAgentCompactHelp } = await import("../agent-cmkIPvWo.mjs");
+		const { printAgentCompactHelp } = await import("../agent-CBhuGaVu.mjs");
 		printAgentCompactHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "agents" && subcommand === "generate") {
-		const { generateAgents, parseAgentsGenerateArgs, printAgentsGenerateHelp } = await import("../agents-B3kj54S3.mjs");
+		const { generateAgents, parseAgentsGenerateArgs, printAgentsGenerateHelp } = await import("../agents-BPX4YRPs.mjs");
 		const agentsOptions = parseAgentsGenerateArgs(args.slice(2));
 		if (agentsOptions.help) {
 			printAgentsGenerateHelp();
@@ -110,11 +110,11 @@ async function main() {
 	} else if (parsedCommand.command === "agents") {
 		console.error(pc.red(`Unknown agents subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printAgentsGenerateHelp } = await import("../agents-B3kj54S3.mjs");
+		const { printAgentsGenerateHelp } = await import("../agents-BPX4YRPs.mjs");
 		printAgentsGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "doctor") {
-		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-C9wz-4CE.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-lV9lhqGA.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();
@@ -122,15 +122,29 @@ async function main() {
 		}
 		await runDoctor(doctorOptions);
 	} else if (parsedCommand.command === "review") {
-		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-DEG_UnxV.mjs");
+		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-ClNDYRnn.mjs");
 		const reviewOptions = parseReviewArgs(args.slice(1));
 		if (reviewOptions.help) {
 			printReviewHelp();
 			return;
 		}
 		await runReview(reviewOptions);
+	} else if ((parsedCommand.command === "codeblocks" || parsedCommand.command === "code-blocks") && subcommand === "validate") {
+		const { parseCodeBlocksValidateArgs, printCodeBlocksValidateHelp, runCodeBlocksValidate } = await import("../codeblocks-B4QzFqNC.mjs");
+		const codeBlocksOptions = parseCodeBlocksValidateArgs(args.slice(2));
+		if (codeBlocksOptions.help) {
+			printCodeBlocksValidateHelp();
+			return;
+		}
+		await runCodeBlocksValidate(codeBlocksOptions);
+	} else if (parsedCommand.command === "codeblocks" || parsedCommand.command === "code-blocks") {
+		console.error(pc.red(`Unknown codeblocks subcommand: ${subcommand ?? "(missing)"}`));
+		console.error();
+		const { printCodeBlocksValidateHelp } = await import("../codeblocks-B4QzFqNC.mjs");
+		printCodeBlocksValidateHelp();
+		process.exit(1);
 	} else if (parsedCommand.command === "search" && subcommand === "sync") {
-		const { syncSearch } = await import("../search-HqdPzNb3.mjs");
+		const { syncSearch } = await import("../search-BjyDm30M.mjs");
 		await syncSearch(searchSyncOptions);
 	} else if (parsedCommand.command === "search") {
 		console.error(pc.red(`Unknown search subcommand: ${subcommand ?? "(missing)"}`));
@@ -138,7 +152,7 @@ async function main() {
 		printHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "sitemap" && subcommand === "generate") {
-		const { generateSitemap, parseSitemapGenerateArgs, printSitemapGenerateHelp } = await import("../sitemap-wtr3w_D2.mjs");
+		const { generateSitemap, parseSitemapGenerateArgs, printSitemapGenerateHelp } = await import("../sitemap-BdSdcAmS.mjs");
 		const sitemapOptions = parseSitemapGenerateArgs(args.slice(2));
 		if (sitemapOptions.help) {
 			printSitemapGenerateHelp();
@@ -148,11 +162,11 @@ async function main() {
 	} else if (parsedCommand.command === "sitemap") {
 		console.error(pc.red(`Unknown sitemap subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printSitemapGenerateHelp } = await import("../sitemap-wtr3w_D2.mjs");
+		const { printSitemapGenerateHelp } = await import("../sitemap-BdSdcAmS.mjs");
 		printSitemapGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "robots" && subcommand === "generate") {
-		const { generateRobots, parseRobotsGenerateArgs, printRobotsGenerateHelp } = await import("../robots-BkRZN-56.mjs");
+		const { generateRobots, parseRobotsGenerateArgs, printRobotsGenerateHelp } = await import("../robots-CNLiZCay.mjs");
 		const robotsOptions = parseRobotsGenerateArgs(args.slice(2));
 		if (robotsOptions.help) {
 			printRobotsGenerateHelp();
@@ -162,11 +176,11 @@ async function main() {
 	} else if (parsedCommand.command === "robots") {
 		console.error(pc.red(`Unknown robots subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printRobotsGenerateHelp } = await import("../robots-BkRZN-56.mjs");
+		const { printRobotsGenerateHelp } = await import("../robots-CNLiZCay.mjs");
 		printRobotsGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "downgrade") {
-		const { downgrade } = await import("../downgrade-Bv7E5LV2.mjs");
+		const { downgrade } = await import("../downgrade-BGANzvQb.mjs");
 		const framework = (typeof flags.framework === "string" ? flags.framework : void 0) ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0);
 		const hasVersionFlag = args.includes("--version") || args.some((arg) => arg.startsWith("--version="));
 		await downgrade({
@@ -174,7 +188,7 @@ async function main() {
 			version: typeof flags.version === "string" ? flags.version : hasVersionFlag ? "" : void 0
 		});
 	} else if (parsedCommand.command === "upgrade") {
-		const { upgrade } = await import("../upgrade-DrOWQIKI.mjs");
+		const { upgrade } = await import("../upgrade-C7DvvfTR.mjs");
 		const framework = (typeof flags.framework === "string" ? flags.framework : void 0) ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0);
 		const hasVersionFlag = args.includes("--version") || args.some((arg) => arg.startsWith("--version="));
 		const version = typeof flags.version === "string" ? flags.version : hasVersionFlag ? "" : void 0;
@@ -206,6 +220,7 @@ ${pc.dim("Commands:")}
   ${pc.cyan("agents")}   AGENTS.md utilities (${pc.dim("generate")} for static agent instructions)
   ${pc.cyan("doctor")}   Inspect and score agent or reader-facing docs quality
   ${pc.cyan("review")}   Review changed docs files and wire Docs Review CI
+  ${pc.cyan("codeblocks")} Validate fenced MDX code blocks (${pc.dim("validate")})
   ${pc.cyan("mcp")}      Run the built-in docs MCP server over stdio
   ${pc.cyan("robots")}   Robots.txt utilities (${pc.dim("generate")} for agent access policy)
   ${pc.cyan("search")}   Search utilities (${pc.dim("sync")} for external indexes)