@farming-labs/docs 0.2.52 → 0.2.53

package/dist/{package-version-C8PigBZk.mjs → package-version-DxnTZH4m.mjs}

@@ -1,4 +1,4 @@
-import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-D-xTRNuh.mjs";
+import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-CMZTjRQT.mjs";
 import pc from "picocolors";
 import * as p from "@clack/prompts";
 

package/dist/{reading-time-CPAy1SWO.mjs → reading-time-BuK2YL23.mjs}

@@ -1,3 +1,6 @@
+import { a as normalizePageAgentFrontmatter, i as hasStructuredPageAgentContract } from "./agent-contract-b0akaPcg.mjs";
+import { Et as DEFAULT_SITEMAP_XML_ROUTE, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, wt as DEFAULT_SITEMAP_MD_ROUTE } from "./agent-BMxMpEa0.mjs";
+import { n as DEFAULT_ROBOTS_TXT_ROUTE } from "./robots-C6uQG-fS.mjs";
 import matter from "gray-matter";
 
 //#region src/define-docs.ts
@@ -158,41 +161,236 @@ function extendTheme(baseTheme, extensions) {
 }
 
 //#endregion
-//#region src/i18n.ts
-function normalizeSegment(value) {
-	return value.replace(/^\/+|\/+$/g, "");
-}
-function splitSegments(value) {
-	const cleaned = normalizeSegment(value);
-	return cleaned ? cleaned.split("/").filter(Boolean) : [];
-}
-function resolveDocsI18n(config) {
-	if (!config || !Array.isArray(config.locales)) return null;
-	const locales = Array.from(new Set(config.locales.map((l) => l.trim()).filter(Boolean)));
-	if (locales.length === 0) return null;
-	return {
-		locales,
-		defaultLocale: config.defaultLocale && locales.includes(config.defaultLocale) ? config.defaultLocale : locales[0]
-	};
+//#region src/agent-conformance.ts
+const DOCS_AGENT_CONTRACT_VERSION = "1.0";
+function normalizeOrigin(value) {
+	return value.replace(/\/+$/, "");
 }
-function resolveDocsLocale(searchParams, i18n) {
-	if (!i18n) return void 0;
-	const raw = searchParams.get("lang") ?? searchParams.get("locale");
-	if (!raw) return void 0;
-	if (i18n.locales.includes(raw)) return raw;
-	return i18n.defaultLocale;
-}
-function resolveDocsPath(pathname, entry) {
-	const entryBase = normalizeSegment(entry || "docs") || "docs";
-	const entryParts = splitSegments(entryBase);
-	const pathParts = splitSegments(pathname);
-	let rest = pathParts;
-	if (entryParts.length > 0) {
-		if (pathParts.slice(0, entryParts.length).join("/") === entryParts.join("/")) rest = pathParts.slice(entryParts.length);
+function normalizeEntry(value) {
+	return value.replace(/^\/+|\/+$/g, "") || "docs";
+}
+/**
+* The framework-neutral public surface every first-party adapter must implement.
+* Adapter tests consume this list so new routes and invariants are added once.
+*/
+function createDocsAgentContractCases(options = {}) {
+	const origin = normalizeOrigin(options.origin ?? "http://localhost");
+	const entry = normalizeEntry(options.entry ?? "docs");
+	const locale = options.locale === void 0 ? "fr" : options.locale;
+	const url = (route) => `${origin}${route.startsWith("/") ? route : `/${route}`}`;
+	const markdown = ["text/markdown"];
+	const json = ["application/json"];
+	const cases = [
+		{
+			surface: "discovery",
+			request: { url: url(DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json
+			}
+		},
+		{
+			surface: "config",
+			request: { url: url(DEFAULT_DOCS_CONFIG_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json,
+				bodyIncludes: ["docs-config-map.v1"]
+			}
+		},
+		{
+			surface: "diagnostics",
+			request: { url: url(DEFAULT_DOCS_DIAGNOSTICS_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: json,
+				bodyIncludes: ["docs-diagnostics.v1"]
+			}
+		},
+		{
+			surface: "feedback-schema",
+			request: { url: url(`${DEFAULT_AGENT_FEEDBACK_ROUTE}/schema`) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["application/schema+json"]
+			}
+		},
+		{
+			surface: "markdown",
+			request: { url: url(`/${entry}.md`) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "markdown-accept",
+			request: {
+				url: url(`/${entry}`),
+				init: { headers: { Accept: "text/markdown" } }
+			},
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "markdown-missing",
+			request: { url: url(`/${entry}/missing.md`) },
+			expect: {
+				statuses: [200, 404],
+				contentTypes: markdown,
+				bodyIncludes: ["not found"]
+			}
+		},
+		{
+			surface: "llms",
+			request: { url: url(DEFAULT_LLMS_TXT_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["text/plain"],
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "llms-full",
+			request: { url: url(DEFAULT_LLMS_FULL_TXT_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["text/plain"],
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "agents",
+			request: { url: url(DEFAULT_AGENTS_MD_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["AGENTS.md"]
+			}
+		},
+		{
+			surface: "skill",
+			request: { url: url(DEFAULT_SKILL_MD_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["name:"]
+			}
+		},
+		{
+			surface: "sitemap-xml",
+			request: { url: url(DEFAULT_SITEMAP_XML_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["application/xml", "text/xml"],
+				bodyIncludes: ["<urlset"]
+			}
+		},
+		{
+			surface: "sitemap-markdown",
+			request: { url: url(DEFAULT_SITEMAP_MD_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: markdown,
+				bodyIncludes: ["Introduction"]
+			}
+		},
+		{
+			surface: "robots",
+			request: { url: url(DEFAULT_ROBOTS_TXT_ROUTE) },
+			expect: {
+				statuses: [200],
+				contentTypes: ["text/plain"],
+				bodyIncludes: ["User-agent:"]
+			}
+		},
+		{
+			surface: "mcp",
+			request: {
+				url: url(DEFAULT_MCP_WELL_KNOWN_ROUTE),
+				init: {
+					method: "POST",
+					headers: {
+						Accept: "application/json, text/event-stream",
+						"Content-Type": "application/json",
+						"MCP-Protocol-Version": "2025-11-25"
+					},
+					body: JSON.stringify({
+						jsonrpc: "2.0",
+						id: 1,
+						method: "initialize",
+						params: {
+							protocolVersion: "2025-11-25",
+							capabilities: {},
+							clientInfo: {
+								name: "agent-conformance",
+								version: DOCS_AGENT_CONTRACT_VERSION
+							}
+						}
+					})
+				}
+			},
+			expect: {
+				statuses: [200],
+				contentTypes: ["application/json", "text/event-stream"],
+				bodyIncludes: ["serverInfo", "protocolVersion"]
+			}
+		}
+	];
+	if (locale) cases.splice(6, 0, {
+		surface: "markdown-locale",
+		request: { url: url(`/${entry}.md?lang=${encodeURIComponent(locale)}`) },
+		expect: {
+			statuses: [200],
+			contentTypes: markdown,
+			bodyIncludes: ["Bonjour"]
+		}
+	});
+	return cases;
+}
+function matchesContentType(actual, expected) {
+	const [mediaType] = actual.split(";", 1);
+	const normalized = mediaType?.trim().toLowerCase();
+	if (!normalized) return false;
+	return expected.some((value) => normalized === value.trim().toLowerCase());
+}
+async function runDocsAgentConformance(options) {
+	const cases = createDocsAgentContractCases(options);
+	const results = [];
+	for (const contractCase of cases) {
+		const issues = [];
+		try {
+			const response = await options.handle(new Request(contractCase.request.url, contractCase.request.init), contractCase.surface);
+			const contentType = response.headers.get("content-type") ?? "";
+			const body = await response.text();
+			if (!contractCase.expect.statuses.includes(response.status)) issues.push(`expected status ${contractCase.expect.statuses.join(" or ")}, received ${response.status}`);
+			if (!matchesContentType(contentType, contractCase.expect.contentTypes)) issues.push(`expected content-type ${contractCase.expect.contentTypes.join(" or ")}, received ${contentType || "<missing>"}`);
+			for (const requiredText of contractCase.expect.bodyIncludes ?? []) if (!body.toLowerCase().includes(requiredText.toLowerCase())) issues.push(`response body did not include ${JSON.stringify(requiredText)}`);
+			results.push({
+				surface: contractCase.surface,
+				passed: issues.length === 0,
+				status: response.status,
+				contentType,
+				issues
+			});
+		} catch (error) {
+			issues.push(error instanceof Error ? error.message : String(error));
+			results.push({
+				surface: contractCase.surface,
+				passed: false,
+				issues
+			});
+		}
 	}
 	return {
-		slug: rest.join("/"),
-		entryPath: entryBase
+		adapter: options.adapter,
+		contractVersion: DOCS_AGENT_CONTRACT_VERSION,
+		passed: results.every((result) => result.passed),
+		cases: results
 	};
 }
 
@@ -327,6 +525,51 @@ function normalizeDateModified(value) {
 	const date = new Date(value);
 	return Number.isNaN(date.getTime()) ? value : date.toISOString();
 }
+function buildAgentContractHowTo(value, fallback) {
+	const agent = normalizePageAgentFrontmatter(value);
+	if (!agent || !hasStructuredPageAgentContract(agent)) return void 0;
+	const steps = [];
+	for (const command of agent.commands ?? []) {
+		const run = typeof command === "string" ? command : command.run;
+		const description = typeof command === "string" ? void 0 : command.description;
+		const cwd = typeof command === "string" ? void 0 : command.cwd;
+		steps.push({
+			"@type": "HowToStep",
+			position: steps.length + 1,
+			name: description ?? "Run command",
+			text: cwd ? `${run} (from ${cwd})` : run
+		});
+	}
+	for (const verification of agent.verification ?? []) {
+		const description = typeof verification === "string" ? verification : verification.description ?? "Verify the result";
+		const details = typeof verification === "string" ? verification : [verification.run, verification.expect ? `Expected: ${verification.expect}` : void 0].filter(Boolean).join(". ");
+		steps.push({
+			"@type": "HowToStep",
+			position: steps.length + 1,
+			name: description,
+			text: details || description
+		});
+	}
+	const supplies = [...(agent.prerequisites ?? []).map((name) => ({
+		"@type": "HowToSupply",
+		name
+	})), ...(agent.files ?? []).map((name) => ({
+		"@type": "HowToSupply",
+		name
+	}))];
+	const about = Object.entries(agent.appliesTo ?? {}).flatMap(([kind, values]) => (typeof values === "string" ? [values] : values ?? []).map((name) => ({
+		"@type": "Thing",
+		name: `${kind}: ${name}`
+	})));
+	return {
+		"@type": "HowTo",
+		name: agent.task ?? fallback.title,
+		...agent.outcome ?? fallback.description ? { description: agent.outcome ?? fallback.description } : {},
+		...about.length > 0 ? { about } : {},
+		...supplies.length > 0 ? { supply: supplies } : {},
+		...steps.length > 0 ? { step: steps } : {}
+	};
+}
 /**
 * Resolve the public docs site URL from existing agent-facing config.
 *
@@ -370,6 +613,8 @@ function buildDocsPageStructuredData(input) {
 		}
 	};
 	if (input.description) result.description = input.description;
+	const agentContract = buildAgentContractHowTo(input.agent, input);
+	if (agentContract) result.mainEntity = agentContract;
 	const dateModified = normalizeDateModified(input.dateModified);
 	if (dateModified) result.dateModified = dateModified;
 	return result;
@@ -437,4 +682,4 @@ function resolveReadingTimeFromSource(source, wordsPerMinute, options) {
 }
 
 //#endregion
-export { extendTheme as _, resolveReadingTimeOptions as a, defineDocs as b, buildPageTwitter as c, resolveOGImage as d, resolveTitle as f, createTheme as g, resolveDocsPath as h, resolveReadingTimeFromSource as i, renderDocsPageStructuredDataJson as l, resolveDocsLocale as m, resolvePageReadingTime as n, buildDocsPageStructuredData as o, resolveDocsI18n as p, resolveReadingTimeFromContent as r, buildPageOpenGraph as s, estimateReadingTimeMinutes as t, resolveDocsMetadataBaseUrl as u, deepMerge as v, resolveChangelogConfig as y };
+export { extendTheme as _, resolveReadingTimeOptions as a, defineDocs as b, buildPageTwitter as c, resolveOGImage as d, resolveTitle as f, createTheme as g, runDocsAgentConformance as h, resolveReadingTimeFromSource as i, renderDocsPageStructuredDataJson as l, createDocsAgentContractCases as m, resolvePageReadingTime as n, buildDocsPageStructuredData as o, DOCS_AGENT_CONTRACT_VERSION as p, resolveReadingTimeFromContent as r, buildPageOpenGraph as s, estimateReadingTimeMinutes as t, resolveDocsMetadataBaseUrl as u, deepMerge as v, resolveChangelogConfig as y };

package/dist/{review-lm3dt7yy.mjs → review-BEsbm0l2.mjs}

@@ -1,5 +1,6 @@
-import { a as ensureDocsReviewWorkflow, o as readDocsReviewConfigFromSource, s as resolveDocsReviewConfig } from "./review-B7goPYUb.mjs";
-import { f as readTopLevelStringProperty, i as loadDocsConfigModule, m as resolveDocsContentDir, p as resolveDocsConfigPath } from "./config-tiQCZ46q.mjs";
+import { a as normalizePageAgentFrontmatter, i as hasStructuredPageAgentContract, r as getPageAgentFrontmatterIssues } from "./agent-contract-b0akaPcg.mjs";
+import { a as ensureDocsReviewWorkflow, o as readDocsReviewConfigFromSource, s as resolveDocsReviewConfig } from "./review-BHdy75TE.mjs";
+import { f as readTopLevelStringProperty, i as loadDocsConfigModule, m as resolveDocsContentDir, p as resolveDocsConfigPath } from "./config-DhIyFsy9.mjs";
 import matter from "gray-matter";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
@@ -214,7 +215,8 @@ function collectReviewFindings(options) {
 			checkAgentContext(findings, options.review, {
 				file,
 				source,
-				rootDir: options.rootDir
+				rootDir: options.rootDir,
+				agent: parsed.data.agent
 			});
 		}
 		checkBrokenLinks(findings, options.review, {
@@ -294,6 +296,39 @@ function checkCodeFences(findings, review, options) {
 	}
 }
 function checkAgentContext(findings, review, options) {
+	for (const issue of getPageAgentFrontmatterIssues(options.agent)) pushFinding(findings, review, {
+		rule: "agentContext",
+		severity: "warn",
+		file: options.file,
+		line: 1,
+		message: `Invalid ${issue.path}: ${issue.message}${/[.!?]$/.test(issue.message) ? "" : "."}`
+	});
+	const agent = normalizePageAgentFrontmatter(options.agent);
+	if (hasStructuredPageAgentContract(agent)) {
+		const missing = [!agent?.task ? "task" : void 0, !agent?.outcome ? "outcome" : void 0].filter(Boolean).join(" and ");
+		if (missing) pushFinding(findings, review, {
+			rule: "agentContext",
+			severity: "suggestion",
+			file: options.file,
+			line: 1,
+			message: `Structured agent contract is missing ${missing}.`
+		});
+		if (agent?.commands?.length && !agent.verification?.length) pushFinding(findings, review, {
+			rule: "agentContext",
+			severity: "suggestion",
+			file: options.file,
+			line: 1,
+			message: "Structured agent contract defines commands without verification steps."
+		});
+		if (agent?.sideEffects?.length && !agent.rollback?.length) pushFinding(findings, review, {
+			rule: "agentContext",
+			severity: "suggestion",
+			file: options.file,
+			line: 1,
+			message: "Structured agent contract defines side effects without rollback guidance."
+		});
+		if (agent?.task && agent.outcome) return;
+	}
 	if (options.source.includes("<Agent>") || options.source.includes("</Agent>")) return;
 	if (existsSync(path.join(path.dirname(path.join(options.rootDir, options.file)), "agent.md"))) return;
 	if (!/\b(install|configure|setup|implement|defineDocs|docs\.config|MCP|agent)\b/i.test(options.source)) return;

package/dist/{robots-DV7u4Ire.mjs → robots-BOwkq9du.mjs}

@@ -1,7 +1,8 @@
-import "./agent-CaOBIVFy.mjs";
-import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-XVPs9lVz.mjs";
-import { f as readTopLevelStringProperty, i as loadDocsConfigModule, o as readBooleanProperty, p as resolveDocsConfigPath, t as extractNestedObjectLiteral, u as readStringProperty } from "./config-tiQCZ46q.mjs";
-import { t as detectFramework } from "./utils-D-xTRNuh.mjs";
+import "./agent-contract-b0akaPcg.mjs";
+import "./agent-BMxMpEa0.mjs";
+import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-C6uQG-fS.mjs";
+import { f as readTopLevelStringProperty, i as loadDocsConfigModule, o as readBooleanProperty, p as resolveDocsConfigPath, t as extractNestedObjectLiteral, u as readStringProperty } from "./config-DhIyFsy9.mjs";
+import { t as detectFramework } from "./utils-CMZTjRQT.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/{robots-XVPs9lVz.mjs → robots-C6uQG-fS.mjs}

@@ -1,4 +1,4 @@
-import { S as DEFAULT_MCP_WELL_KNOWN_ROUTE, T as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, X as normalizeDocsPathSegment, a as DEFAULT_AGENT_MD_ROUTE, b as DEFAULT_MCP_PUBLIC_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, kt as resolveDocsSitemapConfig, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-CaOBIVFy.mjs";
+import { Mt as resolveDocsSitemapConfig, Q as normalizeDocsPathSegment, S as DEFAULT_MCP_WELL_KNOWN_ROUTE, T as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, a as DEFAULT_AGENT_MD_ROUTE, b as DEFAULT_MCP_PUBLIC_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, w as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-BMxMpEa0.mjs";
 
 //#region src/robots.ts
 const DEFAULT_ROBOTS_TXT_ROUTE = "/robots.txt";