@farming-labs/docs 0.1.68 → 0.1.69

package/dist/cli/index.mjs

@@ -100,7 +100,7 @@ async function main() {
 		printAgentCompactHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "doctor") {
-		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-DrZM2dke.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-B2uu7zsB.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();

package/dist/{doctor-DrZM2dke.mjs → doctor-B2uu7zsB.mjs}

@@ -9,6 +9,7 @@ import { t as detectFramework } from "./utils-DSMXVnEu.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
+import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types";
 
 //#region src/cli/doctor.ts
 const NEXT_CONFIG_PATTERN = /^next\.config\.(?:[cm]?js|[cm]?ts)$/;
@@ -60,6 +61,19 @@ function parseDoctorArgs(argv) {
 			parsed.configPath = value;
 			continue;
 		}
+		if (arg.startsWith("--url=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --url.");
+			parsed.url = value;
+			continue;
+		}
+		if (arg === "--url") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --url.");
+			parsed.url = value;
+			index += 1;
+			continue;
+		}
 		if (arg === "--config") {
 			const value = argv[index + 1];
 			if (!value || value.startsWith("--")) throw new Error("Missing value for --config.");
@@ -89,6 +103,7 @@ ${pc.dim("Options:")}
   ${pc.cyan("--site")}             Score reader-facing docs quality for the current docs app
   ${pc.cyan("--human")}            Alias for ${pc.cyan("--site")}
   ${pc.cyan("--json")}             Print the report as JSON for CI, scripts, and other agents
+  ${pc.cyan("--url <url>")}        Probe hosted agent surfaces, e.g. ${pc.dim("https://docs.example.com")}
   ${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
 `);
@@ -466,6 +481,10 @@ function gradeForHumanScore(score) {
 	if (score >= 60) return "Promising";
 	return "Needs work";
 }
+function percentageScore(score, maxScore) {
+	if (maxScore <= 0) return 0;
+	return Math.round(score / maxScore * 100);
+}
 function formatStatus(status) {
 	if (status === "pass") return pc.green("PASS");
 	if (status === "warn") return pc.yellow("WARN");
@@ -611,6 +630,216 @@ function buildHumanCoverage(pages, navigationPages) {
 		navigationPages
 	};
 }
+function normalizeDoctorBaseUrl(value) {
+	const url = new URL(value);
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("URL must use http or https.");
+	url.hash = "";
+	url.search = "";
+	url.pathname = url.pathname.replace(/\/+$/, "");
+	return url.toString().replace(/\/+$/, "");
+}
+function joinDoctorUrl(baseUrl, route) {
+	const base = new URL(baseUrl);
+	const basePath = base.pathname.replace(/\/+$/, "");
+	const routePath = route.startsWith("/") ? route : `/${route}`;
+	return new URL(`${basePath}${routePath}`, base.origin).toString();
+}
+function toMarkdownRoute(pageUrl) {
+	if (!pageUrl) return void 0;
+	const normalized = pageUrl === "/" ? "/index" : pageUrl.replace(/\/+$/, "");
+	return normalized.endsWith(".md") ? normalized : `${normalized}.md`;
+}
+async function fetchWithTimeout(url, init = {}, timeoutMs = 8e3) {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await fetch(url, {
+			...init,
+			signal: controller.signal
+		});
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+async function probeTextRoute(baseUrl, route) {
+	const url = joinDoctorUrl(baseUrl, route);
+	try {
+		const response = await fetchWithTimeout(url, { headers: { Accept: "text/plain, text/markdown, */*" } });
+		const body = await response.text().catch(() => "");
+		if (!response.ok) return {
+			ok: false,
+			status: response.status,
+			detail: `${route} returned HTTP ${response.status}.`
+		};
+		if (body.trim().length === 0) return {
+			ok: false,
+			status: response.status,
+			detail: `${route} returned an empty body.`
+		};
+		return {
+			ok: true,
+			status: response.status,
+			detail: `${route} returned HTTP ${response.status} with ${body.length} characters.`
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+}
+async function probeJsonRoute(baseUrl, route) {
+	const url = joinDoctorUrl(baseUrl, route);
+	try {
+		const response = await fetchWithTimeout(url, { headers: { Accept: "application/json" } });
+		const text = await response.text().catch(() => "");
+		if (!response.ok) return {
+			ok: false,
+			status: response.status,
+			detail: `${route} returned HTTP ${response.status}.`
+		};
+		try {
+			const body = JSON.parse(text);
+			return {
+				ok: true,
+				status: response.status,
+				detail: `${route} returned valid JSON.`,
+				body
+			};
+		} catch {
+			return {
+				ok: false,
+				status: response.status,
+				detail: `${route} did not return valid JSON.`
+			};
+		}
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+}
+async function parseMcpResponse(response) {
+	const contentType = response.headers.get("content-type") ?? "";
+	const body = await response.text();
+	if (contentType.includes("application/json")) return JSON.parse(body);
+	const data = body.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).filter(Boolean).at(-1);
+	if (!data) throw new Error(`Expected MCP JSON-RPC payload, got ${body.slice(0, 120) || "empty body"}.`);
+	return JSON.parse(data);
+}
+async function postMcpJson(baseUrl, route, body, sessionId) {
+	return fetchWithTimeout(joinDoctorUrl(baseUrl, route), {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+			"mcp-protocol-version": LATEST_PROTOCOL_VERSION,
+			...sessionId ? { "mcp-session-id": sessionId } : {}
+		},
+		body: JSON.stringify(body)
+	});
+}
+async function probeMcpRoute(baseUrl, route) {
+	try {
+		const initializeResponse = await postMcpJson(baseUrl, route, {
+			jsonrpc: "2.0",
+			id: "doctor-initialize",
+			method: "initialize",
+			params: {
+				protocolVersion: LATEST_PROTOCOL_VERSION,
+				capabilities: {},
+				clientInfo: {
+					name: "@farming-labs/docs doctor",
+					version: "0.0.0"
+				}
+			}
+		});
+		const initializePayload = await parseMcpResponse(initializeResponse);
+		if (!initializeResponse.ok || initializePayload.error) return {
+			ok: false,
+			detail: `${route} initialize returned HTTP ${initializeResponse.status}: ${String(initializePayload.error?.message ?? "unknown MCP error")}.`
+		};
+		const sessionId = initializeResponse.headers.get("mcp-session-id");
+		if (!sessionId) return {
+			ok: false,
+			detail: `${route} initialize did not return mcp-session-id.`
+		};
+		await postMcpJson(baseUrl, route, {
+			jsonrpc: "2.0",
+			method: "notifications/initialized",
+			params: {}
+		}, sessionId).catch(() => void 0);
+		const toolsResponse = await postMcpJson(baseUrl, route, {
+			jsonrpc: "2.0",
+			id: "doctor-tools-list",
+			method: "tools/list",
+			params: {}
+		}, sessionId);
+		const toolsPayload = await parseMcpResponse(toolsResponse);
+		await fetchWithTimeout(joinDoctorUrl(baseUrl, route), {
+			method: "DELETE",
+			headers: {
+				"mcp-protocol-version": LATEST_PROTOCOL_VERSION,
+				"mcp-session-id": sessionId
+			}
+		}).catch(() => void 0);
+		if (!toolsResponse.ok || toolsPayload.error) return {
+			ok: false,
+			detail: `${route} tools/list returned HTTP ${toolsResponse.status}: ${String(toolsPayload.error?.message ?? "unknown MCP error")}.`
+		};
+		const tools = toolsPayload.result?.tools;
+		const toolNames = Array.isArray(tools) ? tools.map((tool) => tool.name).filter((name) => typeof name === "string") : [];
+		const missingTools = [
+			"list_pages",
+			"get_navigation",
+			"search_docs",
+			"read_page"
+		].filter((tool) => !toolNames.includes(tool));
+		if (missingTools.length > 0) return {
+			ok: false,
+			detail: `${route} connected but is missing tools: ${missingTools.join(", ")}.`
+		};
+		return {
+			ok: true,
+			detail: `${route} initialized and exposed ${toolNames.length} MCP tool${toolNames.length === 1 ? "" : "s"}.`
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${route} failed: ${error instanceof Error ? error.message : String(error)}.`
+		};
+	}
+}
+async function buildHostedAgentChecks(url, pages) {
+	let baseUrl;
+	try {
+		baseUrl = normalizeDoctorBaseUrl(url);
+	} catch (error) {
+		return { checks: [makeCheck("hosted-url", "Hosted URL", "fail", 0, 5, `Could not parse --url "${url}": ${error instanceof Error ? error.message : String(error)}`, "Pass a full hosted URL such as https://docs.example.com.")] };
+	}
+	const checks = [];
+	const discovery = await probeJsonRoute(baseUrl, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE);
+	checks.push(makeCheck("hosted-agent-discovery", "Hosted agent discovery", discovery.ok ? "pass" : "fail", discovery.ok ? 5 : 0, 5, `${baseUrl}: ${discovery.detail}`, discovery.ok ? void 0 : `Make sure ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE} is routed to the shared docs API on the deployed site.`));
+	const llms = await Promise.all([probeTextRoute(baseUrl, DEFAULT_LLMS_TXT_ROUTE), probeTextRoute(baseUrl, DEFAULT_LLMS_FULL_TXT_ROUTE)]);
+	const llmsPassed = llms.filter((result) => result.ok).length;
+	checks.push(makeCheck("hosted-llms", "Hosted llms.txt", llmsPassed === llms.length ? "pass" : llmsPassed > 0 ? "warn" : "fail", llmsPassed === llms.length ? 5 : llmsPassed > 0 ? 3 : 0, 5, llms.map((result) => result.detail).join(" "), llmsPassed === llms.length ? void 0 : "Verify deployed /llms.txt and /llms-full.txt routes return non-empty text."));
+	const skill = await Promise.all([probeTextRoute(baseUrl, DEFAULT_SKILL_MD_ROUTE), probeTextRoute(baseUrl, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE)]);
+	const skillPassed = skill.filter((result) => result.ok).length;
+	checks.push(makeCheck("hosted-skill", "Hosted skill.md", skillPassed === skill.length ? "pass" : skillPassed > 0 ? "warn" : "fail", skillPassed === skill.length ? 5 : skillPassed > 0 ? 3 : 0, 5, skill.map((result) => result.detail).join(" "), skillPassed === skill.length ? void 0 : "Verify deployed /skill.md and /.well-known/skill.md routes return non-empty markdown."));
+	const markdownRoute = toMarkdownRoute(pages[0]?.url);
+	if (markdownRoute) {
+		const markdown = await probeTextRoute(baseUrl, markdownRoute);
+		checks.push(makeCheck("hosted-markdown", "Hosted markdown route", markdown.ok ? "pass" : "fail", markdown.ok ? 5 : 0, 5, markdown.detail, markdown.ok ? void 0 : `Verify deployed markdown routes are forwarded, starting with ${markdownRoute}.`));
+	} else checks.push(makeCheck("hosted-markdown", "Hosted markdown route", "warn", 0, 5, "No local docs page was available to choose a sample .md route.", "Add docs pages so the hosted doctor can probe a representative .md route."));
+	const mcp = await Promise.all([probeMcpRoute(baseUrl, DEFAULT_MCP_PUBLIC_ROUTE), probeMcpRoute(baseUrl, DEFAULT_MCP_WELL_KNOWN_ROUTE)]);
+	const mcpPassed = mcp.filter((result) => result.ok).length;
+	checks.push(makeCheck("hosted-mcp", "Hosted MCP handshake", mcpPassed === mcp.length ? "pass" : mcpPassed > 0 ? "warn" : "fail", mcpPassed === mcp.length ? 10 : mcpPassed > 0 ? 5 : 0, 10, mcp.map((result) => result.detail).join(" "), mcpPassed === mcp.length ? void 0 : `Verify deployed ${DEFAULT_MCP_PUBLIC_ROUTE} and ${DEFAULT_MCP_WELL_KNOWN_ROUTE} support Streamable HTTP initialize and tools/list.`));
+	return {
+		baseUrl,
+		checks
+	};
+}
 async function loadDocsConfigModuleWithProjectEnv(rootDir, explicitPath) {
 	const env = loadProjectEnv(rootDir);
 	const injectedKeys = Object.entries(env).filter(([key]) => process.env[key] === void 0).map(([key, value]) => {
@@ -717,6 +946,8 @@ async function inspectAgentReadiness(options = {}) {
 	const coverageResult = coverageScore(coverage.explicitCoverage);
 	checks.push(makeCheck("coverage", "Explicit page optimization", coverageResult.status, coverageResult.score, 10, coverage.totalPages > 0 ? `${coverage.explicitPages}/${coverage.totalPages} pages define explicit machine-only context (${coverage.pagesWithAgentFiles} agent.md, ${coverage.pagesWithAgentBlocks} Agent blocks, ${coverage.explicitCoverage}% of pages).` : "No docs pages were available to score explicit page optimization.", coverage.explicitCoverage >= 50 ? void 0 : "Add agent.md files or <Agent> blocks to more pages, or run docs agent compact to create page-level machine docs."));
 	checks.push(makeCheck("compact", "Agent compaction freshness", compactionResult.status, compactionResult.score, 5, `${compactionCoverage.freshGeneratedPages} fresh, ${compactionCoverage.staleGeneratedPages} stale, ${compactionCoverage.modifiedGeneratedPages} modified, ${compactionCoverage.unknownGeneratedPages} unknown, ${compactionCoverage.tokenBudgetMissingPages} token-budget missing, and ${compactionCoverage.otherMissingPages} other missing page${compactionCoverage.otherMissingPages === 1 ? "" : "s"} across compactable docs pages.` + (compactConfigured ? " agent.compact defaults are configured." : " No agent.compact defaults were found in docs config."), compactionResult.recommendation));
+	const hosted = options.url ? await buildHostedAgentChecks(options.url, pages) : void 0;
+	if (hosted) checks.push(...hosted.checks);
 	const score = checks.reduce((total, check) => total + check.score, 0);
 	const maxScore = checks.reduce((total, check) => total + check.maxScore, 0);
 	return {
@@ -725,9 +956,10 @@ async function inspectAgentReadiness(options = {}) {
 		configPath: path.relative(rootDir, configPath).replace(/\\/g, "/"),
 		entry,
 		contentDir,
+		url: hosted?.baseUrl,
 		score,
 		maxScore,
-		grade: gradeForAgentScore(score),
+		grade: gradeForAgentScore(percentageScore(score, maxScore)),
 		checks,
 		coverage,
 		recommendations: checks.map((check) => check.recommendation).filter((recommendation) => Boolean(recommendation)).slice(0, 3)
@@ -808,7 +1040,7 @@ async function inspectHumanReadiness(options = {}) {
 		contentDir,
 		score,
 		maxScore,
-		grade: gradeForHumanScore(score),
+		grade: gradeForHumanScore(percentageScore(score, maxScore)),
 		checks,
 		coverage,
 		recommendations: checks.map((check) => check.recommendation).filter((recommendation) => Boolean(recommendation)).slice(0, 3)
@@ -819,6 +1051,7 @@ function printAgentDoctorReport(report) {
 	console.log();
 	console.log(`${pc.bold("Score:")} ${pc.cyan(`${report.score}/${report.maxScore}`)} ${pc.dim(`(${report.grade})`)}`);
 	console.log(`${pc.bold("Framework:")} ${report.framework} ${pc.dim("•")} ${pc.bold("Entry:")} ${report.entry ?? "docs"} ${pc.dim("•")} ${pc.bold("Content:")} ${report.contentDir ?? "-"}`);
+	if (report.url) console.log(`${pc.bold("Hosted URL:")} ${report.url}`);
 	console.log(`${pc.bold("Explicit agent-friendly pages:")} ${report.coverage.explicitPages}/${report.coverage.totalPages} pages ${pc.dim(`(${report.coverage.explicitCoverage}%)`)}`);
 	console.log(`${pc.bold("Generated agent.md freshness:")} ${report.coverage.compaction.freshGeneratedPages} fresh ${pc.dim("•")} ${report.coverage.compaction.staleGeneratedPages} stale ${pc.dim("•")} ${report.coverage.compaction.modifiedGeneratedPages} modified ${pc.dim("•")} ${report.coverage.compaction.tokenBudgetMissingPages} token-budget missing`);
 	console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.1.68",
+  "version": "0.1.69",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",