@farming-labs/docs 0.1.92 → 0.1.93

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-DFseGu9S.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-DjLUv0Dq.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();

package/dist/{doctor-DFseGu9S.mjs → doctor-DjLUv0Dq.mjs}

@@ -736,7 +736,8 @@ async function probeTextRoute(baseUrl, route) {
 		return {
 			ok: true,
 			status: response.status,
-			detail: `${route} returned HTTP ${response.status} with ${body.length} characters.`
+			detail: `${route} returned HTTP ${response.status} with ${body.length} characters.`,
+			body
 		};
 	} catch (error) {
 		return {
@@ -745,6 +746,56 @@ async function probeTextRoute(baseUrl, route) {
 		};
 	}
 }
+function decodeHtmlEntity(value) {
+	const named = {
+		amp: "&",
+		apos: "'",
+		gt: ">",
+		lt: "<",
+		quot: "\""
+	};
+	return value.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, raw) => {
+		const lower = raw.toLowerCase();
+		if (lower.startsWith("#x")) {
+			const codePoint = Number.parseInt(lower.slice(2), 16);
+			return Number.isFinite(codePoint) && codePoint >= 0 && codePoint <= 1114111 ? String.fromCodePoint(codePoint) : entity;
+		}
+		if (lower.startsWith("#")) {
+			const codePoint = Number.parseInt(lower.slice(1), 10);
+			return Number.isFinite(codePoint) && codePoint >= 0 && codePoint <= 1114111 ? String.fromCodePoint(codePoint) : entity;
+		}
+		return named[lower] ?? entity;
+	});
+}
+function htmlAttribute(tag, name) {
+	for (const match of tag.matchAll(/([^\s"'<>/=]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g)) {
+		if (match[1]?.toLowerCase() !== name.toLowerCase()) continue;
+		return decodeHtmlEntity(match[2] ?? match[3] ?? match[4] ?? "");
+	}
+}
+function hasJsonLdScript(html) {
+	return /<script\b(?=[^>]*\btype\s*=\s*["']application\/ld\+json["'])[^>]*>/i.test(html);
+}
+function markdownAlternateHref(html) {
+	for (const match of html.matchAll(/<link\b[^>]*>/gi)) {
+		const tag = match[0];
+		const rel = htmlAttribute(tag, "rel") ?? "";
+		const type = htmlAttribute(tag, "type") ?? "";
+		const href = htmlAttribute(tag, "href");
+		const relTokens = rel.toLowerCase().split(/\s+/).filter(Boolean);
+		if (href && relTokens.includes("alternate") && /^text\/markdown(?:\s*;|$)/i.test(type.trim())) return href;
+	}
+}
+function resolveMarkdownAlternateUrl(href, pageUrl) {
+	if (!href) return void 0;
+	try {
+		const url = new URL(href, pageUrl);
+		const page = new URL(pageUrl);
+		return url.origin === page.origin && url.pathname.endsWith(".md") ? url : void 0;
+	} catch {
+		return;
+	}
+}
 async function probeRobotsRoute(baseUrl, route = DEFAULT_ROBOTS_TXT_ROUTE) {
 	const url = joinDoctorUrl(baseUrl, route);
 	try {
@@ -923,6 +974,93 @@ function hostedRobotsRoute(discoveryBody) {
 		route: readDiscoveryRoute(robots?.route) ?? DEFAULT_ROBOTS_TXT_ROUTE
 	};
 }
+function hostedCapability(discoveryBody, key) {
+	const root = asRecord(discoveryBody);
+	const capability = asRecord(root?.capabilities)?.[key];
+	if (typeof capability === "boolean") return capability;
+	const enabled = asRecord(root?.[key])?.enabled;
+	return typeof enabled === "boolean" ? enabled : void 0;
+}
+function hostedRootDocsRoute(discoveryBody) {
+	const site = asRecord(asRecord(discoveryBody)?.site);
+	return `/${(typeof site?.entry === "string" && site.entry.trim() ? site.entry.trim() : "docs").replace(/^\/+|\/+$/g, "") || "docs"}`;
+}
+function hostedPageUrl(baseUrl, pageRoute) {
+	try {
+		const base = new URL(baseUrl);
+		const parsed = new URL(pageRoute, base.origin);
+		if (parsed.origin !== base.origin) return void 0;
+		parsed.hash = "";
+		parsed.search = "";
+		const basePath = base.pathname.replace(/\/+$/, "");
+		const pagePath = parsed.pathname.replace(/\/+$/, "") || "/";
+		const pathname = !basePath || pagePath === basePath || pagePath.startsWith(`${basePath}/`) ? pagePath : `${basePath}${pagePath}`;
+		return new URL(pathname || "/", base.origin).toString().replace(/\/+$/, "");
+	} catch {
+		return;
+	}
+}
+function sampleHostedPageUrls(baseUrl, discoveryBody, pages, limit = 10) {
+	const pageRoutes = pages.map((page) => page.url).filter((route) => route.startsWith("/") && !route.endsWith(".md"));
+	const fallback = hostedRootDocsRoute(discoveryBody);
+	const unique = Array.from(new Set(pageRoutes.length > 0 ? pageRoutes : [fallback])).sort();
+	return (unique.length <= limit ? unique : Array.from({ length: limit }, (_, index) => unique[Math.floor(index * (unique.length / limit))])).map((route) => hostedPageUrl(baseUrl, route)).filter((url) => typeof url === "string");
+}
+async function probeHostedHtmlPage(url) {
+	try {
+		const response = await fetchWithTimeout(url, { headers: { Accept: "text/html, */*" } });
+		const body = await response.text().catch(() => "");
+		const pathname = new URL(url).pathname;
+		if (!response.ok) return {
+			ok: false,
+			detail: `${pathname} returned HTTP ${response.status}.`,
+			hasJsonLd: false,
+			hasMarkdownAlternate: false
+		};
+		const alternateUrl = resolveMarkdownAlternateUrl(markdownAlternateHref(body), url);
+		return {
+			ok: true,
+			detail: `${pathname} returned HTML with ${body.length} characters.`,
+			hasJsonLd: hasJsonLdScript(body),
+			hasMarkdownAlternate: Boolean(alternateUrl)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			detail: `${url} failed: ${error instanceof Error ? error.message : String(error)}.`,
+			hasJsonLd: false,
+			hasMarkdownAlternate: false
+		};
+	}
+}
+function hostedSurfaceScore(probes, predicate) {
+	const total = probes.length;
+	const passed = probes.filter((probe) => probe.ok && predicate(probe)).length;
+	if (total === 0) return {
+		status: "warn",
+		score: 0,
+		passed: 0,
+		total
+	};
+	if (passed === total) return {
+		status: "pass",
+		score: 5,
+		passed,
+		total
+	};
+	if (passed > 0) return {
+		status: "warn",
+		score: Math.round(passed / total * 5),
+		passed,
+		total
+	};
+	return {
+		status: "fail",
+		score: 0,
+		passed,
+		total
+	};
+}
 async function buildHostedAgentChecks(url, pages) {
 	let baseUrl;
 	try {
@@ -959,6 +1097,14 @@ async function buildHostedAgentChecks(url, pages) {
 		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 htmlPageUrls = sampleHostedPageUrls(baseUrl, discovery.body, pages);
+	const htmlPageProbes = await Promise.all(htmlPageUrls.map((pageUrl) => probeHostedHtmlPage(pageUrl)));
+	const structuredDataScore = hostedSurfaceScore(htmlPageProbes, (probe) => probe.hasJsonLd);
+	const structuredDataEnabled = hostedCapability(discovery.body, "structuredData");
+	checks.push(makeCheck("hosted-structured-data", "Hosted structured data", structuredDataEnabled === false ? "warn" : structuredDataScore.status, structuredDataEnabled === false ? 0 : structuredDataScore.score, 5, structuredDataEnabled === false ? "The hosted discovery spec reports structured data as disabled." : structuredDataScore.total > 0 ? `${structuredDataScore.passed}/${structuredDataScore.total} sampled hosted docs pages include application/ld+json structured data.` : "No hosted docs pages were available to verify application/ld+json structured data.", structuredDataEnabled === false || structuredDataScore.status === "pass" ? void 0 : "Keep JSON-LD enabled on every docs page so agents can read canonical title, description, URL, breadcrumbs, and freshness hints."));
+	const markdownAlternateScore = hostedSurfaceScore(htmlPageProbes, (probe) => probe.hasMarkdownAlternate);
+	const markdownRoutesEnabled = hostedCapability(discovery.body, "markdownRoutes");
+	checks.push(makeCheck("hosted-markdown-alternate", "Hosted markdown alternate links", markdownRoutesEnabled === false ? "warn" : markdownAlternateScore.status, markdownRoutesEnabled === false ? 0 : markdownAlternateScore.score, 5, markdownRoutesEnabled === false ? "The hosted discovery spec reports markdown routes as disabled." : markdownAlternateScore.total > 0 ? `${markdownAlternateScore.passed}/${markdownAlternateScore.total} sampled hosted docs pages include <link rel="alternate" type="text/markdown"> pointing to .md routes.` : "No hosted docs pages were available to verify markdown alternate links.", markdownRoutesEnabled === false || markdownAlternateScore.status === "pass" ? void 0 : "Add a text/markdown alternate link in each docs page head, usually through `alternates.types['text/markdown']`, so agents can discover the page markdown URL from HTML."));
 	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.`));

package/package.json

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