@farming-labs/docs 0.2.120 → 0.2.121

package/dist/agent-contract.d.mts

@@ -0,0 +1,47 @@
+import { PageAgentFrontmatter } from "./types.mjs";
+
+//#region src/agent-contract.d.ts
+interface PageAgentFrontmatterIssue {
+  path: string;
+  message: string;
+}
+declare const PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS: readonly ["task", "outcome", "appliesTo", "prerequisites", "files", "commands", "sideEffects", "verification", "rollback", "failureModes"];
+declare const PAGE_AGENT_CONTRACT_FIELDS: readonly ["tokenBudget", "access", "task", "outcome", "appliesTo", "prerequisites", "files", "commands", "sideEffects", "verification", "rollback", "failureModes"];
+declare const PAGE_AGENT_CONTRACT_FIELD_SCHEMA: {
+  readonly tokenBudget: "number";
+  readonly access: "{visibility?,scopes?,claims?}";
+  readonly task: "string";
+  readonly outcome: "string";
+  readonly appliesTo: {
+    readonly framework: "string|string[]";
+    readonly version: "string|string[]";
+    readonly package: "string|string[]";
+  };
+  readonly prerequisites: "string[]";
+  readonly files: "string[]";
+  readonly commands: "Array<string|{run,cwd?,description?}>";
+  readonly sideEffects: "string[]";
+  readonly verification: "Array<string|{description?,run?,expect?}>";
+  readonly rollback: "string[]";
+  readonly failureModes: "Array<string|{symptom,resolution?}>";
+};
+declare const PAGE_AGENT_CONTRACT_START_MARKER = "<!-- farming-labs:agent-contract:start -->";
+declare const PAGE_AGENT_CONTRACT_END_MARKER = "<!-- farming-labs:agent-contract:end -->";
+/**
+ * Normalize untrusted page frontmatter into the stable agent contract shape.
+ * Invalid fields are omitted so malformed author input cannot break page delivery.
+ */
+declare function normalizePageAgentFrontmatter(value: unknown): PageAgentFrontmatter | undefined;
+declare function hasStructuredPageAgentContract(value: unknown): boolean;
+/** Return author-facing validation issues without throwing. */
+declare function getPageAgentFrontmatterIssues(value: unknown): PageAgentFrontmatterIssue[];
+/** Render normalized `agent` YAML in a stable field order. */
+declare function renderPageAgentFrontmatterYamlLines(value: unknown, indentation?: number): string[];
+/** Render the structured contract as deterministic, compact machine-readable Markdown. */
+declare function renderPageAgentContractMarkdown(value: unknown): string;
+/** Remove generated contract blocks while preserving handwritten guidance. */
+declare function stripGeneratedPageAgentContractMarkdown(markdown: string): string;
+/** Insert one generated contract unless the document already has handwritten contract guidance. */
+declare function upsertPageAgentContractMarkdown(markdown: string, value: unknown): string;
+//#endregion
+export { PAGE_AGENT_CONTRACT_END_MARKER, PAGE_AGENT_CONTRACT_FIELDS, PAGE_AGENT_CONTRACT_FIELD_SCHEMA, PAGE_AGENT_CONTRACT_START_MARKER, PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS, PageAgentFrontmatterIssue, getPageAgentFrontmatterIssues, hasStructuredPageAgentContract, normalizePageAgentFrontmatter, renderPageAgentContractMarkdown, renderPageAgentFrontmatterYamlLines, stripGeneratedPageAgentContractMarkdown, upsertPageAgentContractMarkdown };

package/dist/agent-contract.mjs

