@farming-labs/docs 0.2.29 → 0.2.30

package/dist/cli/index.mjs

@@ -163,7 +163,7 @@ async function main() {
 		printAgentsGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "doctor") {
-		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-Qe_2T86D.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-C_djsk99.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();
@@ -344,6 +344,8 @@ ${pc.dim("Options for doctor:")}
   ${pc.cyan("doctor --human")}                      Alias for ${pc.cyan("doctor --site")}
   ${pc.cyan("doctor --json")}                       Print the report as JSON for CI, scripts, and automation
   ${pc.cyan("doctor --strict")}                     Exit with failure when any doctor check warns or fails
+  ${pc.cyan("doctor --agent --fix")}                Refresh stale generated ${pc.dim("agent.md")} files and token-budget missing outputs
+  ${pc.cyan("doctor --agent --fix --dry-run")}      Report the fix command without writing generated ${pc.dim("agent.md")} files
   ${pc.cyan("doctor --fail-on warn|fail")}          Choose whether warnings or only failures fail CI
   ${pc.cyan("doctor agent")}                        Subcommand alias for agent scoring
   ${pc.cyan("doctor site")}                         Subcommand alias for reader-facing scoring

package/dist/{doctor-Qe_2T86D.mjs → doctor-C_djsk99.mjs}

@@ -7,7 +7,7 @@ import { createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "./mcp.mjs";
 import "./server.mjs";
 import { a as loadProjectEnv, c as readNavTitle, f as readTopLevelStringProperty, i as loadDocsConfigModule, m as resolveDocsContentDir, o as readBooleanProperty, p as resolveDocsConfigPath, r as extractTopLevelConfigObject, t as extractNestedObjectLiteral } from "./config-De5z-2LK.mjs";
 import { t as detectFramework } from "./utils-CoHZJ1i4.mjs";
-import { n as inspectAgentCompactionState, o as scanDocsPageTargets } from "./codeblocks-Dcn5tRbB.mjs";
+import { n as inspectAgentCompactionState, o as scanDocsPageTargets, t as compactAgentDocs } from "./codeblocks-Dcn5tRbB.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
@@ -66,6 +66,14 @@ function parseDoctorArgs(argv) {
 			parsed.strict = true;
 			continue;
 		}
+		if (arg === "--fix") {
+			parsed.fix = true;
+			continue;
+		}
+		if (arg === "--dry-run") {
+			parsed.dryRun = true;
+			continue;
+		}
 		if (arg.startsWith("--fail-on=")) {
 			const value = parseInlineFlag(arg).value;
 			if (!value) throw new Error("Missing value for --fail-on.");
@@ -137,6 +145,8 @@ ${pc.dim("Usage:")}
   pnpm exec docs doctor --site
   pnpm exec docs doctor --agent --json
   pnpm exec docs doctor --agent --strict
+  pnpm exec docs doctor --agent --fix
+  pnpm exec docs doctor --agent --fix --dry-run
   pnpm exec docs doctor --agent --fail-on fail
   pnpm exec docs doctor --only agent
   pnpm exec docs doctor --only site
@@ -150,6 +160,8 @@ ${pc.dim("Options:")}
   ${pc.cyan("--only <mode>")}      Run only one doctor suite: ${pc.cyan("agent")} or ${pc.cyan("site")}
   ${pc.cyan("--json")}             Print the report as JSON for CI, scripts, and other agents
   ${pc.cyan("--strict")}           Exit with failure when any check warns or fails
+  ${pc.cyan("--fix")}              Refresh stale generated agent.md files and token-budget missing outputs
+  ${pc.cyan("--dry-run")}          With ${pc.cyan("--fix")}, report the compaction command without writing files
   ${pc.cyan("--fail-on <level>")}  Exit with failure on ${pc.cyan("warn")} or only on ${pc.cyan("fail")}
   ${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]")}
@@ -1462,6 +1474,7 @@ function printAgentDoctorReport(report) {
 	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`);
+	if (report.fixes && report.fixes.length > 0) console.log(`${pc.bold("Fixes:")} ${report.fixes.map((fix) => `${fix.status === "applied" ? "applied" : "skipped"} ${fix.title}`).join(pc.dim(" • "))}`);
 	console.log();
 	for (const check of report.checks) {
 		console.log(`${formatStatus(check.status)} ${check.title} ${pc.dim(`(${check.score}/${check.maxScore})`)}`);
@@ -1513,8 +1526,58 @@ function applyDoctorExitCode(report, options) {
 	if (!failOn) return;
 	if (failOn === "warn" ? hasNonPassingDoctorCheck(report) : hasFailingDoctorCheck(report)) process.exitCode = 1;
 }
+async function runAgentDoctorFixes(report, options) {
+	const fixes = [];
+	const compaction = report.coverage.compaction;
+	if (!(compaction.staleGeneratedPages > 0 || compaction.tokenBudgetMissingPages > 0)) {
+		if (compaction.modifiedGeneratedPages > 0 || compaction.unknownGeneratedPages > 0) fixes.push({
+			id: "agent-compact",
+			title: "agent compact",
+			status: "skipped",
+			detail: "Only modified or unknown generated agent.md files need attention; doctor --fix leaves those for manual review."
+		});
+		return fixes;
+	}
+	const runCompaction = () => compactAgentDocs({
+		configPath: options.configPath,
+		stale: true,
+		includeMissing: compaction.tokenBudgetMissingPages > 0
+	});
+	const command = `docs agent compact --stale${compaction.tokenBudgetMissingPages > 0 ? " --include-missing" : ""}`;
+	if (options.dryRun) {
+		const missingOutputDetail = compaction.tokenBudgetMissingPages > 0 ? " and create token-budget missing outputs" : "";
+		fixes.push({
+			id: "agent-compact",
+			title: "agent compact",
+			status: "skipped",
+			detail: `Dry run: would run ${command} to refresh stale generated agent.md files${missingOutputDetail}.`
+		});
+		return fixes;
+	}
+	if (options.json) {
+		const originalLog = console.log;
+		console.log = () => void 0;
+		try {
+			await runCompaction();
+		} finally {
+			console.log = originalLog;
+		}
+	} else {
+		console.log();
+		console.log(pc.bold("Applying doctor --fix"));
+		await runCompaction();
+	}
+	fixes.push({
+		id: "agent-compact",
+		title: "agent compact",
+		status: "applied",
+		detail: compaction.tokenBudgetMissingPages > 0 ? "Ran docs agent compact --stale --include-missing to refresh stale generated agent.md files and create token-budget missing outputs." : "Ran docs agent compact --stale to refresh stale generated agent.md files."
+	});
+	return fixes;
+}
 async function runDoctor(options = {}) {
 	if (options.mode === "human") {
+		if (options.fix) throw new Error("doctor --fix is currently only supported with --agent.");
 		const report = await inspectHumanReadiness(options);
 		applyDoctorExitCode(report, options);
 		if (options.json) {
@@ -1524,7 +1587,15 @@ async function runDoctor(options = {}) {
 		printHumanDoctorReport(report);
 		return report;
 	}
-	const report = await inspectAgentReadiness(options);
+	let report = await inspectAgentReadiness(options);
+	let fixes;
+	if (options.fix) {
+		fixes = await runAgentDoctorFixes(report, options);
+		report = {
+			...await inspectAgentReadiness(options),
+			fixes
+		};
+	}
 	applyDoctorExitCode(report, options);
 	if (options.json) {
 		printDoctorJsonReport(report);

package/package.json

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