@farming-labs/docs 0.2.63 → 0.2.64

package/dist/cli/index.mjs

@@ -180,7 +180,7 @@ async function main() {
 		printAgentsGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "doctor") {
-		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-CJqtzKZT.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-DtGYZ41i.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();
@@ -188,7 +188,7 @@ async function main() {
 		}
 		await runDoctor(doctorOptions);
 	} else if (parsedCommand.command === "review") {
-		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-Fndl5brR.mjs");
+		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-CLoHTywU.mjs");
 		const reviewOptions = parseReviewArgs(args.slice(1));
 		if (reviewOptions.help) {
 			printReviewHelp();

package/dist/{doctor-CJqtzKZT.mjs → doctor-DtGYZ41i.mjs}

@@ -13,7 +13,7 @@ import "./agent-skills-server-DraIb6FV.mjs";
 import "./server.mjs";
 import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, r as extractTopLevelConfigObject, s as loadDocsConfigModuleResultWithProjectEnv, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
 import { t as detectFramework } from "./utils-DpiIioYb.mjs";
-import { i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-Dsvh0etV.mjs";
+import { i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-Dj-9Eo3v.mjs";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";

package/dist/{golden-evaluations-Dsvh0etV.mjs → golden-evaluations-Dj-9Eo3v.mjs}

@@ -210,6 +210,94 @@ const PACKAGE_MANAGER_OPTIONS_WITH_VALUES = new Set([
 	"-F",
 	"-w"
 ]);
+const CURL_OPTIONS_WITH_VALUES = new Set([
+	"--cacert",
+	"--cert",
+	"--connect-timeout",
+	"--data",
+	"--data-ascii",
+	"--data-binary",
+	"--data-raw",
+	"--data-urlencode",
+	"--form",
+	"--header",
+	"--json",
+	"--key",
+	"--max-time",
+	"--output",
+	"--request",
+	"--resolve",
+	"--retry",
+	"--retry-delay",
+	"--url",
+	"--user",
+	"--user-agent"
+]);
+const CURL_OPTIONS_WITHOUT_VALUES = new Set([
+	"--compressed",
+	"--fail",
+	"--fail-with-body",
+	"--head",
+	"--include",
+	"--insecure",
+	"--location",
+	"--show-error",
+	"--silent",
+	"--verbose"
+]);
+const CURL_SHORT_OPTIONS_WITH_VALUES = new Set([
+	"A",
+	"d",
+	"F",
+	"H",
+	"o",
+	"u",
+	"X"
+]);
+const CURL_SHORT_OPTIONS_WITHOUT_VALUES = new Set([
+	"f",
+	"I",
+	"i",
+	"k",
+	"L",
+	"s",
+	"S",
+	"v"
+]);
+const TEST_UNARY_OPERATORS = new Set([
+	"-b",
+	"-c",
+	"-d",
+	"-e",
+	"-f",
+	"-g",
+	"-h",
+	"-L",
+	"-n",
+	"-p",
+	"-r",
+	"-S",
+	"-s",
+	"-t",
+	"-u",
+	"-w",
+	"-x",
+	"-z"
+]);
+const TEST_BINARY_OPERATORS = new Set([
+	"=",
+	"==",
+	"!=",
+	"-ef",
+	"-eq",
+	"-ge",
+	"-gt",
+	"-le",
+	"-lt",
+	"-ne",
+	"-nt",
+	"-ot"
+]);
 function isAgentContextVisible(scopes) {
 	return scopes.every((scope) => scope.only === void 0 || scope.only === "agent");
 }
@@ -274,7 +362,8 @@ function analyzeAgentUsefulness(options) {
 	const rootDir = path.resolve(options.rootDir);
 	const packageManager = options.packageManager ?? detectPackageManager(rootDir);
 	const knownDocsCommands = new Set([...DEFAULT_DOCS_COMMANDS, ...options.knownDocsCommands ?? []]);
-	const packageManifests = readProjectPackageManifests(rootDir);
+	const workspaceRoot = findEnclosingWorkspaceRoot(rootDir);
+	const packageManifests = readProjectPackageManifests(workspaceRoot);
 	const pages = options.pages.map((page) => analyzePage(page));
 	const findings = [];
 	const unhealthyCommandKeys = /* @__PURE__ */ new Set();
@@ -345,7 +434,8 @@ function analyzeAgentUsefulness(options) {
 				rootDir,
 				packageManager,
 				knownDocsCommands,
-				packageManifests
+				packageManifests,
+				workspaceRoot
 			});
 			if (commandAnalysis.status === "unhealthy") unhealthyCommandKeys.add(commandKey);
 			if (commandAnalysis.status === "unverified") unverifiedCommandKeys.add(commandKey);
@@ -620,6 +710,14 @@ function analyzeCommand(options) {
 		}));
 		return commandAnalysis(findings);
 	}
+	if (hasUnsupportedShellControlSyntax(executableCommand)) {
+		findings.push(commandFinding(options, {
+			code: "command-unverified",
+			severity: "suggestion",
+			message: "Compound commands, redirections, and shell expansions are not executed or inferred; this command is unverified."
+		}));
+		return commandAnalysis(findings);
+	}
 	const tokens = tokenizeShellCommand(executableCommand);
 	const commandPackageManager = readCommandPackageManager(tokens);
 	const expectedPackageManager = options.command.packageManagerHint ?? (options.command.source === "contract" ? options.packageManager : void 0);
@@ -629,7 +727,7 @@ function analyzeCommand(options) {
 		message: `Command uses ${commandPackageManager}, but ${expectedPackageManager} is expected for this project or code block.`
 	}));
 	const workspaceSelection = readWorkspaceSelection(tokens, commandPackageManager);
