@farming-labs/docs 0.2.1 → 0.2.3

package/dist/cli/index.mjs

@@ -98,36 +98,36 @@ async function main() {
 		]
 	};
 	if (!parsedCommand.command || parsedCommand.command === "init") {
-		const { init } = await import("../init-BHUB2nUr.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-CHeiSRTt.mjs");
+		const { runCloudDeploy } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudDeploy(cloudOptions);
 	} else if (parsedCommand.command === "preview") {
-		const { runCloudPreview } = await import("../cloud-CHeiSRTt.mjs");
+		const { runCloudPreview } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudPreview(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "deploy") {
-		const { runCloudDeploy } = await import("../cloud-CHeiSRTt.mjs");
+		const { runCloudDeploy } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudDeploy(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "preview") {
-		const { runCloudPreview } = await import("../cloud-CHeiSRTt.mjs");
+		const { runCloudPreview } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudPreview(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "init") {
-		const { runCloudInit } = await import("../cloud-CHeiSRTt.mjs");
+		const { runCloudInit } = await import("../cloud-DLc03Z41.mjs");
 		await runCloudInit(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "sync") {
-		const { syncCloudConfig } = await import("../cloud-CHeiSRTt.mjs");
+		const { syncCloudConfig } = await import("../cloud-DLc03Z41.mjs");
 		await syncCloudConfig(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "check") {
-		const { runCloudCheck } = await import("../cloud-CHeiSRTt.mjs");
+		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-CHeiSRTt.mjs");
+		const { printCloudHelp } = await import("../cloud-DLc03Z41.mjs");
 		printCloudHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "mcp") {

package/dist/{cloud-CHeiSRTt.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 = [
@@ -652,6 +652,9 @@ function createCheck(name, status, message, details) {
 		...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;
@@ -684,8 +687,24 @@ function resolveCloudCheckTargets(options) {
 function formatCloudCheckTargets(targets) {
 	return targets.join(", ");
 }
-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 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();
@@ -696,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 {};
@@ -811,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);
 	}
@@ -861,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",
@@ -952,9 +1077,11 @@ async function checkCloudConfig(options = {}) {
 	});
 	const serialized = serializeMaterializedDocsJson(config);
 	const previous = existing ? fs.readFileSync(docsJsonPath, "utf-8") : void 0;
-	const apiBaseUrl = resolveApiBaseUrl(options);
+	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;
@@ -968,6 +1095,14 @@ async function checkCloudConfig(options = {}) {
 	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 {
@@ -998,19 +1133,75 @@ async function checkCloudConfig(options = {}) {
 	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 directApiKeyEnv = configuredApiKeyEnv ? configuredApiKeyEnv.startsWith("NEXT_PUBLIC_") ? configuredApiKeyEnv : void 0 : DEFAULT_PUBLIC_DOCS_CLOUD_API_KEY_ENV;
-		const directApiKey = readEnvValue(env, directApiKeyEnv);
-		if (directApiKeyEnv) checks.push(createCheck("askAi.direct", directApiKey && projectEnv ? "pass" : "fail", directApiKey && projectEnv ? `Ask AI can call the Docs Cloud knowledge endpoint directly with ${directApiKeyEnv}.` : `Ask AI docs-cloud direct mode needs ${directApiKeyEnv} and a Docs Cloud project id.`, { apiKeyEnv: directApiKeyEnv }));
+		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}/api/cloud/me`,
+			url: `${apiBaseUrl}/v1/cloud/me`,
 			apiKey
 		});
 		identity = summarizeIdentity(response);
@@ -1132,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);

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

@@ -188,7 +188,7 @@ async function configureDocsCloudOnboarding(options) {
 		enabled = cloudAnswer;
 	}
 	if (!enabled) return;
-	const { initCloudConfig } = await import("./cloud-CHeiSRTt.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.1",
+  "version": "0.2.3",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",