@farming-labs/docs 0.2.0 → 0.2.2

package/dist/cli/index.mjs

@@ -27,7 +27,11 @@ function parseFlags(argv) {
 		"algolia",
 		"verbose",
 		"host",
-		"json"
+		"json",
+		"network",
+		"analytics",
+		"ask-ai",
+		"deploy"
 	]);
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
@@ -85,36 +89,45 @@ async function main() {
 		apiBaseUrl: typeof flags["api-base-url"] === "string" ? flags["api-base-url"] : typeof flags.url === "string" ? flags.url : void 0,
 		apiKey: typeof flags["api-key"] === "string" ? flags["api-key"] : void 0,
 		apiKeyEnv: typeof flags["api-key-env"] === "string" ? flags["api-key-env"] : void 0,
-		json: typeof flags.json === "boolean" ? flags.json : void 0
+		json: typeof flags.json === "boolean" ? flags.json : void 0,
+		network: typeof flags.network === "boolean" ? flags.network : void 0,
+		checkTargets: [
+			...flags.deploy === true ? ["deploy"] : [],
+			...flags.analytics === true ? ["analytics"] : [],
+			...flags["ask-ai"] === true ? ["ask-ai"] : []
+		]
 	};
 	if (!parsedCommand.command || parsedCommand.command === "init") {
-		const { init } = await import("../init-CZx_vasZ.mjs");
+		const { init } = await import("../init-DeeHyP-N.mjs");
 		await init(initOptions);
 	} else if (parsedCommand.command === "dev") {
 		const { dev } = await import("../dev-D58nBPBv.mjs");
 		await dev(devOptions);
 	} else if (parsedCommand.command === "deploy") {
-		const { runCloudDeploy } = await import("../cloud-BBg-41RG.mjs");
+		const { runCloudDeploy } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudDeploy(cloudOptions);
 	} else if (parsedCommand.command === "preview") {
-		const { runCloudPreview } = await import("../cloud-BBg-41RG.mjs");
+		const { runCloudPreview } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudPreview(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "deploy") {
-		const { runCloudDeploy } = await import("../cloud-BBg-41RG.mjs");
+		const { runCloudDeploy } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudDeploy(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "preview") {
-		const { runCloudPreview } = await import("../cloud-BBg-41RG.mjs");
+		const { runCloudPreview } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudPreview(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "init") {
-		const { runCloudInit } = await import("../cloud-BBg-41RG.mjs");
+		const { runCloudInit } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudInit(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "sync") {
-		const { syncCloudConfig } = await import("../cloud-BBg-41RG.mjs");
+		const { syncCloudConfig } = await import("../cloud-DLc03Z41.mjs");
 		await syncCloudConfig(cloudOptions);
+	} else if (parsedCommand.command === "cloud" && subcommand === "check") {
+		const { runCloudCheck } = await import("../cloud-DLc03Z41.mjs");
+		await runCloudCheck(cloudOptions);
 	} else if (parsedCommand.command === "cloud") {
 		console.error(pc.red(`Unknown cloud subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printCloudHelp } = await import("../cloud-BBg-41RG.mjs");
+		const { printCloudHelp } = await import("../cloud-DLc03Z41.mjs");
 		printCloudHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "mcp") {
@@ -253,7 +266,7 @@ ${pc.dim("Commands:")}
   ${pc.cyan("dev")}      Run frameworkless docs locally from ${pc.dim("docs.json")}
   ${pc.cyan("deploy")}   Sync cloud config and deploy hosted preview docs
   ${pc.cyan("preview")}  Alias for ${pc.cyan("deploy")}
-  ${pc.cyan("cloud")}    Docs Cloud utilities (${pc.dim("init")}, ${pc.dim("deploy")}, ${pc.dim("preview")}, ${pc.dim("sync")})
+  ${pc.cyan("cloud")}    Docs Cloud utilities (${pc.dim("init")}, ${pc.dim("check")}, ${pc.dim("deploy")}, ${pc.dim("preview")}, ${pc.dim("sync")})
   ${pc.cyan("agent")}    Agent utilities (${pc.dim("compact")} to generate sibling agent.md files)
   ${pc.cyan("agents")}   AGENTS.md utilities (${pc.dim("generate")} for static agent instructions)
   ${pc.cyan("doctor")}   Inspect and score agent or reader-facing docs quality
@@ -289,17 +302,22 @@ ${pc.dim("Options for dev:")}
   ${pc.cyan("--host [host]")}       Expose the preview on your network; optionally pass a host value
   ${pc.cyan("--verbose")}           Show raw runtime logs in addition to branded CLI output
 
-${pc.dim("Options for cloud deploy:")}
+${pc.dim("Options for cloud:")}
   ${pc.cyan("cloud init")}                           Add Docs Cloud config to ${pc.dim("docs.config.ts")} and ${pc.dim("docs.json")}
   ${pc.cyan("deploy")}                               Sync ${pc.dim("docs.config.ts")} into ${pc.dim("docs.json")} and deploy hosted preview docs
   ${pc.cyan("cloud deploy")}                         Same as ${pc.cyan("deploy")}
   ${pc.cyan("preview")}                              Alias for ${pc.cyan("deploy")}
   ${pc.cyan("cloud preview")}                        Compatibility alias for ${pc.cyan("cloud deploy")}
   ${pc.cyan("cloud sync")}                           Only materialize cloud settings into ${pc.dim("docs.json")}
+  ${pc.cyan("cloud check")}                          Validate Docs Cloud config, analytics envs, API key, and Ask AI wiring
   ${pc.cyan("--config <path>")}                      Use a custom docs config path
   ${pc.cyan("--api-key-env <name>")}                 Env var that stores the Docs Cloud API key
   ${pc.cyan("--api-base-url <url>")}                 Override the Docs Cloud API base URL
   ${pc.cyan("--api-key <key>")}                      Use an API key directly; prefer ${pc.dim("cloud.apiKey.env")}
+  ${pc.cyan("--analytics")}                          Only check Docs Cloud analytics integration
+  ${pc.cyan("--ask-ai")}                             Only check Docs Cloud Ask AI integration
+  ${pc.cyan("--deploy")}                             Only check Docs Cloud deploy integration
+  ${pc.cyan("--no-network")}                         Skip live Docs Cloud API validation for ${pc.cyan("cloud check")}
   ${pc.cyan("--json")}                              Print machine-readable output
   ${pc.dim("required scopes")}                       project:read, preview:write, jobs:read
 

package/dist/{cloud-BBg-41RG.mjs → cloud-DLc03Z41.mjs}

@@ -12,7 +12,7 @@ const DOCS_CLOUD_SCHEMA_URL = "https://docs.farming-labs.dev/schema/docs.json";
 const DOCS_CLOUD_DEFAULT_API_KEY_ENV = "DOCS_CLOUD_API_KEY";
 const DOCS_CLOUD_DEFAULT_ANALYTICS_PROJECT_ID_ENV = "NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID";
 const DOCS_CLOUD_MISSING_API_KEY_DOCS_URL = "https://docs.farming-labs.dev/docs/cloud/deploy#missing-api-key";
-const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://docs-app.farming-labs.dev";
+const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://api.farming-labs.dev";
 const DEFAULT_PREVIEW_TIMEOUT_MS = 300 * 1e3;
 const DEFAULT_PREVIEW_POLL_INTERVAL_MS = 2e3;
 const REQUIRED_PREVIEW_API_KEY_SCOPES = [
@@ -20,6 +20,13 @@ const REQUIRED_PREVIEW_API_KEY_SCOPES = [
 	"preview:write",
 	"jobs:read"
 ];
+const DOCS_CLOUD_PROJECT_ID_ENVS = ["NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID", "DOCS_CLOUD_PROJECT_ID"];
+const DEFAULT_PUBLIC_DOCS_CLOUD_API_KEY_ENV = "NEXT_PUBLIC_DOCS_CLOUD_API_KEY";
+const CLOUD_CHECK_TARGETS = [
+	"deploy",
+	"analytics",
+	"ask-ai"
+];
 function isRecord(value) {
 	return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
@@ -593,8 +600,111 @@ async function materializeCloudConfig(options = {}) {
 		updated
 	};
 }
-function resolveApiBaseUrl(options) {
-	return (options.apiBaseUrl ?? process.env.DOCS_CLOUD_API_URL ?? process.env.NEXT_PUBLIC_DOCS_CLOUD_URL ?? DEFAULT_DOCS_CLOUD_API_BASE_URL).replace(/\/+$/, "");
+function readCombinedEnv(rootDir) {
+	const env = { ...loadProjectEnv(rootDir) };
+	for (const [key, value] of Object.entries(process.env)) if (typeof value === "string") env[key] = value;
+	return env;
+}
+function readEnvValue(env, name) {
+	if (!name) return void 0;
+	const value = env[name]?.trim();
+	return value ? value : void 0;
+}
+function readFirstEnv(env, names) {
+	for (const name of names) {
+		const value = readEnvValue(env, name);
+		if (value) return {
+			name,
+			value
+		};
+	}
+}
+function readConfiguredCloudApiKeyEnv(snapshot) {
+	const moduleEnv = snapshot.config?.cloud?.apiKey?.env?.trim();
+	if (moduleEnv) return moduleEnv;
+	const apiKeyBlock = extractNestedObjectLiteral(snapshot.content ?? "", ["cloud", "apiKey"]);
+	return (apiKeyBlock ? readStringProperty(apiKeyBlock, "env") : void 0)?.trim() || void 0;
+}
+function readAiProvider(snapshot) {
+	const moduleProvider = (snapshot.config?.ai)?.provider;
+	if (typeof moduleProvider === "string" && moduleProvider.trim()) return moduleProvider.trim();
+	const aiBlock = extractNestedObjectLiteral(snapshot.content ?? "", ["ai"]);
+	return (aiBlock ? readStringProperty(aiBlock, "provider") : void 0)?.trim() || void 0;
+}
+function readRuntimeAnalyticsDisabled(snapshot) {
+	const moduleAnalytics = snapshot.config?.analytics;
+	if (moduleAnalytics === false) return true;
+	if (isRecord(moduleAnalytics) && moduleAnalytics.enabled === false) return true;
+	if (readTopLevelBooleanProperty(snapshot.content ?? "", "analytics") === false) return true;
+	const analyticsBlock = extractNestedObjectLiteral(snapshot.content ?? "", ["analytics"]);
+	return (analyticsBlock ? readTopLevelBooleanProperty(analyticsBlock, "enabled") : void 0) === false;
+}
+function isCloudAnalyticsEnabled(analytics) {
+	if (analytics === false) return false;
+	if (isRecord(analytics) && analytics.enabled === false) return false;
+	return typeof analytics !== "undefined";
+}
+function createCheck(name, status, message, details) {
+	return {
+		name,
+		status,
+		message,
+		...details ? { details } : {}
+	};
+}
+function isBrowserSafeEnvName(name) {
+	return name.startsWith("NEXT_PUBLIC_");
+}
+function summarizeIdentity(identity) {
+	if (!isRecord(identity)) return void 0;
+	const workspace = isRecord(identity.workspace) ? identity.workspace : void 0;
+	const apiKey = isRecord(identity.apiKey) ? identity.apiKey : void 0;
+	const scopes = readApiKeyScopes(identity);
+	return {
+		...workspace ? { workspace: {
+			...typeof workspace.id === "string" ? { id: workspace.id } : {},
+			...typeof workspace.name === "string" ? { name: workspace.name } : {}
+		} } : {},
+		...apiKey ? { apiKey: {
+			...typeof apiKey.id === "string" ? { id: apiKey.id } : {},
+			...scopes.length > 0 ? { scopes } : {}
+		} } : {}
+	};
+}
+function formatCheckStatus(status) {
+	if (status === "pass") return pc.green("ok");
+	if (status === "warn") return pc.yellow("warn");
+	return pc.red("fail");
+}
+function countChecks(checks, status) {
+	return checks.filter((check) => check.status === status).length;
+}
+function resolveCloudCheckTargets(options) {
+	const targets = new Set(options.checkTargets);
+	if (targets.size > 0) return targets;
+	return new Set(CLOUD_CHECK_TARGETS);
+}
+function formatCloudCheckTargets(targets) {
+	return targets.join(", ");
+}
+function resolveApiBaseUrl(options, rootDir = process.cwd()) {
+	if (options.apiBaseUrl?.trim()) return {
+		url: options.apiBaseUrl.trim().replace(/\/+$/, ""),
+		source: "flag"
+	};
+	const projectEnv = loadProjectEnv(rootDir);
+	for (const envName of ["DOCS_CLOUD_API_URL", "NEXT_PUBLIC_DOCS_CLOUD_URL"]) {
+		const value = process.env[envName]?.trim() ?? projectEnv[envName]?.trim();
+		if (value) return {
+			url: value.replace(/\/+$/, ""),
+			source: "env",
+			env: envName
+		};
+	}
+	return {
+		url: DEFAULT_DOCS_CLOUD_API_BASE_URL,
+		source: "default"
+	};
 }
 function resolveApiKey(options, rootDir, envName) {
 	if (options.apiKey?.trim()) return options.apiKey.trim();
@@ -605,6 +715,112 @@ function resolveApiKey(options, rootDir, envName) {
 	if (token) return token;
 	throw new Error(`Missing Docs Cloud API key. Set ${envName} in your shell or .env.local, or configure cloud.apiKey.env in docs.config.ts. See ${DOCS_CLOUD_MISSING_API_KEY_DOCS_URL}.`);
 }
+function isLocalhostUrl(value) {
+	try {
+		const url = new URL(value);
+		return [
+			"localhost",
+			"127.0.0.1",
+			"::1"
+		].includes(url.hostname);
+	} catch {
+		return false;
+	}
+}
+function readNestedString(value, pathSegments) {
+	let current = value;
+	for (const segment of pathSegments) {
+		if (!isRecord(current)) return void 0;
+		current = current[segment];
+	}
+	return typeof current === "string" && current.trim() ? current.trim() : void 0;
+}
+function readDocsSiteOrigin(snapshot, env) {
+	const envSite = readFirstEnv(env, [
+		"NEXT_PUBLIC_BASE_URL",
+		"NEXT_PUBLIC_SITE_URL",
+		"SITE_URL"
+	]);
+	const sitemapBlock = extractNestedObjectLiteral(snapshot.content ?? "", ["sitemap"]);
+	const llmsTxtBlock = extractNestedObjectLiteral(snapshot.content ?? "", ["llmsTxt"]);
+	const robotsBlock = extractNestedObjectLiteral(snapshot.content ?? "", ["robots"]);
+	const candidates = [
+		{
+			value: envSite?.value,
+			source: envSite ? envSite.name : "env"
+		},
+		{
+			value: readNestedString(snapshot.config, ["site", "url"]),
+			source: "site.url"
+		},
+		{
+			value: readNestedString(snapshot.config, ["sitemap", "baseUrl"]),
+			source: "sitemap.baseUrl"
+		},
+		{
+			value: readNestedString(snapshot.config, ["llmsTxt", "baseUrl"]),
+			source: "llmsTxt.baseUrl"
+		},
+		{
+			value: readNestedString(snapshot.config, ["robots", "baseUrl"]),
+			source: "robots.baseUrl"
+		},
+		{
+			value: sitemapBlock ? readStringProperty(sitemapBlock, "baseUrl") : void 0,
+			source: "sitemap.baseUrl"
+		},
+		{
+			value: llmsTxtBlock ? readStringProperty(llmsTxtBlock, "baseUrl") : void 0,
+			source: "llmsTxt.baseUrl"
+		},
+		{
+			value: robotsBlock ? readStringProperty(robotsBlock, "baseUrl") : void 0,
+			source: "robots.baseUrl"
+		}
+	];
+	for (const candidate of candidates) {
+		if (!candidate.value) continue;
+		try {
+			return {
+				origin: new URL(candidate.value).origin,
+				source: candidate.source
+			};
+		} catch {}
+	}
+}
+async function checkCorsPreflight(params) {
+	const response = await fetch(params.url, {
+		method: "OPTIONS",
+		headers: {
+			Origin: params.origin,
+			"Access-Control-Request-Method": "POST",
+			"Access-Control-Request-Headers": params.requestHeaders
+		}
+	});
+	const allowOrigin = response.headers.get("access-control-allow-origin");
+	const allowMethods = response.headers.get("access-control-allow-methods");
+	const allowHeaders = response.headers.get("access-control-allow-headers");
+	const normalizedAllowOrigin = allowOrigin?.toLowerCase();
+	const normalizedOrigin = params.origin.toLowerCase();
+	return {
+		ok: response.ok && (normalizedAllowOrigin === "*" || normalizedAllowOrigin === normalizedOrigin) && Boolean(allowMethods?.toUpperCase().includes("POST")) && areCorsRequestHeadersAllowed(params.requestHeaders, allowHeaders),
+		status: response.status,
+		allowOrigin,
+		allowMethods,
+		allowHeaders
+	};
+}
+function areCorsRequestHeadersAllowed(requestHeaders, allowHeaders) {
+	const requested = parseCorsHeaderList(requestHeaders);
+	if (requested.length === 0) return true;
+	if (!allowHeaders) return false;
+	const allowed = parseCorsHeaderList(allowHeaders);
+	if (allowed.includes("*")) return true;
+	return requested.every((header) => allowed.includes(header));
+}
+function parseCorsHeaderList(value) {
+	return value.split(",").map((header) => header.trim().toLowerCase()).filter(Boolean);
+}
 async function readJsonResponse(response) {
 	const text = await response.text();
 	if (!text.trim()) return {};
@@ -720,7 +936,7 @@ async function fetchCloudJson(params) {
 	const body = await readJsonResponse(response);
 	if (!response.ok) {
 		const requestPath = new URL(params.url).pathname;
-		if (response.status === 404 && requestPath === "/api/cloud/preview") throw new Error("Docs Cloud preview API is not available on this cloud host yet. The API key was validated, but the host did not expose /api/cloud/preview.");
+		if (response.status === 404 && requestPath === "/v1/cloud/preview") throw new Error("Docs Cloud preview API is not available on this cloud host yet. The API key was validated, but the host did not expose /v1/cloud/preview.");
 		const message = readResponseMessage(body, `Docs Cloud request failed with HTTP ${response.status}.`);
 		throw new Error(message);
 	}
@@ -770,7 +986,7 @@ function readStatusLabel(body) {
 }
 async function requestPreview(params) {
 	const initial = await fetchCloudJson({
-		url: `${params.apiBaseUrl}/api/cloud/preview`,
+		url: `${params.apiBaseUrl}/v1/cloud/preview`,
 		apiKey: params.apiKey,
 		init: {
 			method: "POST",
@@ -849,6 +1065,195 @@ function createSpinner(initialMessage, options = {}) {
 		}
 	};
 }
+async function checkCloudConfig(options = {}) {
+	const rootDir = options.rootDir ?? process.cwd();
+	const docsJsonPath = path.join(rootDir, DOCS_JSON_FILE);
+	const existing = readExistingDocsJson(docsJsonPath);
+	const snapshot = await loadDocsConfigSnapshot(rootDir, options.configPath);
+	const config = materializeDocsJsonObject({
+		rootDir,
+		snapshot,
+		existing
+	});
+	const serialized = serializeMaterializedDocsJson(config);
+	const previous = existing ? fs.readFileSync(docsJsonPath, "utf-8") : void 0;
+	const apiBaseUrlResolution = resolveApiBaseUrl(options, rootDir);
+	const apiBaseUrl = apiBaseUrlResolution.url;
+	const apiKeyEnv = config.cloud?.apiKey?.env ?? DOCS_CLOUD_DEFAULT_API_KEY_ENV;
+	const env = readCombinedEnv(rootDir);
+	const siteOrigin = readDocsSiteOrigin(snapshot, env);
+	const checks = [];
+	const configPath = snapshot.path ?? docsJsonPath;
+	const network = options.network !== false;
+	const explicitApiKey = options.apiKey?.trim();
+	const targetSet = resolveCloudCheckTargets(options);
+	const targets = CLOUD_CHECK_TARGETS.filter((target) => targetSet.has(target));
+	const checkDeploy = targetSet.has("deploy");
+	const checkAnalytics = targetSet.has("analytics");
+	const checkAskAi = targetSet.has("ask-ai");
+	const checkProjectEnv = checkAnalytics || checkAskAi;
+	let identity;
+	checks.push(createCheck("config", snapshot.path ? "pass" : "warn", snapshot.path ? `Loaded ${path.relative(rootDir, snapshot.path) || "docs.config.ts"}` : `No docs.config.* found; checking ${DOCS_JSON_FILE} defaults instead.`));
+	checks.push(createCheck("docs.json", !existing ? "warn" : previous === serialized ? "pass" : "warn", !existing ? `${DOCS_JSON_FILE} is missing. Run docs cloud sync to materialize cloud config.` : previous === serialized ? `${DOCS_JSON_FILE} is in sync with docs.config.` : `${DOCS_JSON_FILE} is stale. Run docs cloud sync before deploying.`));
+	checks.push(createCheck("cloud.apiBaseUrl", isLocalhostUrl(apiBaseUrl) ? "warn" : "pass", apiBaseUrlResolution.source === "default" ? `Using the hosted Docs Cloud API at ${apiBaseUrl}.` : isLocalhostUrl(apiBaseUrl) ? `Docs Cloud API base URL is ${apiBaseUrl}; production docs should use the hosted API base URL.` : `Docs Cloud API base URL is ${apiBaseUrl}.`, {
+		source: apiBaseUrlResolution.source,
+		...apiBaseUrlResolution.env ? { env: apiBaseUrlResolution.env } : {}
+	}));
+	if (checkAnalytics || checkAskAi) checks.push(createCheck("docs.siteOrigin", siteOrigin ? "pass" : "warn", siteOrigin ? `Public docs origin is ${siteOrigin.origin}.` : "Could not infer the public docs origin for CORS checks. Set NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_SITE_URL, SITE_URL, or a docs config baseUrl.", siteOrigin ? {
+		origin: siteOrigin.origin,
+		source: siteOrigin.source
+	} : void 0));
+	const apiKey = explicitApiKey || readEnvValue(env, apiKeyEnv);
+	if (checkDeploy) {
+		try {
+			normalizeEnvName(apiKeyEnv, DOCS_CLOUD_DEFAULT_API_KEY_ENV);
+			checks.push(createCheck("apiKey.config", "pass", `Using cloud.apiKey.env ${apiKeyEnv}.`));
+		} catch (error) {
+			checks.push(createCheck("apiKey.config", "fail", error instanceof Error ? error.message : `Invalid API key env ${apiKeyEnv}.`));
+		}
+		checks.push(createCheck("apiKey.value", apiKey ? "pass" : "fail", apiKey ? explicitApiKey ? "Docs Cloud API key was provided with --api-key." : `Docs Cloud API key is present in ${apiKeyEnv}.` : `Missing Docs Cloud API key. Set ${apiKeyEnv} or pass --api-key.`, {
+			env: apiKeyEnv,
+			source: explicitApiKey ? "flag" : apiKey ? "env" : "missing"
+		}));
+	}
+	checks.push(createCheck("cloud.enabled", config.cloud?.enabled === false ? "fail" : "pass", config.cloud?.enabled === false ? "Docs Cloud is disabled by cloud.enabled: false." : "Docs Cloud is enabled."));
+	if (checkDeploy) {
+		if (config.cloud?.deploy?.enabled === false) checks.push(createCheck("deploy.enabled", "fail", "Docs Cloud deployment is disabled by cloud.deploy.enabled: false."));
+		else checks.push(createCheck("deploy.enabled", "pass", "Docs Cloud deployment is enabled."));
+		if (config.cloud?.preview?.enabled === false) checks.push(createCheck("preview.enabled", "fail", "Docs Cloud preview deployment is disabled by cloud.preview.enabled: false."));
+	}
+	const runtimeAnalyticsDisabled = readRuntimeAnalyticsDisabled(snapshot);
+	const cloudAnalyticsEnabled = isCloudAnalyticsEnabled(config.cloud?.analytics);
+	if (checkAnalytics) {
+		if (runtimeAnalyticsDisabled) checks.push(createCheck("analytics.runtime", "fail", "Runtime analytics is disabled by analytics: false or analytics.enabled: false."));
+		else checks.push(createCheck("analytics.runtime", "pass", "Runtime analytics is not disabled."));
+		checks.push(createCheck("analytics.cloud", cloudAnalyticsEnabled ? "pass" : "warn", cloudAnalyticsEnabled ? "Docs Cloud analytics is enabled in cloud.analytics." : "cloud.analytics is not enabled; run docs cloud init to add the recommended analytics config."));
+	}
+	const projectEnv = readFirstEnv(env, DOCS_CLOUD_PROJECT_ID_ENVS);
+	const analyticsNeedsProjectId = cloudAnalyticsEnabled && !runtimeAnalyticsDisabled;
+	if (checkProjectEnv) checks.push(createCheck("project.env", projectEnv ? "pass" : analyticsNeedsProjectId || checkAskAi ? "fail" : "warn", projectEnv ? `Docs Cloud project id is present in ${projectEnv.name}.` : `Missing Docs Cloud project id. Set ${DOCS_CLOUD_PROJECT_ID_ENVS.join(" or ")} for analytics and docs-cloud Ask AI.`, projectEnv ? { env: projectEnv.name } : void 0));
+	const aiProvider = readAiProvider(snapshot);
+	let askAiCorsMode = "none";
+	if (checkAskAi) if (aiProvider === "docs-cloud") {
+		checks.push(createCheck("askAi.provider", "pass", "Ask AI is configured with provider: \"docs-cloud\"."));
+		const configuredApiKeyEnv = readConfiguredCloudApiKeyEnv(snapshot);
+		const publicApiKeyEnv = configuredApiKeyEnv && isBrowserSafeEnvName(configuredApiKeyEnv) ? configuredApiKeyEnv : readFirstEnv(env, [DEFAULT_PUBLIC_DOCS_CLOUD_API_KEY_ENV])?.name ?? DEFAULT_PUBLIC_DOCS_CLOUD_API_KEY_ENV;
+		const publicApiKey = readEnvValue(env, publicApiKeyEnv);
+		const publicProjectEnv = readFirstEnv(env, [DOCS_CLOUD_DEFAULT_ANALYTICS_PROJECT_ID_ENV]);
+		const serverApiKeyEnv = configuredApiKeyEnv ?? DOCS_CLOUD_DEFAULT_API_KEY_ENV;
+		const serverApiKey = readEnvValue(env, serverApiKeyEnv);
+		if (publicApiKey && publicProjectEnv) {
+			checks.push(createCheck("askAi.direct", "pass", `Ask AI can call the Docs Cloud knowledge endpoint directly with ${publicApiKeyEnv}.`, {
+				apiKeyEnv: publicApiKeyEnv,
+				projectIdEnv: publicProjectEnv.name
+			}));
+			askAiCorsMode = "direct";
+		} else if (serverApiKey && projectEnv) {
+			checks.push(createCheck("askAi.direct", "warn", `Direct browser Ask AI needs ${DEFAULT_PUBLIC_DOCS_CLOUD_API_KEY_ENV} and ${DOCS_CLOUD_DEFAULT_ANALYTICS_PROJECT_ID_ENV}; this app can use the local docs API route with ${serverApiKeyEnv}.`, {
+				apiKeyEnv: serverApiKeyEnv,
+				projectIdEnv: projectEnv.name,
+				proxy: true
+			}));
+			askAiCorsMode = "proxy";
+		} else checks.push(createCheck("askAi.direct", "fail", `Ask AI docs-cloud direct mode needs ${DEFAULT_PUBLIC_DOCS_CLOUD_API_KEY_ENV} and ${DOCS_CLOUD_DEFAULT_ANALYTICS_PROJECT_ID_ENV}.`, { apiKeyEnv: publicApiKeyEnv }));
+	} else if (aiProvider) checks.push(createCheck("askAi.provider", "pass", `Ask AI provider is ${aiProvider}.`));
+	else checks.push(createCheck("askAi.provider", "warn", "Ask AI is not configured with provider: \"docs-cloud\"."));
+	if (checkAnalytics || checkAskAi) if (!network) checks.push(createCheck("cloud.cors", "warn", "Skipped Docs Cloud CORS validation because --no-network was passed."));
+	else if (!siteOrigin) checks.push(createCheck("cloud.cors", "warn", "Could not infer the docs site origin for CORS checks. Set NEXT_PUBLIC_BASE_URL or a docs config baseUrl."));
+	else {
+		if (checkAnalytics) try {
+			const cors = await checkCorsPreflight({
+				url: `${apiBaseUrl}/v1/analytics/events`,
+				origin: siteOrigin.origin,
+				requestHeaders: "content-type"
+			});
+			checks.push(createCheck("cors.analytics", cors.ok ? "pass" : "fail", cors.ok ? `Analytics CORS allows ${siteOrigin.origin}.` : `Analytics CORS blocked ${siteOrigin.origin}.`, {
+				origin: siteOrigin.origin,
+				originSource: siteOrigin.source,
+				status: cors.status,
+				allowOrigin: cors.allowOrigin,
+				allowMethods: cors.allowMethods,
+				allowHeaders: cors.allowHeaders
+			}));
+		} catch (error) {
+			checks.push(createCheck("cors.analytics", "fail", error instanceof Error ? `Analytics CORS check failed: ${error.message}` : "Analytics CORS check failed."));
+		}
+		if (checkAskAi && projectEnv && askAiCorsMode === "direct") try {
+			const cors = await checkCorsPreflight({
+				url: `${apiBaseUrl}/v1/projects/${encodeURIComponent(projectEnv.value)}/knowledge/ask`,
+				origin: siteOrigin.origin,
+				requestHeaders: "authorization, content-type"
+			});
+			checks.push(createCheck("cors.askAi", cors.ok ? "pass" : "fail", cors.ok ? `Ask AI CORS allows ${siteOrigin.origin}.` : `Ask AI CORS blocked ${siteOrigin.origin}.`, {
+				origin: siteOrigin.origin,
+				originSource: siteOrigin.source,
+				status: cors.status,
+				allowOrigin: cors.allowOrigin,
+				allowMethods: cors.allowMethods,
+				allowHeaders: cors.allowHeaders
+			}));
+		} catch (error) {
+			checks.push(createCheck("cors.askAi", "fail", error instanceof Error ? `Ask AI CORS check failed: ${error.message}` : "Ask AI CORS check failed."));
+		}
+		else if (checkAskAi && askAiCorsMode === "proxy") checks.push(createCheck("cors.askAi", "pass", "Ask AI uses the local docs API route, so Docs Cloud browser CORS is not required.", { proxy: true }));
+	}
+	if (checkDeploy) if (!network) checks.push(createCheck("apiKey.network", "warn", "Skipped Docs Cloud API validation because --no-network was passed."));
+	else if (!apiKey) checks.push(createCheck("apiKey.network", "warn", "Skipped Docs Cloud API validation because no API key value was available."));
+	else try {
+		const response = await fetchCloudJson({
+			url: `${apiBaseUrl}/v1/cloud/me`,
+			apiKey
+		});
+		identity = summarizeIdentity(response);
+		checks.push(createCheck("apiKey.network", "pass", `Validated API key with ${apiBaseUrl}.`, identity));
+		const scopes = readApiKeyScopes(response);
+		if (scopes.length === 0) checks.push(createCheck("apiKey.scopes", "warn", "Docs Cloud validated the API key but did not return scope metadata."));
+		else {
+			const missing = REQUIRED_PREVIEW_API_KEY_SCOPES.filter((scope) => !scopes.includes(scope));
+			checks.push(createCheck("apiKey.scopes", missing.length === 0 ? "pass" : "fail", missing.length === 0 ? `API key has required deploy scopes: ${REQUIRED_PREVIEW_API_KEY_SCOPES.join(", ")}.` : `API key is missing required deploy scope${missing.length === 1 ? "" : "s"}: ${missing.join(", ")}.`, { scopes }));
+		}
+	} catch (error) {
+		checks.push(createCheck("apiKey.network", "fail", error instanceof Error ? error.message : "Could not validate Docs Cloud API key."));
+	}
+	return {
+		ok: countChecks(checks, "fail") === 0,
+		apiBaseUrl,
+		configPath,
+		docsJsonPath,
+		apiKeyEnv,
+		analyticsProjectIdEnv: projectEnv?.name,
+		network,
+		targets,
+		checks,
+		...identity ? { identity } : {}
+	};
+}
+async function runCloudCheck(options = {}) {
+	const result = await checkCloudConfig(options);
+	if (options.json) console.log(JSON.stringify(result, null, 2));
+	else {
+		console.log(pc.bold("Docs Cloud check"));
+		console.log(`${pc.dim("api")} ${result.apiBaseUrl}`);
+		console.log(`${pc.dim("scope")} ${formatCloudCheckTargets(result.targets)}`);
+		console.log();
+		for (const check of result.checks) console.log(`${formatCheckStatus(check.status)} ${pc.bold(check.name)} ${check.message}`);
+		console.log();
+		if (result.ok) {
+			const warnings = countChecks(result.checks, "warn");
+			const suffix = warnings > 0 ? ` with ${warnings} warning${warnings === 1 ? "" : "s"}` : "";
+			console.log(`${pc.green("ok")} Docs Cloud check passed${suffix}.`);
+		} else {
+			const failures = countChecks(result.checks, "fail");
+			console.log(`${pc.red("fail")} Docs Cloud check failed with ${failures} failed check${failures === 1 ? "" : "s"}.`);
+		}
+	}
+	if (!result.ok) {
+		const error = /* @__PURE__ */ new Error("Docs Cloud check failed.");
+		markCliErrorReported(error);
+		throw error;
+	}
+	return result;
+}
 async function syncCloudConfig(options = {}) {
 	const result = await materializeCloudConfig(options);
 	if (options.json) {
@@ -918,10 +1323,10 @@ async function runCloudDeployment(options = {}) {
 		if (materialized.config.cloud?.preview?.enabled === false) throw new Error("Docs Cloud preview deployments are disabled in cloud.preview.enabled. Remove that legacy override before deploying hosted preview docs.");
 		if (materialized.config.cloud?.deploy?.enabled === false) throw new Error("Docs Cloud deployment is disabled in cloud.deploy.enabled. Set it to true before deploying hosted preview docs.");
 		const apiKey = resolveApiKey(options, rootDir, materialized.apiKeyEnv);
-		const apiBaseUrl = resolveApiBaseUrl(options);
+		const apiBaseUrl = resolveApiBaseUrl(options, rootDir).url;
 		spinner.update("Validating Docs Cloud API key");
 		const identity = await fetchCloudJson({
-			url: `${apiBaseUrl}/api/cloud/me`,
+			url: `${apiBaseUrl}/v1/cloud/me`,
 			apiKey
 		});
 		assertPreviewApiKeyScopes(identity);
@@ -970,6 +1375,7 @@ ${pc.bold("@farming-labs/docs cloud")}
 
 ${pc.dim("Usage:")}
   ${pc.cyan("docs cloud init")}           Add Docs Cloud config to ${pc.dim("docs.config.ts")} and ${pc.dim("docs.json")}
+  ${pc.cyan("docs cloud check")}          Validate Docs Cloud config, analytics envs, API key, and Ask AI wiring
   ${pc.cyan("docs deploy")}               Sync ${pc.dim("docs.config.ts")} to ${pc.dim("docs.json")} and deploy hosted preview docs
   ${pc.cyan("docs cloud deploy")}         Same as ${pc.cyan("docs deploy")}
   ${pc.cyan("docs preview")}              Compatibility alias for ${pc.cyan("docs deploy")}
@@ -981,6 +1387,10 @@ ${pc.dim("Options:")}
   ${pc.cyan("--api-key-env <name>")}      Env var that stores the Docs Cloud API key
   ${pc.cyan("--api-base-url <url>")}      Override Docs Cloud API base URL
   ${pc.cyan("--api-key <key>")}           Use an API key directly; prefer ${pc.dim("cloud.apiKey.env")}
+  ${pc.cyan("--analytics")}               Only check Docs Cloud analytics integration
+  ${pc.cyan("--ask-ai")}                  Only check Docs Cloud Ask AI integration
+  ${pc.cyan("--deploy")}                  Only check Docs Cloud deploy integration
+  ${pc.cyan("--no-network")}              Skip live Docs Cloud API validation for ${pc.cyan("cloud check")}
   ${pc.cyan("--json")}                    Print machine-readable output
 
 ${pc.dim("API key scopes:")}
@@ -997,4 +1407,4 @@ ${pc.dim("Config example:")}
 }
 
 //#endregion
-export { initCloudConfig, printCloudHelp, runCloudDeploy, runCloudInit, runCloudPreview, syncCloudConfig };
+export { initCloudConfig, printCloudHelp, runCloudCheck, runCloudDeploy, runCloudInit, runCloudPreview, syncCloudConfig };

package/dist/{init-CZx_vasZ.mjs → init-DeeHyP-N.mjs}

@@ -188,7 +188,7 @@ async function configureDocsCloudOnboarding(options) {
 		enabled = cloudAnswer;
 	}
 	if (!enabled) return;
-	const { initCloudConfig } = await import("./cloud-BBg-41RG.mjs");
+	const { initCloudConfig } = await import("./cloud-DLc03Z41.mjs");
 	printDocsCloudOnboardingInstructions(await initCloudConfig({
 		rootDir: options.rootDir,
 		configPath: getDocsCloudConfigPathForFramework(options.framework)

package/package.json

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