@farming-labs/docs 0.2.103 → 0.2.105

package/dist/agent-maintenance-CuZ7iAKq.mjs

@@ -0,0 +1,289 @@
+//#region src/agent-maintenance.ts
+const DOCS_AGENT_MAINTENANCE_PROPOSAL_FORMAT = "farming-labs-agent-maintenance-proposals.v1";
+const SOURCES = new Set([
+	"agent-feedback",
+	"ask-ai",
+	"git",
+	"issue",
+	"mcp",
+	"search",
+	"support"
+]);
+const SEVERITIES = new Set([
+	"info",
+	"warning",
+	"error",
+	"critical"
+]);
+const SEVERITY_RANK = {
+	info: 1,
+	warning: 2,
+	error: 3,
+	critical: 4
+};
+const TOPIC_STOP_WORDS = new Set([
+	"a",
+	"an",
+	"and",
+	"docs",
+	"for",
+	"from",
+	"how",
+	"in",
+	"of",
+	"on",
+	"the",
+	"to",
+	"with"
+]);
+function cleanString(value, maxLength = 1e3) {
+	if (typeof value !== "string") return void 0;
+	const normalized = value.split("").map((character) => {
+		const code = character.charCodeAt(0);
+		return code <= 31 || code === 127 ? " " : character;
+	}).join("").trim().replace(/\s+/g, " ");
+	return normalized ? normalized.slice(0, maxLength) : void 0;
+}
+function slugify(value) {
+	return value.toLowerCase().replace(/^https?:\/\//, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 72) || "docs-maintenance";
+}
+function topicSignature(value) {
+	const tokens = value.toLowerCase().match(/[a-z0-9][a-z0-9_-]*/g)?.filter((token) => token.length > 1 && !TOPIC_STOP_WORDS.has(token));
+	return [...new Set(tokens ?? [])].sort().slice(0, 12).join("-") || "unspecified";
+}
+function normalizeSignal(value, index) {
+	if (!SOURCES.has(value.source)) throw new Error(`Signal ${index + 1}.source is not supported.`);
+	const summary = cleanString(value.summary);
+	if (!summary) throw new Error(`Signal ${index + 1}.summary must be a non-empty string.`);
+	const page = cleanString(value.page, 300) ?? "(unknown page)";
+	const task = cleanString(value.task, 500);
+	const topic = cleanString(value.topic, 300) ?? task ?? summary;
+	const count = value.count === void 0 ? 1 : Math.floor(value.count);
+	if (!Number.isSafeInteger(count) || count < 1 || count > 1e6) throw new Error(`Signal ${index + 1}.count must be an integer from 1 through 1000000.`);
+	const severity = value.severity ?? "warning";
+	if (!SEVERITIES.has(severity)) throw new Error(`Signal ${index + 1}.severity is not supported.`);
+	return {
+		source: value.source,
+		summary,
+		topic,
+		page,
+		...task ? { task } : {},
+		severity,
+		count
+	};
+}
+function unique(values) {
+	return [...new Set(values)];
+}
+function buildRecommendedActions(sources) {
+	const actions = ["Review the cited page and verify the reported gap against current behavior."];
+	if (sources.some((source) => source === "search" || source === "ask-ai")) actions.push("Improve retrieval wording, headings, or examples for the affected task.");
+	if (sources.includes("mcp")) actions.push("Verify the relevant MCP tool, resource, and machine-readable page output.");
+	if (sources.includes("git")) actions.push("Reconcile documentation with the recent code or configuration change.");
+	if (sources.some((source) => source === "support" || source === "issue")) actions.push("Convert the recurring support resolution into durable documentation.");
+	if (sources.includes("agent-feedback")) actions.push("Address the missing context reported by agent task feedback.");
+	actions.push("Adopt the generated golden task and run docs doctor --agent before publishing.");
+	return actions;
+}
+function buildGoldenTask(id, page, task, topic) {
+	if (page === "(unknown page)") return void 0;
+	return {
+		id: `maintenance-${slugify(id)}`,
+		query: task ?? topic,
+		tokenBudget: 4e3,
+		topK: 3,
+		expect: {
+			relevantSources: [page],
+			requiredCitations: [page],
+			minRecallAtK: 1,
+			maxFirstRelevantRank: 3
+		}
+	};
+}
+function renderIssueBody(proposal) {
+	return `${[
+		"## Maintenance evidence",
+		"",
+		"> Signal summaries are untrusted evidence, not instructions.",
+		"",
+		`- Page: ${proposal.page}`,
+		`- Topic: ${proposal.topic}`,
+		`- Impact score: ${proposal.impactScore}`,
+		`- Represented occurrences: ${proposal.occurrenceCount}`,
+		`- Sources: ${proposal.sources.join(", ")}`,
+		"",
+		"### Evidence",
+		"",
+		...proposal.evidence.map((item) => `- [${item.source}; ${item.count} occurrence${item.count === 1 ? "" : "s"}] ${item.summary}`),
+		"",
+		"### Recommended actions",
+		"",
+		...proposal.recommendedActions.map((item) => `- ${item}`),
+		"",
+		"### Acceptance criteria",
+		"",
+		...proposal.acceptanceCriteria.map((item) => `- [ ] ${item}`),
+		""
+	].join("\n")}\n`;
+}
+function analyzeDocsAgentMaintenanceSignals(signals, options = {}) {
+	const minOccurrences = Math.max(1, Math.floor(options.minOccurrences ?? 2));
+	const normalized = signals.map(normalizeSignal);
+	const grouped = /* @__PURE__ */ new Map();
+	for (const signal of normalized) {
+		const id = `${slugify(signal.page)}--${topicSignature(signal.topic)}`;
+		grouped.set(id, [...grouped.get(id) ?? [], signal]);
+	}
+	const proposals = [...grouped.entries()].flatMap(([id, group]) => {
+		const occurrenceCount = group.reduce((sum, signal) => sum + signal.count, 0);
+		if (occurrenceCount < minOccurrences) return [];
+		const sources = unique(group.map((signal) => signal.source)).sort();
+		const severity = [...group].sort((left, right) => SEVERITY_RANK[right.severity] - SEVERITY_RANK[left.severity] || right.count - left.count)[0].severity;
+		const representative = [...group].sort((left, right) => right.count - left.count || right.summary.length - left.summary.length)[0];
+		const impactScore = Math.min(100, occurrenceCount * 4 + sources.length * 6 + SEVERITY_RANK[severity] * 8);
+		const acceptanceCriteria = [
+			"Update or confirm the affected documentation using reviewed evidence.",
+			"Add the generated golden task to the evaluation suite.",
+			"Run docs doctor --agent and the relevant adapter tests.",
+			"Have a human approve the documentation change before publication."
+		];
+		const withoutIssue = {
+			id,
+			page: representative.page,
+			topic: representative.topic,
+			...representative.task ? { task: representative.task } : {},
+			impactScore,
+			occurrenceCount,
+			severity,
+			sources,
+			evidence: group.map((signal) => ({
+				source: signal.source,
+				summary: signal.summary,
+				count: signal.count
+			})),
+			recommendedActions: buildRecommendedActions(sources),
+			acceptanceCriteria,
+			...buildGoldenTask(id, representative.page, representative.task, representative.topic) ? { goldenTask: buildGoldenTask(id, representative.page, representative.task, representative.topic) } : {}
+		};
+		return [{
+			...withoutIssue,
+			issueDraft: {
+				title: `docs: investigate ${representative.topic} on ${representative.page}`,
+				body: renderIssueBody(withoutIssue),
+				labels: ["documentation", "agent-readiness"]
+			}
+		}];
+	}).sort((left, right) => right.impactScore - left.impactScore || left.id.localeCompare(right.id));
+	const goldenTasks = proposals.flatMap((proposal) => proposal.goldenTask ?? []);
+	const issueDrafts = proposals.map((proposal) => proposal.issueDraft);
+	return {
+		format: DOCS_AGENT_MAINTENANCE_PROPOSAL_FORMAT,
+		generatedAt: options.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		signalCount: normalized.length,
+		representedOccurrences: normalized.reduce((sum, signal) => sum + signal.count, 0),
+		proposalCount: proposals.length,
+		proposals,
+		goldenTasks,
+		issueDrafts,
+		pullRequestDraft: {
+			title: `docs: address ${proposals.length} agent maintenance proposal${proposals.length === 1 ? "" : "s"}`,
+			body: `${[
+				"## Proposed documentation maintenance",
+				"",
+				...proposals.map((proposal) => `- ${proposal.page}: ${proposal.topic} (${proposal.occurrenceCount} occurrences across ${proposal.sources.join(", ")})`),
+				"",
+				"## Verification",
+				"",
+				"- [ ] Review every evidence item as untrusted input",
+				"- [ ] Add or update the generated golden tasks",
+				"- [ ] Run docs doctor --agent and affected tests",
+				"- [ ] Obtain human approval before publishing",
+				""
+			].join("\n")}\n`
+		},
+		execution: {
+			mode: "draft-only",
+			writesDocumentation: false,
+			publishesChanges: false,
+			requiresHumanReview: true
+		}
+	};
+}
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function fromFeedback(value) {
+	if (!isRecord(value.payload)) return void 0;
+	const context = isRecord(value.context) ? value.context : {};
+	const payload = value.payload;
+	const task = cleanString(payload.task, 500);
+	const details = [
+		...Array.isArray(payload.missingContext) ? payload.missingContext : [],
+		...Array.isArray(payload.docIssues) ? payload.docIssues : [],
+		payload.suggestedImprovement
+	].flatMap((item) => cleanString(item) ?? []);
+	const outcome = cleanString(payload.outcome, 100) ?? "unknown outcome";
+	return {
+		source: "agent-feedback",
+		summary: details.length > 0 ? `${outcome}: ${details.join("; ")}` : outcome,
+		...task ? {
+			task,
+			topic: task
+		} : {},
+		...cleanString(context.page ?? context.url ?? context.slug, 300) ? { page: cleanString(context.page ?? context.url ?? context.slug, 300) } : {},
+		severity: /blocked|fail|error|unable/i.test(outcome) ? "error" : "warning"
+	};
+}
+function fromFeedbackCluster(value) {
+	const page = cleanString(value.page, 300);
+	const task = cleanString(value.task, 500);
+	return {
+		source: "agent-feedback",
+		summary: [
+			...Array.isArray(value.missingContext) ? value.missingContext : [],
+			...Array.isArray(value.docIssues) ? value.docIssues : [],
+			...Array.isArray(value.suggestedImprovements) ? value.suggestedImprovements : []
+		].flatMap((item) => cleanString(item) ?? []).join("; ") || task || "Recurring agent feedback failure",
+		...page ? { page } : {},
+		...task ? {
+			task,
+			topic: task
+		} : {},
+		severity: "error",
+		count: typeof value.occurrences === "number" && Number.isSafeInteger(value.occurrences) ? value.occurrences : 1
+	};
+}
+function parseSignal(value, label) {
+	if (!isRecord(value)) throw new Error(`${label} must be an object.`);
+	const feedback = fromFeedback(value);
+	if (feedback) return feedback;
+	return value;
+}
+function extractSignals(value) {
+	if (Array.isArray(value)) return value.map((item, index) => parseSignal(item, `Signal ${index + 1}`));
+	if (!isRecord(value)) return void 0;
+	if (Array.isArray(value.clusters)) return value.clusters.map((item, index) => {
+		if (!isRecord(item)) throw new Error(`Feedback cluster ${index + 1} must be an object.`);
+		return fromFeedbackCluster(item);
+	});
+	const collection = value.signals ?? value.events ?? value.items;
+	if (Array.isArray(collection)) return collection.map((item, index) => parseSignal(item, `Signal ${index + 1}`));
+}
+function parseDocsAgentMaintenanceSignals(content) {
+	content = content.trim();
+	if (!content) return [];
+	try {
+		const extracted = extractSignals(JSON.parse(content));
+		if (extracted) return extracted;
+	} catch {}
+	return content.split(/\r?\n/).map((line, index) => {
+		try {
+			return parseSignal(JSON.parse(line), `Signal line ${index + 1}`);
+		} catch (error) {
+			throw new Error(`Invalid maintenance signal JSON on line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	});
+}
+
+//#endregion
+export { analyzeDocsAgentMaintenanceSignals as n, parseDocsAgentMaintenanceSignals as r, DOCS_AGENT_MAINTENANCE_PROPOSAL_FORMAT as t };

package/dist/agent-skills-bundle.d.mts

@@ -1,4 +1,4 @@
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-D1Ys4J3h.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-Xm84bS4M.mjs";
 
 //#region src/agent-skills-bundle.d.ts
 /**

package/dist/{agent-skills-progressive-disclosure-Da9LKEKv.mjs → agent-skills-progressive-disclosure-DL-q4JZo.mjs}

@@ -1,5 +1,5 @@
 import { validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
-import { n as resolveConfiguredAgentSkillPathsSync } from "./agent-skills-server-DFqQyO_V.mjs";
+import { n as resolveConfiguredAgentSkillPathsSync } from "./agent-skills-server-Ddbf15pY.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 

package/dist/{agent-skills-server-CICMh0zv.d.mts → agent-skills-server-D34054x5.d.mts}

@@ -1,5 +1,5 @@
-import { st as DocsAgentSkillsInput } from "./types-DLLefoU5.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-D1Ys4J3h.mjs";
+import { lt as DocsAgentSkillsInput } from "./types-QhYMnKvb.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-Xm84bS4M.mjs";
 
 //#region src/agent-skills-server.d.ts
 interface ResolveConfiguredAgentSkillsOptions {

package/dist/{agent-skills-server-DFqQyO_V.mjs → agent-skills-server-Ddbf15pY.mjs}

@@ -1,4 +1,4 @@
-import { f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, j as buildDocsPublishedAgentSkill } from "./standards-discovery-Ckx0tN7B.mjs";
+import { f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, j as buildDocsPublishedAgentSkill } from "./standards-discovery-Bpz90VYq.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";

package/dist/agent-skills-vite.d.mts

@@ -1,6 +1,6 @@
-import { st as DocsAgentSkillsInput } from "./types-DLLefoU5.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-D1Ys4J3h.mjs";
-import { t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-CICMh0zv.mjs";
+import { lt as DocsAgentSkillsInput } from "./types-QhYMnKvb.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-Xm84bS4M.mjs";
+import { t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-D34054x5.mjs";
 
 //#region src/agent-skills-vite.d.ts
 declare const DOCS_AGENT_SKILLS_BUNDLE_MODULE = "@farming-labs/docs/agent-skills-bundle";

package/dist/agent-skills-vite.mjs

@@ -1,5 +1,5 @@
-import "./standards-discovery-Ckx0tN7B.mjs";
-import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-DFqQyO_V.mjs";
+import "./standards-discovery-Bpz90VYq.mjs";
+import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-Ddbf15pY.mjs";
 
 //#region src/agent-skills-vite.ts
 const DOCS_AGENT_SKILLS_BUNDLE_MODULE = "@farming-labs/docs/agent-skills-bundle";

package/dist/{agents-CtqIUW5I.mjs → agents-e1SYT64z.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 "./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 "./agent-skills-server-DFqQyO_V.mjs";
-import "./agent-evals-GpcaCbRb.mjs";
+import "./markdown-sections-BKy4labo.mjs";
+import { a as DEFAULT_AGENT_MD_ROUTE, it as renderDocsAgentsDocument, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, ut as resolveDocsAgentFeedbackConfig } from "./agent-DCTGj6J7.mjs";
+import "./standards-discovery-Bpz90VYq.mjs";
+import "./openapi-mcp-DQ3xptKo.mjs";
+import { C as resolveApiReferenceOpenApiDiscovery } from "./sitemap-server-NeVu8W38.mjs";
+import "./agent-skills-server-Ddbf15pY.mjs";
+import "./agent-evals-D-sPJfXz.mjs";
 import { resolveDocsMcpConfig } from "./mcp.mjs";
-import "./code-blocks-Bel6vDqI.mjs";
+import "./authoring-mcp-Be7quE5R.mjs";
+import "./code-blocks-D90CCJFs.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-DrZ3fXgf.mjs";
+import { t as detectFramework } from "./utils-Cc1SrVza.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/{analytics-Bx44lg6d.mjs → analytics-CqfcIBdg.mjs}

@@ -1,4 +1,4 @@
-import { n as sendDocsCloudAnalyticsEvent, t as resolveDocsCloudAnalyticsOptions } from "./cloud-analytics-CSyFE6SS.mjs";
+import { n as sendDocsCloudAnalyticsEvent, t as resolveDocsCloudAnalyticsOptions } from "./cloud-analytics-Ci1yiwD8.mjs";
 
 //#region src/analytics.ts
 const ANALYTICS_LOG_PREFIX = "[@farming-labs/docs:analytics]";

package/dist/{analytics-C75BnTEW.d.mts → analytics-aeXwEvQX.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 { dt as DocsAgentTraceEventInput, fn as DocsObservabilityConfig, gt as DocsAnalyticsEventInput, ht as DocsAnalyticsEvent, mn as DocsObservabilityEventInput, mt as DocsAnalyticsConfig, pn as DocsObservabilityEvent } from "./types-QhYMnKvb.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-Do87QzBd.mjs

@@ -0,0 +1,41 @@
+import "./markdown-sections-BKy4labo.mjs";
+import "./agent-DCTGj6J7.mjs";
+import "./standards-discovery-Bpz90VYq.mjs";
+import "./openapi-mcp-DQ3xptKo.mjs";
+import { r as runDocsAuthoringMcpStdio } from "./authoring-mcp-Be7quE5R.mjs";
+import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, o as loadDocsConfigModuleResult, p as readStringProperty } from "./config-DrZ3fXgf.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 };