@@ -0,0 +1,645 @@
+import { normalizeDocsPageAccessPolicy } from "./access.mjs";
+
+//#region src/agent-contract.ts
+const PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS = [
+	"task",
+	"outcome",
+	"appliesTo",
+	"prerequisites",
+	"files",
+	"commands",
+	"sideEffects",
+	"verification",
+	"rollback",
+	"failureModes"
+];
+const PAGE_AGENT_CONTRACT_FIELDS = [
+	"tokenBudget",
+	"access",
+	...PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS
+];
+const PAGE_AGENT_CONTRACT_FIELD_SCHEMA = {
+	tokenBudget: "number",
+	access: "{visibility?,scopes?,claims?}",
+	task: "string",
+	outcome: "string",
+	appliesTo: {
+		framework: "string|string[]",
+		version: "string|string[]",
+		package: "string|string[]"
+	},
+	prerequisites: "string[]",
+	files: "string[]",
+	commands: "Array<string|{run,cwd?,description?}>",
+	sideEffects: "string[]",
+	verification: "Array<string|{description?,run?,expect?}>",
+	rollback: "string[]",
+	failureModes: "Array<string|{symptom,resolution?}>"
+};
+const APPLIES_TO_FIELDS = [
+	"framework",
+	"version",
+	"package"
+];
+const COMMAND_FIELDS = [
+	"run",
+	"cwd",
+	"description"
+];
+const VERIFICATION_FIELDS = [
+	"description",
+	"run",
+	"expect"
+];
+const FAILURE_MODE_FIELDS = ["symptom", "resolution"];
+const ACCESS_FIELDS = [
+	"visibility",
+	"scopes",
+	"claims"
+];
+const PAGE_AGENT_CONTRACT_START_MARKER = "<!-- farming-labs:agent-contract:start -->";
+const PAGE_AGENT_CONTRACT_END_MARKER = "<!-- farming-labs:agent-contract:end -->";
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeString(value) {
+	if (typeof value !== "string") return void 0;
+	return value.trim() || void 0;
+}
+function normalizeStringList(value) {
+	if (!Array.isArray(value)) return void 0;
+	const seen = /* @__PURE__ */ new Set();
+	const normalized = [];
+	for (const item of value) {
+		const text = normalizeString(item);
+		if (!text || seen.has(text)) continue;
+		seen.add(text);
+		normalized.push(text);
+	}
+	return normalized.length > 0 ? normalized : void 0;
+}
+function normalizeStringOrList(value) {
+	const single = normalizeString(value);
+	if (single) return [single];
+	return normalizeStringList(value);
+}
+function normalizeAppliesTo(value) {
+	if (!isRecord(value)) return void 0;
+	const framework = normalizeStringOrList(value.framework);
+	const version = normalizeStringOrList(value.version);
+	const packageNames = normalizeStringOrList(value.package);
+	if (!framework && !version && !packageNames) return void 0;
+	return {
+		...framework ? { framework } : {},
+		...version ? { version } : {},
+		...packageNames ? { package: packageNames } : {}
+	};
+}
+function normalizeCommands(value) {
+	if (!Array.isArray(value)) return void 0;
+	const commands = [];
+	for (const item of value) {
+		const shorthand = normalizeString(item);
+		if (shorthand) {
+			commands.push(shorthand);
+			continue;
+		}
+		if (!isRecord(item)) continue;
+		const run = normalizeString(item.run);
+		if (!run) continue;
+		const cwd = normalizeString(item.cwd);
+		const description = normalizeString(item.description);
+		commands.push({
+			run,
+			...cwd ? { cwd } : {},
+			...description ? { description } : {}
+		});
+	}
+	return commands.length > 0 ? commands : void 0;
+}
+function normalizeVerification(value) {
+	if (!Array.isArray(value)) return void 0;
+	const verification = [];
+	for (const item of value) {
+		const shorthand = normalizeString(item);
+		if (shorthand) {
+			verification.push(shorthand);
+			continue;
+		}
+		if (!isRecord(item)) continue;
+		const description = normalizeString(item.description);
+		const run = normalizeString(item.run);
+		const expect = normalizeString(item.expect);
+		if (!description && !run && !expect) continue;
+		verification.push({
+			...description ? { description } : {},
+			...run ? { run } : {},
+			...expect ? { expect } : {}
+		});
+	}
+	return verification.length > 0 ? verification : void 0;
+}
+function normalizeFailureModes(value) {
+	if (!Array.isArray(value)) return void 0;
+	const failureModes = [];
+	for (const item of value) {
+		const shorthand = normalizeString(item);
+		if (shorthand) {
+			failureModes.push(shorthand);
+			continue;
+		}
+		if (!isRecord(item)) continue;
+		const symptom = normalizeString(item.symptom);
+		if (!symptom) continue;
+		const resolution = normalizeString(item.resolution);
+		failureModes.push({
+			symptom,
+			...resolution ? { resolution } : {}
+		});
+	}
+	return failureModes.length > 0 ? failureModes : void 0;
+}
+function normalizeTokenBudget(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return void 0;
+	return Math.ceil(value);
+}
+/**
+* Normalize untrusted page frontmatter into the stable agent contract shape.
+* Invalid fields are omitted so malformed author input cannot break page delivery.
+*/
+function normalizePageAgentFrontmatter(value) {
+	if (!isRecord(value)) return void 0;
+	const tokenBudget = normalizeTokenBudget(value.tokenBudget);
+	const access = "access" in value ? normalizeDocsPageAccessPolicy(value.access) ?? { visibility: "authenticated" } : void 0;
+	const task = normalizeString(value.task);
+	const outcome = normalizeString(value.outcome);
+	const appliesTo = normalizeAppliesTo(value.appliesTo);
+	const prerequisites = normalizeStringList(value.prerequisites);
+	const files = normalizeStringList(value.files);
+	const commands = normalizeCommands(value.commands);
+	const sideEffects = normalizeStringList(value.sideEffects);
+	const verification = normalizeVerification(value.verification);
+	const rollback = normalizeStringList(value.rollback);
+	const failureModes = normalizeFailureModes(value.failureModes);
+	const normalized = {
+		...tokenBudget !== void 0 ? { tokenBudget } : {},
+		...access ? { access } : {},
+		...task ? { task } : {},
+		...outcome ? { outcome } : {},
+		...appliesTo ? { appliesTo } : {},
+		...prerequisites ? { prerequisites } : {},
+		...files ? { files } : {},
+		...commands ? { commands } : {},
+		...sideEffects ? { sideEffects } : {},
+		...verification ? { verification } : {},
+		...rollback ? { rollback } : {},
+		...failureModes ? { failureModes } : {}
+	};
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+function hasStructuredPageAgentContract(value) {
+	const normalized = normalizePageAgentFrontmatter(value);
+	if (!normalized) return false;
+	return PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS.some((field) => normalized[field] !== void 0);
+}
+function addStringIssue(issues, object, field) {
+	if (!(field in object)) return;
+	if (!normalizeString(object[field])) issues.push({
+		path: `agent.${field}`,
+		message: "must be a non-empty string"
+	});
+}
+function addStringListIssues(issues, object, field) {
+	if (!(field in object)) return;
+	const value = object[field];
+	if (!Array.isArray(value) || value.length === 0) {
+		issues.push({
+			path: `agent.${field}`,
+			message: "must be a non-empty string array"
+		});
+		return;
+	}
+	value.forEach((item, index) => {
+		if (!normalizeString(item)) issues.push({
+			path: `agent.${field}[${index}]`,
+			message: "must be a non-empty string"
+		});
+	});
+}
+function editDistance(left, right) {
+	const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+		const current = [leftIndex];
+		for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) current[rightIndex] = Math.min((current[rightIndex - 1] ?? 0) + 1, (previous[rightIndex] ?? 0) + 1, (previous[rightIndex - 1] ?? 0) + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1));
+		previous.splice(0, previous.length, ...current);
+	}
+	return previous[right.length] ?? 0;
+}
+function closestKnownField(field, allowed) {
+	const closest = allowed.map((candidate) => ({
+		candidate,
+		distance: editDistance(field, candidate)
+	})).sort((left, right) => left.distance - right.distance || left.candidate.localeCompare(right.candidate))[0];
+	if (!closest) return void 0;
+	const threshold = Math.max(1, Math.min(3, Math.floor(closest.candidate.length / 3)));
+	return closest.distance <= threshold ? closest.candidate : void 0;
+}
+function addUnknownKeyIssues(issues, object, allowed, path) {
+	for (const field of Object.keys(object)) {
+		if (allowed.includes(field)) continue;
+		const suggestion = closestKnownField(field, allowed);
+		issues.push({
+			path: `${path}.${field}`,
+			message: suggestion ? `is not recognized; did you mean "${path}.${suggestion}"?` : "is not recognized"
+		});
+	}
+}
+/** Return author-facing validation issues without throwing. */
+function getPageAgentFrontmatterIssues(value) {
+	if (value === void 0) return [];
+	if (!isRecord(value)) return [{
+		path: "agent",
+		message: "must be an object"
+	}];
+	const issues = [];
+	addUnknownKeyIssues(issues, value, PAGE_AGENT_CONTRACT_FIELDS, "agent");
+	if ("tokenBudget" in value && (typeof value.tokenBudget !== "number" || !Number.isFinite(value.tokenBudget) || value.tokenBudget <= 0)) issues.push({
+		path: "agent.tokenBudget",
+		message: "must be a positive finite number"
+	});
+	if ("access" in value) if (!isRecord(value.access)) issues.push({
+		path: "agent.access",
+		message: "must be an object"
+	});
+	else {
+		addUnknownKeyIssues(issues, value.access, ACCESS_FIELDS, "agent.access");
+		if ("visibility" in value.access && value.access.visibility !== "public" && value.access.visibility !== "authenticated") issues.push({
+			path: "agent.access.visibility",
+			message: "must be \"public\" or \"authenticated\""
+		});
+		if ("scopes" in value.access && !normalizeStringList(value.access.scopes)) issues.push({
+			path: "agent.access.scopes",
+			message: "must be a non-empty string array"
+		});
+		if ("claims" in value.access) {
+			if (!isRecord(value.access.claims) || Object.keys(value.access.claims).length === 0) issues.push({
+				path: "agent.access.claims",
+				message: "must be a non-empty object"
+			});
+			else for (const [name, claim] of Object.entries(value.access.claims)) if (!name.trim() || normalizeDocsPageAccessPolicy({ claims: { [name]: claim } }) === void 0) issues.push({
+				path: `agent.access.claims.${name || "<empty>"}`,
+				message: "must be a string, number, boolean, or non-empty string array"
+			});
+		}
+		if (!normalizeDocsPageAccessPolicy(value.access)) issues.push({
+			path: "agent.access",
+			message: "must include a valid visibility, scope, or claim"
+		});
+	}
+	addStringIssue(issues, value, "task");
+	addStringIssue(issues, value, "outcome");
+	if ("appliesTo" in value) if (!isRecord(value.appliesTo)) issues.push({
+		path: "agent.appliesTo",
+		message: "must be an object"
+	});
+	else {
+		addUnknownKeyIssues(issues, value.appliesTo, APPLIES_TO_FIELDS, "agent.appliesTo");
+		for (const field of [
+			"framework",
+			"version",
+			"package"
+		]) {
+			if (!(field in value.appliesTo)) continue;
+			const fieldValue = value.appliesTo[field];
+			if (!normalizeStringOrList(fieldValue)) {
+				issues.push({
+					path: `agent.appliesTo.${field}`,
+					message: "must be a non-empty string or string array"
+				});
+				continue;
+			}
+			if (Array.isArray(fieldValue)) fieldValue.forEach((item, index) => {
+				if (!normalizeString(item)) issues.push({
+					path: `agent.appliesTo.${field}[${index}]`,
+					message: "must be a non-empty string"
+				});
+			});
+		}
+		if (!normalizeAppliesTo(value.appliesTo)) issues.push({
+			path: "agent.appliesTo",
+			message: "must include framework, version, or package"
+		});
+	}
+	for (const field of [
+		"prerequisites",
+		"files",
+		"sideEffects",
+		"rollback"
+	]) addStringListIssues(issues, value, field);
+	if ("commands" in value) if (!Array.isArray(value.commands) || value.commands.length === 0) issues.push({
+		path: "agent.commands",
+		message: "must be a non-empty array"
+	});
+	else value.commands.forEach((command, index) => {
+		if (normalizeString(command)) return;
+		if (!isRecord(command)) {
+			issues.push({
+				path: `agent.commands[${index}]`,
+				message: "must be a command string or an object with a non-empty run field"
+			});
+			return;
+		}
+		addUnknownKeyIssues(issues, command, COMMAND_FIELDS, `agent.commands[${index}]`);
+		if (!normalizeString(command.run)) {
+			issues.push({
+				path: `agent.commands[${index}]`,
+				message: "must be a command string or an object with a non-empty run field"
+			});
+			return;
+		}
+		for (const field of ["cwd", "description"]) if (field in command && !normalizeString(command[field])) issues.push({
+			path: `agent.commands[${index}].${field}`,
+			message: "must be a non-empty string"
+		});
+	});
+	if ("verification" in value) if (!Array.isArray(value.verification) || value.verification.length === 0) issues.push({
+		path: "agent.verification",
+		message: "must be a non-empty array"
+	});
+	else value.verification.forEach((step, index) => {
+		if (normalizeString(step)) return;
+		if (!isRecord(step)) {
+			issues.push({
+				path: `agent.verification[${index}]`,
+				message: "must be a string or an object with description, run, or expect"
+			});
+			return;
+		}
+		addUnknownKeyIssues(issues, step, VERIFICATION_FIELDS, `agent.verification[${index}]`);
+		if (!normalizeVerification([step])) {
+			issues.push({
+				path: `agent.verification[${index}]`,
+				message: "must be a string or an object with description, run, or expect"
+			});
+			return;
+		}
+		for (const field of [
+			"description",
+			"run",
+			"expect"
+		]) if (field in step && !normalizeString(step[field])) issues.push({
+			path: `agent.verification[${index}].${field}`,
+			message: "must be a non-empty string"
+		});
+	});
+	if ("failureModes" in value) if (!Array.isArray(value.failureModes) || value.failureModes.length === 0) issues.push({
+		path: "agent.failureModes",
+		message: "must be a non-empty array"
+	});
+	else value.failureModes.forEach((mode, index) => {
+		if (normalizeString(mode)) return;
+		if (!isRecord(mode)) {
+			issues.push({
+				path: `agent.failureModes[${index}]`,
+				message: "must be a string or an object with a non-empty symptom field"
+			});
+			return;
+		}
+		addUnknownKeyIssues(issues, mode, FAILURE_MODE_FIELDS, `agent.failureModes[${index}]`);
+		if (!normalizeString(mode.symptom)) {
+			issues.push({
+				path: `agent.failureModes[${index}]`,
+				message: "must be a string or an object with a non-empty symptom field"
+			});
+			return;
+		}
+		if ("resolution" in mode && !normalizeString(mode.resolution)) issues.push({
+			path: `agent.failureModes[${index}].resolution`,
+			message: "must be a non-empty string"
+		});
+	});
+	return issues;
+}
+function yamlString(value) {
+	return JSON.stringify(value);
+}
+function renderYamlStringList(lines, indent, key, values) {
+	lines.push(`${indent}${key}:`);
+	for (const value of values) lines.push(`${indent}  - ${yamlString(value)}`);
+}
+function renderYamlObjectList(lines, indent, key, values, fields) {
+	lines.push(`${indent}${key}:`);
+	for (const value of values) {
+		if (typeof value === "string") {
+			lines.push(`${indent}  - ${yamlString(value)}`);
+			continue;
+		}
+		const record = value;
+		const firstField = fields.find((field) => normalizeString(record[field]));
+		if (!firstField) continue;
+		lines.push(`${indent}  - ${firstField}: ${yamlString(normalizeString(record[firstField]))}`);
+		for (const field of fields) {
+			const fieldValue = normalizeString(record[field]);
+			if (field === firstField || !fieldValue) continue;
+			lines.push(`${indent}    ${field}: ${yamlString(fieldValue)}`);
+		}
+	}
+}
+/** Render normalized `agent` YAML in a stable field order. */
+function renderPageAgentFrontmatterYamlLines(value, indentation = 0) {
+	const agent = normalizePageAgentFrontmatter(value);
+	if (!agent) return [];
+	const indent = " ".repeat(Math.max(0, indentation));
+	const child = `${indent}  `;
+	const lines = [`${indent}agent:`];
+	if (agent.tokenBudget !== void 0) lines.push(`${child}tokenBudget: ${agent.tokenBudget}`);
+	if (agent.access) {
+		lines.push(`${child}access:`);
+		const accessIndent = `${child}  `;
+		if (agent.access.visibility) lines.push(`${accessIndent}visibility: ${agent.access.visibility}`);
+		if (agent.access.scopes) renderYamlStringList(lines, accessIndent, "scopes", [...agent.access.scopes]);
+		if (agent.access.claims) {
+			lines.push(`${accessIndent}claims:`);
+			const claimsIndent = `${accessIndent}  `;
+			for (const [name, claim] of Object.entries(agent.access.claims).sort(([left], [right]) => left.localeCompare(right))) if (Array.isArray(claim)) renderYamlStringList(lines, claimsIndent, yamlString(name), [...claim]);
+			else lines.push(`${claimsIndent}${yamlString(name)}: ${typeof claim === "string" ? yamlString(claim) : claim}`);
+		}
+	}
+	if (agent.task) lines.push(`${child}task: ${yamlString(agent.task)}`);
+	if (agent.outcome) lines.push(`${child}outcome: ${yamlString(agent.outcome)}`);
+	if (agent.appliesTo) {
+		lines.push(`${child}appliesTo:`);
+		const appliesIndent = `${child}  `;
+		for (const field of [
+			"framework",
+			"version",
+			"package"
+		]) {
+			const values = normalizeStringOrList(agent.appliesTo[field]);
+			if (values) renderYamlStringList(lines, appliesIndent, field, values);
+		}
+	}
+	if (agent.prerequisites) renderYamlStringList(lines, child, "prerequisites", agent.prerequisites);
+	if (agent.files) renderYamlStringList(lines, child, "files", agent.files);
+	if (agent.commands) renderYamlObjectList(lines, child, "commands", agent.commands, [
+		"run",
+		"cwd",
+		"description"
+	]);
+	if (agent.sideEffects) renderYamlStringList(lines, child, "sideEffects", agent.sideEffects);
+	if (agent.verification) renderYamlObjectList(lines, child, "verification", agent.verification, [
+		"description",
+		"run",
+		"expect"
+	]);
+	if (agent.rollback) renderYamlStringList(lines, child, "rollback", agent.rollback);
+	if (agent.failureModes) renderYamlObjectList(lines, child, "failureModes", agent.failureModes, ["symptom", "resolution"]);
+	return lines;
+}
+function inlineCode(value) {
+	const longestRun = Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length));
+	const fence = "`".repeat(longestRun + 1);
+	const padding = value.startsWith("`") || value.endsWith("`") ? " " : "";
+	return `${fence}${padding}${value}${padding}${fence}`;
+}
+function renderTextList(lines, title, values, code = false) {
+	lines.push("", `### ${title}`, "");
+	for (const value of values) lines.push(`- ${code ? inlineCode(value) : value}`);
+}
+/** Render the structured contract as deterministic, compact machine-readable Markdown. */
+function renderPageAgentContractMarkdown(value) {
+	const agent = normalizePageAgentFrontmatter(value);
+	if (!agent || !hasStructuredPageAgentContract(agent)) return "";
+	const lines = [PAGE_AGENT_CONTRACT_START_MARKER, "## Agent Contract"];
+	if (agent.task) lines.push("", `Task: ${agent.task}`);
+	if (agent.outcome) lines.push(`Outcome: ${agent.outcome}`);
+	if (agent.appliesTo) {
+		lines.push("", "### Applies To", "");
+		for (const [label, field] of [
+			["Framework", "framework"],
+			["Version", "version"],
+			["Package", "package"]
+		]) {
+			const values = normalizeStringOrList(agent.appliesTo[field]);
+			if (values) lines.push(`- ${label}: ${values.map(inlineCode).join(", ")}`);
+		}
+	}
+	if (agent.prerequisites) renderTextList(lines, "Prerequisites", agent.prerequisites);
+	if (agent.files) renderTextList(lines, "Files", agent.files, true);
+	if (agent.commands) {
+		lines.push("", "### Commands", "");
+		for (const command of agent.commands) {
+			if (typeof command === "string") {
+				lines.push(`- ${inlineCode(command)}`);
+				continue;
+			}
+			const details = [command.cwd ? `cwd ${inlineCode(command.cwd)}` : void 0, command.description].filter(Boolean);
+			lines.push(`- ${inlineCode(command.run)}${details.length ? ` — ${details.join("; ")}` : ""}`);
+		}
+	}
+	if (agent.sideEffects) renderTextList(lines, "Side Effects", agent.sideEffects);
+	if (agent.verification) {
+		lines.push("", "### Verification", "");
+		for (const step of agent.verification) {
+			if (typeof step === "string") {
+				lines.push(`- ${step}`);
+				continue;
+			}
+			const summary = step.description ?? (step.run ? `Run ${inlineCode(step.run)}` : step.expect ?? "Verification step");
+			lines.push(`- ${summary}`);
+			if (step.run && step.description) lines.push(`  - Run: ${inlineCode(step.run)}`);
+			if (step.expect && step.expect !== summary) lines.push(`  - Expected: ${step.expect}`);
+		}
+	}
+	if (agent.rollback) renderTextList(lines, "Rollback", agent.rollback);
+	if (agent.failureModes) {
+		lines.push("", "### Failure Modes", "");
+		for (const mode of agent.failureModes) {
+			if (typeof mode === "string") {
+				lines.push(`- ${mode}`);
+				continue;
+			}
+			lines.push(`- ${mode.symptom}${mode.resolution ? ` — Recovery: ${mode.resolution}` : ""}`);
+		}
+	}
+	lines.push(PAGE_AGENT_CONTRACT_END_MARKER);
+	return lines.join("\n");
+}
+/** Remove generated contract blocks while preserving handwritten guidance. */
+function stripGeneratedPageAgentContractMarkdown(markdown) {
+	const newline = markdown.includes("\r\n") ? "\r\n" : "\n";
+	const output = [];
+	let fence;
+	let pendingBlock;
+	let skipEmptySeparator = false;
+	for (const line of markdown.split(/\r?\n/)) {
+		if (pendingBlock) {
+			pendingBlock.push(line);
+			if (isGeneratedAgentContractMarker(line, PAGE_AGENT_CONTRACT_END_MARKER)) {
+				pendingBlock = void 0;
+				skipEmptySeparator = true;
+			}
+			continue;
+		}
+		if (!fence && isGeneratedAgentContractMarker(line, PAGE_AGENT_CONTRACT_START_MARKER)) {
+			pendingBlock = [line];
+			continue;
+		}
+		if (skipEmptySeparator && line.length === 0) continue;
+		skipEmptySeparator = false;
+		output.push(line);
+		fence = advanceMarkdownFence(line, fence);
+	}
+	if (pendingBlock) output.push(...pendingBlock);
+	while (output[0] === "") output.shift();
+	return output.join(newline);
+}
+function isGeneratedAgentContractMarker(line, marker) {
+	if (line.trim() !== marker) return false;
+	const markerIndex = line.indexOf(marker);
+	return markerIndex <= 3 && /^ *$/.test(line.slice(0, markerIndex));
+}
+function advanceMarkdownFence(line, fence) {
+	if (fence) {
+		const closing = /^ {0,3}(`+|~+)[\t ]*$/.exec(line)?.[1];
+		if (closing?.[0] === fence.character && closing.length >= fence.length) return;
+		return fence;
+	}
+	const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+	if (!opening?.[1]) return void 0;
+	if (opening[1][0] === "`" && opening[2]?.includes("`")) return void 0;
+	return {
+		character: opening[1][0],
+		length: opening[1].length
+	};
+}
+function isAgentContractHeadingText(value) {
+	return value.trim().toLowerCase() === "agent contract";
+}
+function hasPageAgentContractHeading(markdown) {
+	let fence;
+	let previousLine;
+	for (const line of markdown.split(/\r?\n/)) {
+		const nextFence = advanceMarkdownFence(line, fence);
+		if (fence || nextFence) {
+			fence = nextFence;
+			previousLine = void 0;
+			continue;
+		}
+		const atxText = /^ {0,3}#{1,6}(?:[\t ]+|$)(.*)$/.exec(line)?.[1]?.replace(/[\t ]+#+[\t ]*$/, "").trim();
+		if (atxText && isAgentContractHeadingText(atxText)) return true;
+		if (previousLine && /^ {0,3}(?:=+|-+)[\t ]*$/.test(line) && isAgentContractHeadingText(previousLine)) return true;
+		previousLine = line.trim().length > 0 && !/^ {4}/.test(line) && !/^ {0,3}\t/.test(line) ? line : void 0;
+	}
+	return false;
+}
+/** Insert one generated contract unless the document already has handwritten contract guidance. */
+function upsertPageAgentContractMarkdown(markdown, value) {
+	const cleaned = stripGeneratedPageAgentContractMarkdown(markdown);
+	const contract = renderPageAgentContractMarkdown(value);
+	if (!contract || hasPageAgentContractHeading(cleaned)) return cleaned;
+	return cleaned ? `${contract}\n\n${cleaned.replace(/^\r?\n+/, "")}` : contract;
+}
+
+//#endregion
+export { PAGE_AGENT_CONTRACT_END_MARKER, PAGE_AGENT_CONTRACT_FIELDS, PAGE_AGENT_CONTRACT_FIELD_SCHEMA, PAGE_AGENT_CONTRACT_START_MARKER, PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS, getPageAgentFrontmatterIssues, hasStructuredPageAgentContract, normalizePageAgentFrontmatter, renderPageAgentContractMarkdown, renderPageAgentFrontmatterYamlLines, stripGeneratedPageAgentContractMarkdown, upsertPageAgentContractMarkdown };

package/dist/agent-detection.d.mts

@@ -0,0 +1,6 @@
+//#region src/agent-detection.d.ts
+declare const DOCS_AI_AGENT_USER_AGENT_HEADER_PATTERN: string;
+declare const DOCS_TRADITIONAL_BOT_USER_AGENT_HEADER_PATTERN: string;
+declare const DOCS_BOT_LIKE_USER_AGENT_HEADER_PATTERN: string;
+//#endregion
+export { DOCS_AI_AGENT_USER_AGENT_HEADER_PATTERN, DOCS_BOT_LIKE_USER_AGENT_HEADER_PATTERN, DOCS_TRADITIONAL_BOT_USER_AGENT_HEADER_PATTERN };