@farming-labs/docs 0.2.53 → 0.2.55

package/dist/codeblocks-BzfkREEC.mjs

@@ -0,0 +1,250 @@
+import { i as validateCodeBlocks, r as resolveDocsCodeBlocksValidateConfig } from "./code-blocks-C9awWzEQ.mjs";
+import { d as readStringProperty, h as resolveDocsContentDir, i as loadDocsConfigModule, m as resolveDocsConfigPath, p as readTopLevelStringProperty, s as readBooleanProperty, t as extractNestedObjectLiteral, u as readNumberProperty } from "./config-CydaZ5PB.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import pc from "picocolors";
+
+//#region src/cli/codeblocks.ts
+function parseInlineFlag(arg) {
+	const [rawKey, value] = arg.slice(2).split("=", 2);
+	return {
+		key: rawKey.trim(),
+		value
+	};
+}
+function parseCodeBlocksValidateArgs(argv) {
+	const parsed = {};
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--help" || arg === "-h") {
+			parsed.help = true;
+			continue;
+		}
+		if (arg === "--json") {
+			parsed.json = true;
+			continue;
+		}
+		if (arg === "--plan") {
+			parsed.plan = true;
+			continue;
+		}
+		if (arg === "--run") {
+			parsed.run = true;
+			continue;
+		}
+		if (arg.startsWith("--config=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --config.");
+			parsed.configPath = value;
+			continue;
+		}
+		if (arg === "--config") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --config.");
+			parsed.configPath = value;
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown codeblocks validate flag: ${arg}.`);
+	}
+	return parsed;
+}
+function printCodeBlocksValidateHelp() {
+	console.log(`
+${pc.bold("@farming-labs/docs codeblocks validate")}
+
+${pc.dim("Usage:")}
+  pnpm exec docs codeblocks validate
+  pnpm exec docs codeblocks validate --plan
+  pnpm exec docs codeblocks validate --json
+  pnpm exec docs codeblocks validate --config docs.config.ts
+
+${pc.dim("Options:")}
+  ${pc.cyan("--plan")}             Build the execution plan without running code
+  ${pc.cyan("--run")}              Force execution even when config mode is ${pc.dim("\"plan\"")}
+  ${pc.cyan("--json")}             Print machine-readable output
+  ${pc.cyan("--config <path>")}    Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
+  ${pc.cyan("-h, --help")}         Show this help message
+`);
+}
+async function runCodeBlocksValidate(options = {}) {
+	const rootDir = process.cwd();
+	const loaded = await loadDocsConfigModule(rootDir, options.configPath, { silent: options.json });
+	const configPath = loaded?.path ?? resolveDocsConfigPath(rootDir, options.configPath);
+	const configContent = existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
+	const entry = loaded?.config.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
+	const contentDir = loaded?.config.contentDir ?? resolveDocsContentDir(rootDir, configContent, entry);
+	const config = resolveDocsCodeBlocksValidateConfig(loaded?.config.codeBlocks?.validate ?? readStaticCodeBlocksValidateConfig(configContent));
+	if (!config.enabled) {
+		const disabledReport = {
+			summary: {
+				total: 0,
+				planned: 0,
+				pass: 0,
+				skip: 0,
+				fail: 0
+			},
+			config,
+			targets: [],
+			plans: [],
+			results: []
+		};
+		if (options.json) console.log(JSON.stringify(redactReport(disabledReport), null, 2));
+		else console.log(pc.yellow("codeBlocks.validate is disabled. Add `codeBlocks: { validate: true }` to docs.config.ts."));
+		return disabledReport;
+	}
+	const effectiveConfig = {
+		...config,
+		mode: options.run ? "report" : config.mode
+	};
+	const planOnly = options.plan === true || effectiveConfig.mode === "plan";
+	const report = await validateCodeBlocks({
+		rootDir,
+		contentDir,
+		config: effectiveConfig,
+		planOnly: options.plan
+	});
+	if (options.json) console.log(JSON.stringify(redactReport(report), null, 2));
+	else printCodeBlocksReport(report, planOnly);
+	if (!options.plan && report.summary.fail > 0) process.exitCode = 1;
+	return report;
+}
+function readStaticCodeBlocksValidateConfig(content) {
+	const block = extractNestedObjectLiteral(content, ["codeBlocks"]);
+	if (!block) return void 0;
+	if (/\bvalidate\s*:\s*true\b/.test(block)) return true;
+	if (/\bvalidate\s*:\s*false\b/.test(block)) return false;
+	const validateBlock = extractNestedObjectLiteral(content, ["codeBlocks", "validate"]);
+	if (validateBlock) {
+		const config = {};
+		const enabled = readBooleanProperty(validateBlock, "enabled");
+		const mode = readStringProperty(validateBlock, "mode");
+		const missingEnv = readStringProperty(validateBlock, "missingEnv");
+		const unsupportedLanguage = readStringProperty(validateBlock, "unsupportedLanguage");
+		const envFile = readStringArrayProperty(validateBlock, "envFile");
+		if (enabled !== void 0) config.enabled = enabled;
+		if (mode === "plan" || mode === "report") config.mode = mode;
+		if (missingEnv === "skip" || missingEnv === "warn" || missingEnv === "error") config.missingEnv = missingEnv;
+		if (unsupportedLanguage === "skip" || unsupportedLanguage === "warn" || unsupportedLanguage === "error") config.unsupportedLanguage = unsupportedLanguage;
+		if (envFile) config.envFile = envFile;
+		const planner = readStaticPlannerConfig(extractNestedObjectLiteral(content, [
+			"codeBlocks",
+			"validate",
+			"planner"
+		]));
+		if (planner) config.planner = planner;
+		const runner = readStaticRunnerConfig(extractNestedObjectLiteral(content, [
+			"codeBlocks",
+			"validate",
+			"runner"
+		]));
+		if (runner) config.runner = runner;
+		const env = readStringRecord(extractNestedObjectLiteral(content, [
+			"codeBlocks",
+			"validate",
+			"env"
+		]));
+		if (env && Object.keys(env).length > 0) config.env = env;
+		return config;
+	}
+	if (/\bvalidate\s*:\s*\{/.test(block)) return true;
+}
+function readStaticPlannerConfig(block) {
+	if (!block) return void 0;
+	const provider = readStringProperty(block, "provider");
+	const model = readStringProperty(block, "model");
+	const baseUrl = readStringProperty(block, "baseUrl");
+	const baseUrlEnv = readStringProperty(block, "baseUrlEnv");
+	const apiKeyEnv = readStringProperty(block, "apiKeyEnv");
+	if (provider !== "metadata" && provider !== "openai" && provider !== "openai-compatible" && provider !== "cloud") return;
+	return {
+		provider,
+		...model ? { model } : {},
+		...baseUrl ? { baseUrl } : {},
+		...baseUrlEnv ? { baseUrlEnv } : {},
+		...apiKeyEnv ? { apiKeyEnv } : {}
+	};
+}
+function readStaticRunnerConfig(block) {
+	if (!block) return void 0;
+	const provider = readStringProperty(block, "provider");
+	const tokenEnv = readStringProperty(block, "tokenEnv");
+	const projectIdEnv = readStringProperty(block, "projectIdEnv");
+	const teamIdEnv = readStringProperty(block, "teamIdEnv");
+	const projectJson = readStringProperty(block, "projectJson");
+	const runtime = readStringProperty(block, "runtime");
+	const apiUrlEnv = readStringProperty(block, "apiUrlEnv");
+	const targetEnv = readStringProperty(block, "targetEnv");
+	const timeoutMs = readNumberProperty(block, "timeoutMs");
+	if (provider !== "local" && provider !== "vercel-sandbox" && provider !== "e2b" && provider !== "daytona" && provider !== "cloud") return;
+	return {
+		provider,
+		...tokenEnv ? { tokenEnv } : {},
+		...projectIdEnv ? { projectIdEnv } : {},
+		...teamIdEnv ? { teamIdEnv } : {},
+		...projectJson ? { projectJson } : {},
+		...runtime === "node24" || runtime === "node22" || runtime === "python3.13" ? { runtime } : {},
+		...apiUrlEnv ? { apiUrlEnv } : {},
+		...targetEnv ? { targetEnv } : {},
+		...timeoutMs !== void 0 ? { timeoutMs } : {}
+	};
+}
+function readStringArrayProperty(content, key) {
+	const single = readStringProperty(content, key);
+	if (single) return [single];
+	const match = content.match(new RegExp(`\\b${key}\\b\\s*:\\s*\\[([\\s\\S]*?)\\]`));
+	if (!match) return void 0;
+	const values = [...match[1].matchAll(/["']([^"']+)["']/g)].map((item) => item[1]);
+	return values.length > 0 ? values : void 0;
+}
+function readStringRecord(block) {
+	if (!block) return void 0;
+	const record = {};
+	for (const pattern of [/(?:^|,)\s*([A-Za-z_$][\w$]*)\s*:\s*["']([^"']+)["']/g, /(?:^|,)\s*["']([^"']+)["']\s*:\s*["']([^"']+)["']/g]) {
+		let match;
+		while (match = pattern.exec(block)) record[match[1]] = match[2];
+	}
+	return record;
+}
+function printCodeBlocksReport(report, planOnly) {
+	const label = planOnly ? "Code block plan" : "Code block validation";
+	console.log(pc.bold(label));
+	console.log([
+		...report.summary.planned > 0 ? [`${pc.cyan(`${report.summary.planned} planned`)}`] : [],
+		`${pc.green(`${report.summary.pass} pass`)}`,
+		`${pc.yellow(`${report.summary.skip} skip`)}`,
+		`${report.summary.fail > 0 ? pc.red(`${report.summary.fail} fail`) : pc.dim("0 fail")}`,
+		`${report.targets.length} code blocks`
+	].join(pc.dim(" • ")));
+	if (report.results.length === 0) return;
+	console.log();
+	for (const result of report.results) {
+		const status = result.status === "PLAN" ? pc.cyan(result.status) : result.status === "PASS" ? pc.green(result.status) : result.status === "FAIL" ? pc.red(result.status) : pc.yellow(result.status);
+		const location = `${result.target.relativePath}:${result.target.lineStart}`;
+		const detail = result.reason ?? result.plan.reason ?? result.plan.template;
+		console.log(`${status} ${pc.cyan(location)} ${pc.dim(detail)}`);
+	}
+}
+function redactReport(report) {
+	return {
+		...report,
+		config: {
+			...report.config,
+			planner: {
+				...report.config.planner,
+				apiKey: report.config.planner.apiKey ? "[REDACTED]" : void 0
+			}
+		},
+		results: report.results.map((result) => ({
+			...result,
+			stdout: trimOutput(result.stdout),
+			stderr: trimOutput(result.stderr)
+		}))
+	};
+}
+function trimOutput(value) {
+	if (!value) return value;
+	return value.length > 4e3 ? `${value.slice(0, 4e3)}...` : value;
+}
+
+//#endregion
+export { parseCodeBlocksValidateArgs, printCodeBlocksValidateHelp, runCodeBlocksValidate };

package/dist/{config-DhIyFsy9.mjs → config-CydaZ5PB.mjs}

@@ -279,28 +279,69 @@ function loadProjectEnv(rootDir) {
 	return env;
 }
 async function loadDocsConfigModule(rootDir, explicitPath, options = {}) {
+	const result = await loadDocsConfigModuleResult(rootDir, explicitPath, options);
+	return result.status === "evaluated" ? {
+		path: result.path,
+		config: result.config
+	} : null;
+}
+function resolveDocsConfigModuleExport(loaded) {
+	if (!loaded || typeof loaded !== "object" || Array.isArray(loaded)) return loaded;
+	const record = loaded;
+	return Object.prototype.hasOwnProperty.call(record, "default") ? record.default : loaded;
+}
+function isPlainDocsConfig(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+/**
+* Load docs.config with an explicit confidence signal for diagnostics.
+* Existing callers can keep using `loadDocsConfigModule`, which preserves the
+* previous evaluated-config-or-null contract.
+*/
+async function loadDocsConfigModuleResult(rootDir, explicitPath, options = {}) {
 	const configPath = resolveDocsConfigPath(rootDir, explicitPath);
 	try {
 		const { createJiti } = await import("jiti");
-		const loaded = await createJiti(import.meta.url, {
+		const config = resolveDocsConfigModuleExport(await createJiti(import.meta.url, {
 			moduleCache: false,
 			fsCache: false,
-			interopDefault: true
-		}).import(configPath);
-		const config = loaded.default ?? loaded;
-		if (!config || typeof config !== "object") return null;
+			interopDefault: false
+		}).import(configPath));
+		if (!isPlainDocsConfig(config)) return {
+			status: "static-fallback",
+			path: configPath,
+			error: "The config module did not export a plain object."
+		};
 		return {
+			status: "evaluated",
 			path: configPath,
 			config
 		};
 	} catch (error) {
-		if (!options.silent && process.env.NODE_ENV !== "test") {
-			const message = error instanceof Error ? error.message : String(error);
-			console.warn(`[docs] Could not evaluate ${configPath} as a module; falling back to static parsing. ${message}`);
-		}
-		return null;
+		const message = error instanceof Error ? error.message : String(error);
+		if (!options.silent && process.env.NODE_ENV !== "test") console.warn(`[docs] Could not evaluate ${configPath} as a module; falling back to static parsing. ${message}`);
+		return {
+			status: "static-fallback",
+			path: configPath,
+			error: message
+		};
+	}
+}
+/** Evaluate docs.config after loading project-local env files, then restore process.env. */
+async function loadDocsConfigModuleResultWithProjectEnv(rootDir, explicitPath, options = {}) {
+	const env = loadProjectEnv(rootDir);
+	const injectedKeys = Object.entries(env).filter(([key]) => process.env[key] === void 0).map(([key, value]) => {
+		process.env[key] = value;
+		return key;
+	});
+	try {
+		return await loadDocsConfigModuleResult(rootDir, explicitPath, options);
+	} finally {
+		for (const key of injectedKeys) delete process.env[key];
 	}
 }
 
 //#endregion
-export { loadProjectEnv as a, readNavTitle as c, readTopLevelBooleanProperty as d, readTopLevelStringProperty as f, loadDocsConfigModule as i, readNumberProperty as l, resolveDocsContentDir as m, extractObjectLiteral as n, readBooleanProperty as o, resolveDocsConfigPath as p, extractTopLevelConfigObject as r, readEnvReferenceProperty as s, extractNestedObjectLiteral as t, readStringProperty as u };
+export { loadDocsConfigModuleResultWithProjectEnv as a, readEnvReferenceProperty as c, readStringProperty as d, readTopLevelBooleanProperty as f, resolveDocsContentDir as h, loadDocsConfigModule as i, readNavTitle as l, resolveDocsConfigPath as m, extractObjectLiteral as n, loadProjectEnv as o, readTopLevelStringProperty as p, extractTopLevelConfigObject as r, readBooleanProperty as s, extractNestedObjectLiteral as t, readNumberProperty as u };

package/dist/{dev-DFeVU2Ui.mjs → dev-BA2kRuCn.mjs}

@@ -1,10 +1,10 @@
-import { i as detectPackageManagerFromProject } from "./utils-CMZTjRQT.mjs";
-import { K as rootLayoutTemplate, W as postcssConfigTemplate, g as docsLayoutTemplate, v as globalCssTemplate, yt as tsconfigTemplate } from "./templates-Bty9M6lA.mjs";
+import { i as detectPackageManagerFromProject } from "./utils-DBCCkkJS.mjs";
+import { K as rootLayoutTemplate, W as postcssConfigTemplate, g as docsLayoutTemplate, v as globalCssTemplate, yt as tsconfigTemplate } from "./templates-1Cod8KrJ.mjs";
 import fs from "node:fs";
 import path from "node:path";
-import pc from "picocolors";
 import { spawn } from "node:child_process";
 import os from "node:os";
+import pc from "picocolors";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
 

package/dist/docs-cloud-server.d.mts

@@ -1,5 +1,5 @@
-import { b as DocsAnalyticsEventInput, v as DocsAnalyticsConfig, y as DocsAnalyticsEvent } from "./types-CdKu8KmO.mjs";
-import { n as DocsCloudAskAIResponseOptions, t as DocsCloudAskAIConfig } from "./cloud-ask-ai-CMzYVzVX.mjs";
+import { D as DocsAnalyticsEventInput, E as DocsAnalyticsEvent, T as DocsAnalyticsConfig } from "./types-R-DN23yw.mjs";
+import { n as DocsCloudAskAIResponseOptions, t as DocsCloudAskAIConfig } from "./cloud-ask-ai-CvRVnwdK.mjs";
 
 //#region src/docs-cloud-server.d.ts
 type DocsCloudRuntimeValue<T = string> = T | undefined | null | (() => T | undefined | null);

package/dist/docs-cloud-server.mjs

@@ -1,5 +1,5 @@
-import { n as sendDocsCloudAnalyticsEvent } from "./cloud-analytics-Dlk_byos.mjs";
-import { t as createDocsCloudAskAIResponse } from "./cloud-ask-ai-BFlx8VMO.mjs";
+import { n as sendDocsCloudAnalyticsEvent } from "./cloud-analytics-CSyFE6SS.mjs";
+import { t as createDocsCloudAskAIResponse } from "./cloud-ask-ai-1k0q6OAH.mjs";
 
 //#region src/docs-cloud-server.ts
 const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://api.farming-labs.dev";