@farming-labs/docs 0.2.102 → 0.2.104

package/dist/{agents-CtqIUW5I.mjs → agents-D3SLnQet.mjs}

@@ -1,15 +1,16 @@
-import { a as DEFAULT_AGENT_MD_ROUTE, lt as resolveDocsAgentFeedbackConfig, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, rt as renderDocsAgentsDocument, t as DEFAULT_AGENTS_MD_ROUTE } from "./agent-CFqECAG0.mjs";
+import { a as DEFAULT_AGENT_MD_ROUTE, lt as resolveDocsAgentFeedbackConfig, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, rt as renderDocsAgentsDocument, t as DEFAULT_AGENTS_MD_ROUTE } from "./agent-PSrgiJD8.mjs";
 import "./markdown-sections-7OoA7ylx.mjs";
 import "./standards-discovery-Ckx0tN7B.mjs";
-import "./content-change-hydration-BsbBXAUi.mjs";
-import { C as resolveApiReferenceOpenApiDiscovery } from "./sitemap-server-B0SiREN0.mjs";
+import "./openapi-mcp-B7u7Y0gB.mjs";
+import { C as resolveApiReferenceOpenApiDiscovery } from "./sitemap-server-C2TauhKa.mjs";
 import "./agent-skills-server-DFqQyO_V.mjs";
-import "./agent-evals-GpcaCbRb.mjs";
+import "./agent-evals-U9d_db2u.mjs";
 import { resolveDocsMcpConfig } from "./mcp.mjs";
-import "./code-blocks-Bel6vDqI.mjs";
+import "./authoring-mcp-BCM5CJbJ.mjs";
+import "./code-blocks-c3nIrWOM.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-BaTmjDqD.mjs";
-import { t as detectFramework } from "./utils-DOMeZW9V.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-BhF6J2N4.mjs";
+import { t as detectFramework } from "./utils-DcCUwxqS.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/{analytics-C75BnTEW.d.mts → analytics-B-jz7re8.d.mts}

@@ -1,4 +1,4 @@
-import { dn as DocsObservabilityEvent, fn as DocsObservabilityEventInput, ft as DocsAnalyticsConfig, lt as DocsAgentTraceEventInput, mt as DocsAnalyticsEventInput, pt as DocsAnalyticsEvent, un as DocsObservabilityConfig } from "./types-DLLefoU5.mjs";
+import { dn as DocsObservabilityEvent, fn as DocsObservabilityEventInput, ft as DocsAnalyticsConfig, lt as DocsAgentTraceEventInput, mt as DocsAnalyticsEventInput, pt as DocsAnalyticsEvent, un as DocsObservabilityConfig } from "./types-BthCiAD9.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"];

package/dist/authoring-BsWXMH43.mjs

@@ -0,0 +1,41 @@
+import "./agent-PSrgiJD8.mjs";
+import "./markdown-sections-7OoA7ylx.mjs";
+import "./standards-discovery-Ckx0tN7B.mjs";
+import "./openapi-mcp-B7u7Y0gB.mjs";
+import { r as runDocsAuthoringMcpStdio } from "./authoring-mcp-BCM5CJbJ.mjs";
+import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, o as loadDocsConfigModuleResult, p as readStringProperty } from "./config-BhF6J2N4.mjs";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+//#region src/cli/authoring.ts
+async function runAuthoringMcp(options = {}) {
+	const rootDir = process.cwd();
+	const content = readFileSync(resolveDocsConfigPath(rootDir, options.configPath), "utf8");
+	const configLoad = await loadDocsConfigModuleResult(rootDir, options.configPath);
+	const config = configLoad.status === "evaluated" ? configLoad.config : void 0;
+	const entry = config?.entry ?? readStringProperty(content, "entry") ?? "docs";
+	const contentDir = config?.contentDir ?? resolveDocsContentDir(rootDir, content, entry);
+	const navTitle = typeof config?.nav?.title === "string" ? config.nav.title : readNavTitle(content);
+	const cliPath = process.argv[1];
+	if (!cliPath) throw new Error("Could not resolve the docs CLI executable for doctor checks.");
+	await runDocsAuthoringMcpStdio({
+		rootDir,
+		entry,
+		contentDir,
+		name: `${navTitle ?? "Documentation"} authoring`,
+		branchPrefix: options.branchPrefix,
+		baseBranch: options.baseBranch,
+		allowPublish: options.allowPublish,
+		doctorCommand: [
+			process.execPath,
+			path.resolve(cliPath),
+			"doctor",
+			"--agent",
+			"--json",
+			...options.configPath ? ["--config", options.configPath] : []
+		]
+	});
+}
+
+//#endregion
+export { runAuthoringMcp };

