@farming-labs/docs 0.2.28 → 0.2.30

package/dist/cli/index.mjs

@@ -31,7 +31,8 @@ function parseFlags(argv) {
 		"network",
 		"analytics",
 		"ask-ai",
-		"deploy"
+		"deploy",
+		"dry-run"
 	]);
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
@@ -162,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();
@@ -228,22 +229,24 @@ async function main() {
 		printRobotsGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "downgrade") {
-		const { downgrade } = await import("../downgrade-D7zavP20.mjs");
+		const { downgrade } = await import("../downgrade-ghVFFHKi.mjs");
 		const framework = (typeof flags.framework === "string" ? flags.framework : void 0) ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0);
 		const hasVersionFlag = args.includes("--version") || args.some((arg) => arg.startsWith("--version="));
 		await downgrade({
 			framework,
-			version: typeof flags.version === "string" ? flags.version : hasVersionFlag ? "" : void 0
+			version: typeof flags.version === "string" ? flags.version : hasVersionFlag ? "" : void 0,
+			dryRun: flags["dry-run"] === true
 		});
 	} else if (parsedCommand.command === "upgrade") {
-		const { upgrade } = await import("../upgrade-Dzej61y4.mjs");
+		const { upgrade } = await import("../upgrade-aexO-zom.mjs");
 		const framework = (typeof flags.framework === "string" ? flags.framework : void 0) ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0);
 		const hasVersionFlag = args.includes("--version") || args.some((arg) => arg.startsWith("--version="));
 		const version = typeof flags.version === "string" ? flags.version : hasVersionFlag ? "" : void 0;
 		await upgrade({
 			framework,
 			tag: version !== void 0 ? void 0 : args.includes("--beta") ? "beta" : args.includes("--latest") ? "latest" : parsedCommand.tag ?? "latest",
-			version
+			version,
+			dryRun: flags["dry-run"] === true
 		});
 	} else if (parsedCommand.command === "--help" || parsedCommand.command === "-h") printHelp();
 	else if (parsedCommand.command === "--version" || parsedCommand.command === "-v") printVersion();
@@ -341,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
@@ -394,6 +399,7 @@ ${pc.dim("Options for upgrade:")}
   ${pc.cyan("--version <version>")} Install an exact version (e.g. ${pc.dim("0.1.104")})
   ${pc.cyan("--latest")}            Install latest stable (default)
   ${pc.cyan("--beta")}             Install beta versions
+  ${pc.cyan("--dry-run")}          Print the install command without changing dependencies
   ${pc.cyan("upgrade@beta")}       Shortcut for ${pc.cyan("upgrade --beta")}
   ${pc.cyan("upgrade@latest")}     Shortcut for ${pc.cyan("upgrade --latest")}
 
@@ -401,6 +407,7 @@ ${pc.dim("Options for downgrade:")}
   ${pc.cyan("downgrade")}           Install the published version immediately below the current installed version
   ${pc.cyan("--framework <name>")}  Explicit framework (${pc.dim("next")}, ${pc.dim("tanstack-start")}, ${pc.dim("nuxt")}, ${pc.dim("sveltekit")}, ${pc.dim("astro")}); omit to auto-detect
   ${pc.cyan("--version <version>")} Install an exact lower version (e.g. ${pc.dim("0.1.103")})
+  ${pc.cyan("--dry-run")}          Print the install command without changing dependencies
 
   ${pc.cyan("-h, --help")}         Show this help message
   ${pc.cyan("-v, --version")}     Show version

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/dist/{downgrade-D7zavP20.mjs → downgrade-ghVFFHKi.mjs}

@@ -165,6 +165,11 @@ async function downgrade(options = {}) {
 	const cmd = buildDowngradeCommand(framework, targetVersion, pm);
 	p.log.step(`Downgrading ${preset} docs packages from ${currentVersion} to ${targetVersion}...`);
 	p.log.message(pc.dim(packages.join(", ")));
+	if (options.dryRun) {
+		p.log.info("Dry run. Would run:\n  " + pc.cyan(cmd));
+		p.outro(pc.green("Dry run complete. No changes made."));
+		return;
+	}
 	try {
 		exec(cmd, cwd);
 		p.log.success(`Packages downgraded to ${targetVersion}.`);

package/dist/{upgrade-Dzej61y4.mjs → upgrade-aexO-zom.mjs}

@@ -37,6 +37,11 @@ async function upgrade(options = {}) {
 	const packages = getPackagesForFramework(framework);
 	p.log.step(`Upgrading ${preset} docs packages to ${target}...`);
 	p.log.message(pc.dim(packages.join(", ")));
+	if (options.dryRun) {
+		p.log.info("Dry run. Would run:\n  " + pc.cyan(cmd));
+		p.outro(pc.green("Dry run complete. No changes made."));
+		return;
+	}
 	try {
 		exec(cmd, cwd);
 		p.log.success(`Packages upgraded to ${target}.`);

package/package.json

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