-	const workspaceResolution = resolveWorkspaceSelection(workspaceSelection, options.packageManifests, options.rootDir);
+	const workspaceResolution = resolveWorkspaceSelection(workspaceSelection, options.packageManifests, options.rootDir, options.workspaceRoot);
 	if (workspaceResolution.status === "unresolved") {
 		const selectors = workspaceSelection.selectors.length ? workspaceSelection.selectors.join(", ") : "all workspaces";
 		findings.push(commandFinding(options, {
@@ -660,7 +758,7 @@ function analyzeCommand(options) {
 		severity: "error",
 		message: `Command references an unknown docs CLI command: docs ${docsCommand}`
 	}));
-	if (isStaticallyKnownPackageManagerCommand(tokens) || isVersionProbe(tokens)) verificationEstablished = true;
+	if (isStaticallyKnownPackageManagerCommand(tokens) || isVersionProbe(tokens) || isStaticallyValidCurlCommand(tokens) || isStaticallyValidShellBuiltin(tokens, resolvedCwd, options.rootDir) || isStaticallyValidAgentToolCommand(tokens)) verificationEstablished = true;
 	if (!verificationEstablished && findings.length === 0) findings.push(commandFinding(options, {
 		code: "command-unverified",
 		severity: "suggestion",
@@ -894,9 +992,74 @@ function detectPackageManager(rootDir) {
 	const declared = typeof packageJson?.packageManager === "string" ? packageJson.packageManager : "";
 	return /^(npm|pnpm|yarn|bun)@/.exec(declared)?.[1];
 }
+function findEnclosingWorkspaceRoot(startDir) {
+	const repositoryBoundary = findNearestGitBoundary(startDir);
+	let current = startDir;
+	let traversed = 0;
+	while (true) {
+		if (existsSync(path.join(current, "pnpm-workspace.yaml")) || existsSync(path.join(current, "pnpm-workspace.yml"))) return current;
+		const workspaces = readJsonFile(path.join(current, "package.json"))?.workspaces;
+		if (Array.isArray(workspaces) || workspaces !== null && typeof workspaces === "object" && !Array.isArray(workspaces)) return current;
+		if (current === repositoryBoundary || !repositoryBoundary && traversed >= 12) return startDir;
+		const parent = path.dirname(current);
+		if (parent === current) return startDir;
+		current = parent;
+		traversed += 1;
+	}
+}
+function findNearestGitBoundary(startDir) {
+	let current = startDir;
+	while (true) {
+		if (existsSync(path.join(current, ".git"))) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return void 0;
+		current = parent;
+	}
+}
 function normalizeShellCommand(command) {
 	return command.trim().replace(/^\$\s*/, "");
 }
+function hasUnsupportedShellControlSyntax(command) {
+	let quote;
+	let escaped = false;
+	for (let index = 0; index < command.length; index += 1) {
+		const character = command[index] ?? "";
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (character === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (character === quote) quote = void 0;
+			continue;
+		}
+		if (character === "'" || character === "\"") {
+			quote = character;
+			continue;
+		}
+		if (character === "<") {
+			const placeholder = /^<[A-Za-z0-9._-]+>/.exec(command.slice(index))?.[0];
+			if (placeholder) {
+				index += placeholder.length - 1;
+				continue;
+			}
+		}
+		if ([
+			"&",
+			"|",
+			";",
+			"<",
+			">",
+			"`",
+			"\n",
+			"\r"
+		].includes(character) || character === "$" && command[index + 1] === "(") return true;
+	}
+	return Boolean(quote || escaped);
+}
 function tokenizeShellCommand(command) {
 	return command.match(/"[^"]*"|'[^']*'|[^\s]+/g)?.map(stripShellQuotes) ?? [];
 }
@@ -1071,7 +1234,126 @@ function isVersionProbe(tokens) {
 		"yarn"
 	].includes(tokens[0] ?? "") && ["--version", "-v"].includes(tokens[1] ?? "");
 }
-function resolveWorkspaceSelection(selection, manifests, rootDir) {
+function isStaticallyValidCurlCommand(tokens) {
+	if (tokens[0] !== "curl") return false;
+	let urls = 0;
+	let parseOptions = true;
+	for (let index = 1; index < tokens.length; index += 1) {
+		const token = tokens[index] ?? "";
+		if (parseOptions && token === "--") {
+			parseOptions = false;
+			continue;
+		}
+		if (parseOptions && token.startsWith("--")) {
+			const equalsIndex = token.indexOf("=");
+			const option = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;
+			const inlineValue = equalsIndex >= 0 ? token.slice(equalsIndex + 1) : void 0;
+			if (CURL_OPTIONS_WITHOUT_VALUES.has(option)) {
+				if (inlineValue !== void 0) return false;
+				continue;
+			}
+			if (!CURL_OPTIONS_WITH_VALUES.has(option)) return false;
+			const value = inlineValue ?? tokens[index + 1];
+			if (!value || !inlineValue && value.startsWith("-")) return false;
+			if (inlineValue === void 0) index += 1;
+			if (!isValidCurlOptionValue(option, value)) return false;
+			if (option === "--url") urls += 1;
+			continue;
+		}
+		if (parseOptions && token.startsWith("-") && token !== "-") {
+			const shortOptions = token.slice(1);
+			if (!shortOptions) return false;
+			let consumed = false;
+			for (let offset = 0; offset < shortOptions.length; offset += 1) {
+				const option = shortOptions[offset] ?? "";
+				if (CURL_SHORT_OPTIONS_WITHOUT_VALUES.has(option)) continue;
+				if (!CURL_SHORT_OPTIONS_WITH_VALUES.has(option)) return false;
+				const inlineValue = shortOptions.slice(offset + 1);
+				const value = inlineValue || tokens[index + 1];
+				if (!value || !inlineValue && value.startsWith("-")) return false;
+				if (!inlineValue) index += 1;
+				if (!isValidCurlOptionValue(`-${option}`, value)) return false;
+				consumed = true;
+				break;
+			}
+			if (consumed || [...shortOptions].every((item) => CURL_SHORT_OPTIONS_WITHOUT_VALUES.has(item))) continue;
+			return false;
+		}
+		if (!isHttpUrl(token)) return false;
+		urls += 1;
+	}
+	return urls > 0;
+}
+function isValidCurlOptionValue(option, value) {
+	if (option === "--url") return isHttpUrl(value);
+	if (option === "--request" || option === "-X") return /^[A-Z]+$/i.test(value);
+	if (option === "--header" || option === "-H") return /^[^:\s][^:]*:\s*.*$/.test(value);
+	if (option === "--connect-timeout" || option === "--max-time") return /^\d+(?:\.\d+)?$/.test(value);
+	if (option === "--retry" || option === "--retry-delay") return /^\d+$/.test(value);
+	return value.length > 0;
+}
+function isHttpUrl(value) {
+	try {
+		const url = new URL(value);
+		return (url.protocol === "http:" || url.protocol === "https:") && Boolean(url.hostname);
+	} catch {
+		return false;
+	}
+}
+function isStaticallyValidShellBuiltin(tokens, cwd, rootDir) {
+	const command = tokens[0];
+	const args = tokens.slice(1);
+	if (command === "echo") return true;
+	if (command === "printf") return args.length > 0;
+	if (command === "pwd") return args.every((argument) => argument === "-L" || argument === "-P");
+	if (command === "export" || command === "unset") {
+		if (args.length === 0) return false;
+		return args.every((argument) => command === "export" ? /^[A-Za-z_][A-Za-z0-9_]*(?:=.*)?$/.test(argument) : /^[A-Za-z_][A-Za-z0-9_]*$/.test(argument));
+	}
+	if (command === "test") return isValidTestExpression(args);
+	if (command === "[") return args.at(-1) === "]" && isValidTestExpression(args.slice(0, -1));
+	if (command !== "cd" || args.length !== 1) return false;
+	const target = args[0] ?? "";
+	if (!target || target === "-" || path.isAbsolute(target) || /[$*?[\]{}]/.test(target)) return false;
+	return isPathInside(rootDir, path.resolve(cwd, target));
+}
+function isValidTestExpression(args) {
+	if (args[0] === "!") return args.length > 1 && isValidTestExpression(args.slice(1));
+	if (args.length === 1) return true;
+	if (args.length === 2) return TEST_UNARY_OPERATORS.has(args[0] ?? "");
+	return args.length === 3 && TEST_BINARY_OPERATORS.has(args[1] ?? "");
+}
+function isStaticallyValidAgentToolCommand(tokens) {
+	return isStaticallyValidSkillsCommand(tokens) || isStaticallyValidClaudeMcpCommand(tokens);
+}
+function isStaticallyValidSkillsCommand(tokens) {
+	const invocation = unwrapDownloadRunner(tokens);
+	if (!invocation || !/^skills(?:@(?:latest|\d+(?:\.\d+){0,2}))?$/.test(invocation[0] ?? "")) return false;
+	if (invocation.length !== 3 || invocation[1] !== "add") return false;
+	const source = invocation[2] ?? "";
+	if (/^https:\/\/(?:www\.)?github\.com\/[^/\s]+\/[^/\s]+(?:\.git)?(?:#[^\s]+)?$/.test(source)) return true;
+	return /^@?[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:#[A-Za-z0-9._/-]+)?$/.test(source);
+}
+function unwrapDownloadRunner(tokens) {
+	const runner = tokens[0];
+	if (runner === "skills") return tokens;
+	if (runner === "npx" || runner === "pnpx" || runner === "bunx") return tokens.slice(1);
+	if (runner === "npm" && tokens[1] === "exec" && tokens[2] === "--") return tokens.slice(3);
+	if ((runner === "pnpm" || runner === "yarn" || runner === "bun") && ["dlx", "x"].includes(tokens[1] ?? "")) return tokens.slice(2);
+}
+function isStaticallyValidClaudeMcpCommand(tokens) {
+	if (tokens.length !== 5 || tokens[0] !== "claude" || tokens[1] !== "mcp" || tokens[2] !== "add-json" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(tokens[3] ?? "")) return false;
+	try {
+		const config = JSON.parse(tokens[4] ?? "");
+		if (!config || typeof config !== "object" || Array.isArray(config)) return false;
+		if (config.type === "http" || config.type === "sse") return typeof config.url === "string" && isHttpUrl(config.url);
+		if (config.type !== "stdio" || typeof config.command !== "string" || !config.command.trim()) return false;
+		return config.args === void 0 || Array.isArray(config.args) && config.args.every((argument) => typeof argument === "string");
+	} catch {
+		return false;
+	}
+}
+function resolveWorkspaceSelection(selection, manifests, rootDir, workspaceRoot) {
 	if (!selection.requested) return {
 		status: "none",
 		manifests: []
@@ -1092,8 +1374,8 @@ function resolveWorkspaceSelection(selection, manifests, rootDir) {
 			resolved.push(namedManifest);
 			continue;
 		}
-		const selectorPath = path.resolve(rootDir, selector);
-		const pathManifest = [...manifests.values()].find((manifest) => path.resolve(manifest.directory) === selectorPath);
+		const selectorPaths = Array.from(new Set([path.resolve(rootDir, selector), path.resolve(workspaceRoot, selector)]));
+		const pathManifest = [...manifests.values()].find((manifest) => selectorPaths.includes(path.resolve(manifest.directory)));
 		if (!pathManifest) return {
 			status: "unresolved",
 			manifests: []

package/dist/{review-Fndl5brR.mjs → review-CLoHTywU.mjs}

@@ -7,7 +7,7 @@ import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfi
 import "./code-blocks-DnNVNK2M.mjs";
 import { _ as resolveDocsContentDir, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-Wcdj-D0a.mjs";
 import { t as detectFramework } from "./utils-DpiIioYb.mjs";
-import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-Dsvh0etV.mjs";
+import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-Dj-9Eo3v.mjs";
 import matter from "gray-matter";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";

package/package.json

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