package/dist/authoring-mcp-BCM5CJbJ.mjs

@@ -0,0 +1,380 @@
+import { at as renderDocsMarkdownDocument } from "./agent-PSrgiJD8.mjs";
+import { createFilesystemDocsMcpSource } from "./mcp.mjs";
+import { n as analyzeDocsAgentFeedback, r as readDocsAgentFeedbackFile } from "./agent-feedback-loop-CGrc-gDW.mjs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { McpServer } from "@modelcontextprotocol/server";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+
+//#region src/authoring-mcp.ts
+const execFileAsync = promisify(execFile);
+const AUTHORING_MAX_COMMAND_OUTPUT_BYTES = 1e6;
+const DEFAULT_MAX_AUTHORING_FILE_BYTES = 1e6;
+const DOCS_AUTHORING_EXTENSIONS = new Set([
+	".md",
+	".mdx",
+	".svx"
+]);
+function structuredResult(value) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(value, null, 2)
+		}],
+		structuredContent: value
+	};
+}
+function isContained(parent, candidate) {
+	const relative = path.relative(parent, candidate);
+	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function projectPath(rootDir, absolutePath) {
+	return path.relative(rootDir, absolutePath).replace(/\\/g, "/");
+}
+function resolveContentRoot(options) {
+	return path.resolve(options.rootDir, options.contentDir ?? options.entry ?? "docs");
+}
+function assertPathHasNoSymlinks(basePath, candidate) {
+	const relative = path.relative(basePath, candidate);
+	let current = basePath;
+	for (const segment of relative.split(path.sep).filter(Boolean)) {
+		current = path.join(current, segment);
+		if (existsSync(current) && lstatSync(current).isSymbolicLink()) throw new Error(`Authoring paths cannot traverse symbolic links: ${current}`);
+	}
+}
+function resolveDocsFile(options, value) {
+	if (!value.trim() || path.isAbsolute(value) || value.includes("\0")) throw new Error("Authoring paths must be non-empty project-relative paths.");
+	const rootDir = path.resolve(options.rootDir);
+	const contentRoot = resolveContentRoot(options);
+	const candidate = path.resolve(rootDir, value);
+	if (!isContained(contentRoot, candidate)) throw new Error(`Authoring is restricted to ${projectPath(rootDir, contentRoot)}/.`);
+	if (existsSync(contentRoot) && lstatSync(contentRoot).isSymbolicLink()) throw new Error("The authoring content directory cannot be a symbolic link.");
+	assertPathHasNoSymlinks(contentRoot, candidate);
+	if (!DOCS_AUTHORING_EXTENSIONS.has(path.extname(candidate).toLowerCase())) throw new Error("Authoring only supports .md, .mdx, and .svx documentation files.");
+	return candidate;
+}
+function resolveProjectInputFile(rootDir, value) {
+	if (!value.trim() || path.isAbsolute(value) || value.includes("\0")) throw new Error("Input paths must be non-empty project-relative paths.");
+	const resolvedRoot = path.resolve(rootDir);
+	const candidate = path.resolve(resolvedRoot, value);
+	if (!isContained(resolvedRoot, candidate)) throw new Error("Input files must stay inside the project root.");
+	assertPathHasNoSymlinks(resolvedRoot, candidate);
+	if (existsSync(candidate) && !isContained(realpathSync(resolvedRoot), realpathSync(candidate))) throw new Error("Input files must stay inside the project root.");
+	return candidate;
+}
+function sha256(value) {
+	return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function readDocsAuthoringFile(options, filePath) {
+	const absolutePath = resolveDocsFile(options, filePath);
+	if (!existsSync(absolutePath) || !statSync(absolutePath).isFile()) throw new Error(`Documentation file does not exist: ${filePath}`);
+	const content = readFileSync(absolutePath, "utf8");
+	return {
+		path: projectPath(path.resolve(options.rootDir), absolutePath),
+		sha256: sha256(content),
+		bytes: Buffer.byteLength(content, "utf8"),
+		content
+	};
+}
+function writeDocsAuthoringFile(options, input) {
+	const absolutePath = resolveDocsFile(options, input.path);
+	const maxFileBytes = Math.max(1, options.maxFileBytes ?? DEFAULT_MAX_AUTHORING_FILE_BYTES);
+	if (Buffer.byteLength(input.content, "utf8") > maxFileBytes) throw new Error(`Authoring write exceeds the ${maxFileBytes}-byte file limit.`);
+	if (existsSync(absolutePath)) {
+		const current = readFileSync(absolutePath, "utf8");
+		if (!input.expectedSha256) throw new Error("expectedSha256 is required when overwriting an existing documentation file.");
+		if (sha256(current) !== input.expectedSha256) throw new Error("Documentation changed since it was read; read it again before overwriting.");
+	} else if (input.expectedSha256) throw new Error("expectedSha256 was provided, but the documentation file does not exist.");
+	mkdirSync(path.dirname(absolutePath), { recursive: true });
+	const temporaryPath = path.join(path.dirname(absolutePath), `.${path.basename(absolutePath)}.${randomUUID()}.tmp`);
+	try {
+		writeFileSync(temporaryPath, input.content, {
+			encoding: "utf8",
+			flag: "wx"
+		});
+		renameSync(temporaryPath, absolutePath);
+	} catch (error) {
+		if (existsSync(temporaryPath)) unlinkSync(temporaryPath);
+		throw error;
+	}
+	return readDocsAuthoringFile(options, input.path);
+}
+async function runCommand(rootDir, command, timeout = 12e4) {
+	try {
+		const result = await execFileAsync(command[0], command.slice(1), {
+			cwd: rootDir,
+			encoding: "utf8",
+			maxBuffer: AUTHORING_MAX_COMMAND_OUTPUT_BYTES,
+			timeout
+		});
+		return {
+			ok: true,
+			command: [...command],
+			stdout: result.stdout,
+			stderr: result.stderr,
+			exitCode: 0
+		};
+	} catch (error) {
+		const failure = error;
+		return {
+			ok: false,
+			command: [...command],
+			stdout: failure.stdout ?? "",
+			stderr: failure.stderr ?? failure.message,
+			exitCode: typeof failure.code === "number" ? failure.code : 1
+		};
+	}
+}
+async function runGit(rootDir, args) {
+	return runCommand(rootDir, ["git", ...args]);
+}
+async function requireGitSuccess(rootDir, args) {
+	const result = await runGit(rootDir, args);
+	if (!result.ok) throw new Error(result.stderr.trim() || `git ${args.join(" ")} failed.`);
+	return result.stdout.trim();
+}
+async function listChangedFiles(rootDir) {
+	const [unstaged, staged, untracked] = await Promise.all([
+		requireGitSuccess(rootDir, [
+			"diff",
+			"--name-only",
+			"--no-ext-diff"
+		]),
+		requireGitSuccess(rootDir, [
+			"diff",
+			"--cached",
+			"--name-only",
+			"--no-ext-diff"
+		]),
+		requireGitSuccess(rootDir, [
+			"ls-files",
+			"--others",
+			"--exclude-standard"
+		])
+	]);
+	return [...new Set([
+		unstaged,
+		staged,
+		untracked
+	].flatMap((value) => value.split(/\r?\n/)).filter(Boolean))].map((value) => value.replace(/\\/g, "/")).sort();
+}
+function validateAuthoringBranch(branch, prefix) {
+	if (!branch.startsWith(prefix) || branch === prefix || /\s|\.\.|~|\^|:|\?|\*|\[|\\/.test(branch)) throw new Error(`Authoring branches must start with ${prefix} and use a valid Git ref name.`);
+}
+async function previewDocsFile(options, filePath) {
+	const state = readDocsAuthoringFile(options, filePath);
+	const source = createFilesystemDocsMcpSource({
+		rootDir: options.rootDir,
+		entry: options.entry ?? "docs",
+		contentDir: options.contentDir ?? options.entry ?? "docs"
+	});
+	const page = (await Promise.resolve(source.getPages())).find((candidate) => candidate.sourcePath === state.path);
+	if (!page) throw new Error(`The docs source did not resolve a public page for ${state.path}.`);
+	const document = renderDocsMarkdownDocument(page);
+	return {
+		file: state.path,
+		url: page.url,
+		title: page.title,
+		sha256: state.sha256,
+		markdown: document.slice(0, 1e5),
+		truncated: document.length > 1e5
+	};
+}
+async function publishDraftPullRequest(options, input) {
+	const rootDir = path.resolve(options.rootDir);
+	const contentRootRelative = projectPath(rootDir, resolveContentRoot(options));
+	const branch = await requireGitSuccess(rootDir, ["branch", "--show-current"]);
+	validateAuthoringBranch(branch, options.branchPrefix?.trim() || "docs/");
+	const changedFiles = await listChangedFiles(rootDir);
+	if (changedFiles.length === 0) throw new Error("No documentation changes are available to publish.");
+	const outsideContent = changedFiles.filter((file) => file !== contentRootRelative && !file.startsWith(`${contentRootRelative}/`));
+	if (outsideContent.length > 0) throw new Error(`Draft PR publishing refuses changes outside ${contentRootRelative}/: ${outsideContent.join(", ")}`);
+	if (!(await runCommand(rootDir, [
+		"gh",
+		"auth",
+		"status"
+	], 3e4)).ok) throw new Error("GitHub CLI authentication is required before publishing.");
+	await requireGitSuccess(rootDir, [
+		"add",
+		"--",
+		contentRootRelative
+	]);
+	await requireGitSuccess(rootDir, [
+		"commit",
+		"-m",
+		input.commitMessage
+	]);
+	await requireGitSuccess(rootDir, [
+		"push",
+		"-u",
+		"origin",
+		branch
+	]);
+	const created = await runCommand(rootDir, [
+		"gh",
+		"pr",
+		"create",
+		"--draft",
+		...options.baseBranch ? ["--base", options.baseBranch] : [],
+		"--head",
+		branch,
+		"--title",
+		input.title,
+		"--body",
+		input.body
+	], 6e4);
+	if (!created.ok) throw new Error(created.stderr.trim() || "Could not create the draft PR.");
+	return {
+		branch,
+		changedFiles,
+		url: created.stdout.trim().split(/\r?\n/).at(-1) ?? "",
+		draft: true
+	};
+}
+/**
+* Create a protected authoring-only MCP server.
+*
+* This server is intentionally separate from createDocsMcpServer and is never wired into public
+* framework adapters. Use stdio locally or place the returned server behind an authenticated,
+* authoring-scoped transport.
+*/
+async function createDocsAuthoringMcpServer(options) {
+	const rootDir = path.resolve(options.rootDir);
+	const contentRoot = resolveContentRoot(options);
+	if (!isContained(rootDir, contentRoot)) throw new Error("The authoring content directory must stay inside the project root.");
+	if (existsSync(contentRoot) && lstatSync(contentRoot).isSymbolicLink()) throw new Error("The authoring content directory cannot be a symbolic link.");
+	const branchPrefix = options.branchPrefix?.trim() || "docs/";
+	const server = new McpServer({
+		name: options.name ?? "@farming-labs/docs-authoring",
+		version: options.version ?? "0.0.0"
+	}, { capabilities: { logging: {} } });
+	server.registerTool("authoring_status", {
+		title: "Inspect documentation authoring status",
+		description: "Return the current branch and changed files before an authoring operation.",
+		annotations: { readOnlyHint: true }
+	}, async () => {
+		return structuredResult({
+			branch: await requireGitSuccess(rootDir, ["branch", "--show-current"]),
+			branchPrefix,
+			contentDirectory: projectPath(rootDir, contentRoot),
+			changedFiles: await listChangedFiles(rootDir),
+			publishEnabled: options.allowPublish === true
+		});
+	});
+	server.registerTool("authoring_create_branch", {
+		title: "Create a documentation authoring branch",
+		description: "Create a constrained branch after verifying the complete worktree is clean.",
+		inputSchema: z.object({ branch: z.string().trim().min(1).max(200) }),
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: false
+		}
+	}, async ({ branch }) => {
+		validateAuthoringBranch(branch, branchPrefix);
+		if ((await listChangedFiles(rootDir)).length > 0) throw new Error("Create the authoring branch before editing; the worktree is not clean.");
+		await requireGitSuccess(rootDir, [
+			"switch",
+			"-c",
+			branch
+		]);
+		return structuredResult({
+			branch,
+			created: true
+		});
+	});
+	server.registerTool("authoring_read_doc", {
+		title: "Read a documentation source file",
+		description: "Read a docs-tree file and return the SHA-256 required for safe overwrites.",
+		inputSchema: z.object({ path: z.string().trim().min(1).max(4096) }),
+		annotations: { readOnlyHint: true }
+	}, async ({ path: filePath }) => structuredResult(readDocsAuthoringFile(options, filePath)));
+	server.registerTool("authoring_write_doc", {
+		title: "Write a documentation source file",
+		description: "Atomically write inside the docs tree. Existing files require the SHA-256 returned by authoring_read_doc.",
+		inputSchema: z.object({
+			path: z.string().trim().min(1).max(4096),
+			content: z.string(),
+			expectedSha256: z.string().regex(/^[a-f0-9]{64}$/).optional()
+		}),
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: true
+		}
+	}, async (input) => structuredResult(writeDocsAuthoringFile(options, input)));
+	server.registerTool("authoring_preview_doc", {
+		title: "Preview machine-readable documentation",
+		description: "Render the edited page through the same Markdown projection used by agents.",
+		inputSchema: z.object({ path: z.string().trim().min(1).max(4096) }),
+		annotations: { readOnlyHint: true }
+	}, async ({ path: filePath }) => structuredResult(await previewDocsFile(options, filePath)));
+	server.registerTool("authoring_run_doctor", {
+		title: "Run docs doctor",
+		description: "Run the operator-configured docs doctor command without a shell.",
+		annotations: { readOnlyHint: true }
+	}, async () => {
+		if (!options.doctorCommand) throw new Error("No doctorCommand was configured for this authoring server.");
+		return structuredResult(await runCommand(rootDir, options.doctorCommand));
+	});
+	server.registerTool("authoring_diff", {
+		title: "Review documentation diff",
+		description: "Return the docs-tree Git diff and any untracked documentation paths.",
+		annotations: { readOnlyHint: true }
+	}, async () => {
+		const diff = await runGit(rootDir, [
+			"diff",
+			"--no-ext-diff",
+			"--unified=3",
+			"HEAD",
+			"--",
+			projectPath(rootDir, contentRoot)
+		]);
+		if (!diff.ok) throw new Error(diff.stderr || "Could not render the documentation diff.");
+		return structuredResult({
+			changedFiles: await listChangedFiles(rootDir),
+			diff: diff.stdout.slice(0, AUTHORING_MAX_COMMAND_OUTPUT_BYTES),
+			truncated: diff.stdout.length > AUTHORING_MAX_COMMAND_OUTPUT_BYTES
+		});
+	});
+	server.registerTool("authoring_analyze_feedback", {
+		title: "Turn recurring agent feedback into improvement drafts",
+		description: "Cluster a project-local JSON or JSONL feedback export and draft golden tasks, issues, and a docs PR description.",
+		inputSchema: z.object({
+			path: z.string().trim().min(1).max(4096),
+			minOccurrences: z.number().int().min(2).max(100).optional()
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ path: filePath, minOccurrences }) => {
+		return structuredResult(analyzeDocsAgentFeedback(readDocsAgentFeedbackFile(resolveProjectInputFile(rootDir, filePath)), { minOccurrences }));
+	});
+	if (options.allowPublish === true) server.registerTool("authoring_publish_draft_pr", {
+		title: "Commit, push, and open a draft documentation PR",
+		description: "Publish docs-only changes after an explicit confirmation. Rejects changes outside the configured content directory.",
+		inputSchema: z.object({
+			confirm: z.literal(true),
+			title: z.string().trim().min(1).max(256),
+			body: z.string().max(65536),
+			commitMessage: z.string().trim().min(1).max(256)
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false,
+			openWorldHint: true
+		}
+	}, async ({ title, body, commitMessage }) => structuredResult(await publishDraftPullRequest(options, {
+		title,
+		body,
+		commitMessage
+	})));
+	return server;
+}
+async function runDocsAuthoringMcpStdio(options) {
+	await serveStdio(() => createDocsAuthoringMcpServer(options));
+}
+
+//#endregion
+export { writeDocsAuthoringFile as i, readDocsAuthoringFile as n, runDocsAuthoringMcpStdio as r, createDocsAuthoringMcpServer as t };

package/dist/browser.d.mts

@@ -1,4 +1,4 @@
-import { c as emitDocsAnalyticsEvent, d as resolveDocsAnalyticsConfig } from "./analytics-C75BnTEW.mjs";
-import { t as applySidebarFolderIndexBehavior } from "./sidebar-CwZlgyAz.mjs";
-import { n as resolveDocsAudienceExposure, t as DocsContentAudience } from "./audience-exposure-Cw3SA4WE.mjs";
+import { c as emitDocsAnalyticsEvent, d as resolveDocsAnalyticsConfig } from "./analytics-B-jz7re8.mjs";
+import { t as applySidebarFolderIndexBehavior } from "./sidebar-DmXRpAAK.mjs";
+import { n as resolveDocsAudienceExposure, t as DocsContentAudience } from "./audience-exposure-BW13cI2O.mjs";
 export { type DocsContentAudience, applySidebarFolderIndexBehavior, emitDocsAnalyticsEvent, resolveDocsAnalyticsConfig, resolveDocsAudienceExposure };