@farming-labs/docs 0.1.138 → 0.1.140

package/dist/cli/index.mjs

@@ -81,6 +81,7 @@ async function main() {
 		configPath: typeof flags.config === "string" ? flags.config : void 0,
 		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
 	};
 	if (!parsedCommand.command || parsedCommand.command === "init") {
@@ -90,24 +91,27 @@ async function main() {
 		const { dev } = await import("../dev-DdlhqXNU.mjs");
 		await dev(devOptions);
 	} else if (parsedCommand.command === "deploy") {
-		const { runCloudDeploy } = await import("../cloud-BdSGNsah.mjs");
+		const { runCloudDeploy } = await import("../cloud-DcsDg7Ze.mjs");
 		await runCloudDeploy(cloudOptions);
 	} else if (parsedCommand.command === "preview") {
-		const { runCloudPreview } = await import("../cloud-BdSGNsah.mjs");
+		const { runCloudPreview } = await import("../cloud-DcsDg7Ze.mjs");
 		await runCloudPreview(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "deploy") {
-		const { runCloudDeploy } = await import("../cloud-BdSGNsah.mjs");
+		const { runCloudDeploy } = await import("../cloud-DcsDg7Ze.mjs");
 		await runCloudDeploy(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "preview") {
-		const { runCloudPreview } = await import("../cloud-BdSGNsah.mjs");
+		const { runCloudPreview } = await import("../cloud-DcsDg7Ze.mjs");
 		await runCloudPreview(cloudOptions);
+	} else if (parsedCommand.command === "cloud" && subcommand === "init") {
+		const { runCloudInit } = await import("../cloud-DcsDg7Ze.mjs");
+		await runCloudInit(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "sync") {
-		const { syncCloudConfig } = await import("../cloud-BdSGNsah.mjs");
+		const { syncCloudConfig } = await import("../cloud-DcsDg7Ze.mjs");
 		await syncCloudConfig(cloudOptions);
 	} else if (parsedCommand.command === "cloud") {
 		console.error(pc.red(`Unknown cloud subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printCloudHelp } = await import("../cloud-BdSGNsah.mjs");
+		const { printCloudHelp } = await import("../cloud-DcsDg7Ze.mjs");
 		printCloudHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "mcp") {
@@ -246,7 +250,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("deploy")}, ${pc.dim("preview")}, ${pc.dim("sync")})
+  ${pc.cyan("cloud")}    Docs Cloud utilities (${pc.dim("init")}, ${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
@@ -281,12 +285,14 @@ ${pc.dim("Options for dev:")}
   ${pc.cyan("--verbose")}           Show raw runtime logs in addition to branded CLI output
 
 ${pc.dim("Options for cloud deploy:")}
+  ${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("--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("--json")}                              Print machine-readable output

package/dist/{cloud-BdSGNsah.mjs → cloud-DcsDg7Ze.mjs}

@@ -9,6 +9,7 @@ import { execFileSync } from "node:child_process";
 const DOCS_JSON_FILE = "docs.json";
 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 DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://docs-app.farming-labs.dev";
 const DEFAULT_PREVIEW_TIMEOUT_MS = 300 * 1e3;
 const DEFAULT_PREVIEW_POLL_INTERVAL_MS = 2e3;
@@ -112,6 +113,299 @@ async function loadDocsConfigSnapshot(rootDir, explicitPath) {
 		config: (await loadDocsConfigModule(rootDir, configPath, { silent: true }))?.config
 	};
 }
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function findBalancedBraceEnd(content, braceStart) {
+	let depth = 0;
+	let stringQuote = null;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	for (let index = braceStart; index < content.length; index += 1) {
+		const char = content[index];
+		const next = content[index + 1];
+		if (lineComment) {
+			if (char === "\n") lineComment = false;
+			continue;
+		}
+		if (blockComment) {
+			if (char === "*" && next === "/") {
+				blockComment = false;
+				index += 1;
+			}
+			continue;
+		}
+		if (stringQuote) {
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (char === stringQuote) stringQuote = null;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			lineComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			blockComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			stringQuote = char;
+			continue;
+		}
+		if (char === "{") {
+			depth += 1;
+			continue;
+		}
+		if (char !== "}") continue;
+		depth -= 1;
+		if (depth === 0) return index;
+	}
+	return -1;
+}
+function findConfigObjectRange(content) {
+	for (const marker of ["defineDocs(", "export default"]) {
+		const markerIndex = content.indexOf(marker);
+		if (markerIndex === -1) continue;
+		const braceStart = content.indexOf("{", markerIndex);
+		if (braceStart === -1) continue;
+		const braceEnd = findBalancedBraceEnd(content, braceStart);
+		if (braceEnd === -1) continue;
+		return {
+			braceStart,
+			braceEnd,
+			bodyStart: braceStart + 1,
+			bodyEnd: braceEnd
+		};
+	}
+}
+function stripLeadingPropertyTrivia(content) {
+	let current = content;
+	while (true) {
+		const trimmed = current.replace(/^\s+/, "");
+		if (trimmed.startsWith("//")) {
+			const lineEnd = trimmed.indexOf("\n");
+			current = lineEnd === -1 ? "" : trimmed.slice(lineEnd + 1);
+			continue;
+		}
+		if (trimmed.startsWith("/*")) {
+			const blockEnd = trimmed.indexOf("*/");
+			current = blockEnd === -1 ? "" : trimmed.slice(blockEnd + 2);
+			continue;
+		}
+		return trimmed;
+	}
+}
+function propertyStartsWithKey(property, key) {
+	return new RegExp(`^${escapeRegExp(key)}\\s*:`).test(stripLeadingPropertyTrivia(property));
+}
+function findTopLevelPropertyRange(content, bodyStart, bodyEnd, key) {
+	let start = bodyStart;
+	let stringQuote = null;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	let braceDepth = 0;
+	let bracketDepth = 0;
+	let parenDepth = 0;
+	const maybeMatch = (end) => {
+		if (!propertyStartsWithKey(content.slice(start, end), key)) return void 0;
+		return {
+			start,
+			end
+		};
+	};
+	for (let index = bodyStart; index <= bodyEnd; index += 1) {
+		const char = content[index];
+		const next = content[index + 1];
+		if (index === bodyEnd) return maybeMatch(index);
+		if (lineComment) {
+			if (char === "\n") lineComment = false;
+			continue;
+		}
+		if (blockComment) {
+			if (char === "*" && next === "/") {
+				blockComment = false;
+				index += 1;
+			}
+			continue;
+		}
+		if (stringQuote) {
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (char === stringQuote) stringQuote = null;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			lineComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			blockComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			stringQuote = char;
+			continue;
+		}
+		if (char === "{") {
+			braceDepth += 1;
+			continue;
+		}
+		if (char === "}") {
+			braceDepth = Math.max(0, braceDepth - 1);
+			continue;
+		}
+		if (char === "[") {
+			bracketDepth += 1;
+			continue;
+		}
+		if (char === "]") {
+			bracketDepth = Math.max(0, bracketDepth - 1);
+			continue;
+		}
+		if (char === "(") {
+			parenDepth += 1;
+			continue;
+		}
+		if (char === ")") {
+			parenDepth = Math.max(0, parenDepth - 1);
+			continue;
+		}
+		if (char !== "," || braceDepth !== 0 || bracketDepth !== 0 || parenDepth !== 0) continue;
+		const match = maybeMatch(index);
+		if (match) return match;
+		start = index + 1;
+	}
+}
+function findObjectPropertyRange(content, object, key) {
+	const property = findTopLevelPropertyRange(content, object.bodyStart, object.bodyEnd, key);
+	if (!property) return void 0;
+	const colon = content.indexOf(":", property.start);
+	const braceStart = content.indexOf("{", colon);
+	if (colon === -1 || braceStart === -1 || braceStart > property.end) return void 0;
+	const braceEnd = findBalancedBraceEnd(content, braceStart);
+	if (braceEnd === -1 || braceEnd > property.end) return void 0;
+	return {
+		braceStart,
+		braceEnd,
+		bodyStart: braceStart + 1,
+		bodyEnd: braceEnd
+	};
+}
+function lineIndentAt(content, index) {
+	const lineStart = content.lastIndexOf("\n", index - 1) + 1;
+	return content.slice(lineStart, index).match(/^\s*/)?.[0] ?? "";
+}
+function insertObjectProperties(content, object, properties) {
+	if (properties.length === 0) return content;
+	const body = content.slice(object.bodyStart, object.bodyEnd);
+	const closingIndent = lineIndentAt(content, object.braceEnd);
+	const beforeObjectClose = content.slice(0, object.bodyEnd).replace(/\s*$/, "");
+	const suffix = content.slice(object.bodyEnd);
+	return `${beforeObjectClose}${body.trim().length > 0 && !beforeObjectClose.endsWith(",") ? "," : ""}\n${properties.join("\n")}\n${closingIndent}${suffix}`;
+}
+function renderAnalyticsConfigProperty(indent) {
+	return `${indent}analytics: {
+${indent}  enabled: true,
+${indent}  console: false,
+${indent}  includeInputs: false,
+${indent}},`;
+}
+function renderCloudConfigProperty(indent, apiKeyEnv) {
+	return `${indent}cloud: {
+${indent}  apiKey: { env: ${JSON.stringify(apiKeyEnv)} },
+${indent}  deploy: { enabled: true },
+${indent}  analytics: {
+${indent}    enabled: true,
+${indent}    console: false,
+${indent}    includeInputs: false,
+${indent}  },
+${indent}  publish: { mode: "draft-pr", baseBranch: "main" },
+${indent}},`;
+}
+function renderCloudInitDocsConfig(apiKeyEnv) {
+	return `import { defineDocs } from "@farming-labs/docs";
+
+export default defineDocs({
+${renderAnalyticsConfigProperty("  ")}
+${renderCloudConfigProperty("  ", apiKeyEnv)}
+});
+`;
+}
+function normalizeEnvName(value, fallback) {
+	const normalized = value?.trim();
+	if (!normalized) return fallback;
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(normalized)) throw new Error(`Invalid environment variable name: ${normalized}`);
+	return normalized;
+}
+function ensureDocsConfigCloudInit(options) {
+	const resolvedConfigPath = tryResolveDocsConfigPath(options.rootDir, options.configPath);
+	const configPath = resolvedConfigPath ?? path.join(options.rootDir, "docs.config.ts");
+	if (!resolvedConfigPath) {
+		fs.writeFileSync(configPath, renderCloudInitDocsConfig(options.apiKeyEnv), "utf-8");
+		return {
+			configPath,
+			created: true,
+			updated: true
+		};
+	}
+	const original = fs.readFileSync(configPath, "utf-8");
+	let content = original;
+	let configObject = findConfigObjectRange(content);
+	if (!configObject) throw new Error(`Could not find an object export in ${path.relative(options.rootDir, configPath)}. Use defineDocs({ ... }) or export default { ... } before running cloud init.`);
+	const topLevelIndent = `${lineIndentAt(content, configObject.braceEnd)}  `;
+	const cloudProperty = findTopLevelPropertyRange(content, configObject.bodyStart, configObject.bodyEnd, "cloud");
+	let cloudObject = findObjectPropertyRange(content, configObject, "cloud");
+	if (!cloudProperty) content = insertObjectProperties(content, configObject, [renderCloudConfigProperty(topLevelIndent, options.apiKeyEnv)]);
+	else if (!cloudObject) throw new Error(`Could not update cloud config in ${path.relative(options.rootDir, configPath)} because cloud is not an object literal.`);
+	configObject = findConfigObjectRange(content);
+	if (!configObject) throw new Error(`Could not re-read ${path.relative(options.rootDir, configPath)}.`);
+	cloudObject = findObjectPropertyRange(content, configObject, "cloud");
+	if (cloudObject) {
+		const cloudIndent = `${lineIndentAt(content, cloudObject.braceEnd)}  `;
+		const missingCloudProperties = [];
+		if (!findTopLevelPropertyRange(content, cloudObject.bodyStart, cloudObject.bodyEnd, "apiKey")) missingCloudProperties.push(`${cloudIndent}apiKey: { env: ${JSON.stringify(options.apiKeyEnv)} },`);
+		else {
+			const apiKeyObject = findObjectPropertyRange(content, cloudObject, "apiKey");
+			if (apiKeyObject && !findTopLevelPropertyRange(content, apiKeyObject.bodyStart, apiKeyObject.bodyEnd, "env")) {
+				content = insertObjectProperties(content, apiKeyObject, [`${lineIndentAt(content, apiKeyObject.braceEnd)}  env: ${JSON.stringify(options.apiKeyEnv)},`]);
+				configObject = findConfigObjectRange(content);
+				cloudObject = findObjectPropertyRange(content, configObject, "cloud");
+			}
+		}
+		if (!findTopLevelPropertyRange(content, cloudObject.bodyStart, cloudObject.bodyEnd, "deploy")) missingCloudProperties.push(`${cloudIndent}deploy: { enabled: true },`);
+		if (!findTopLevelPropertyRange(content, cloudObject.bodyStart, cloudObject.bodyEnd, "analytics")) missingCloudProperties.push(renderAnalyticsConfigProperty(cloudIndent));
+		if (!findTopLevelPropertyRange(content, cloudObject.bodyStart, cloudObject.bodyEnd, "publish")) missingCloudProperties.push(`${cloudIndent}publish: { mode: "draft-pr", baseBranch: "main" },`);
+		content = insertObjectProperties(content, cloudObject, missingCloudProperties);
+	}
+	configObject = findConfigObjectRange(content);
+	if (!configObject) throw new Error(`Could not re-read ${path.relative(options.rootDir, configPath)}.`);
+	if (!findTopLevelPropertyRange(content, configObject.bodyStart, configObject.bodyEnd, "analytics")) content = insertObjectProperties(content, configObject, [renderAnalyticsConfigProperty(`${lineIndentAt(content, configObject.braceEnd)}  `)]);
+	if (content !== original) fs.writeFileSync(configPath, content, "utf-8");
+	return {
+		configPath,
+		created: false,
+		updated: content !== original
+	};
+}
 function readExistingDocsJson(docsJsonPath) {
 	if (!fs.existsSync(docsJsonPath)) return void 0;
 	try {
@@ -564,6 +858,51 @@ async function syncCloudConfig(options = {}) {
 	console.log(`${pc.dim("api key env")} ${result.apiKeyEnv}`);
 	return result;
 }
+async function initCloudConfig(options = {}) {
+	const rootDir = options.rootDir ?? process.cwd();
+	const apiKeyEnv = normalizeEnvName(options.apiKeyEnv, DOCS_CLOUD_DEFAULT_API_KEY_ENV);
+	const configUpdate = ensureDocsConfigCloudInit({
+		rootDir,
+		configPath: options.configPath,
+		apiKeyEnv
+	});
+	const materialized = await materializeCloudConfig({
+		...options,
+		rootDir,
+		configPath: path.relative(rootDir, configUpdate.configPath)
+	});
+	return {
+		configPath: configUpdate.configPath,
+		docsJsonPath: materialized.docsJsonPath,
+		apiKeyEnv: materialized.apiKeyEnv,
+		analyticsProjectIdEnv: DOCS_CLOUD_DEFAULT_ANALYTICS_PROJECT_ID_ENV,
+		configCreated: configUpdate.created,
+		configUpdated: configUpdate.updated,
+		docsJsonCreated: materialized.created,
+		docsJsonUpdated: materialized.updated
+	};
+}
+async function runCloudInit(options = {}) {
+	const result = await initCloudConfig(options);
+	if (options.json) {
+		console.log(JSON.stringify(result, null, 2));
+		return result;
+	}
+	const relativeConfigPath = path.relative(process.cwd(), result.configPath) || "docs.config.ts";
+	const relativeDocsJsonPath = path.relative(process.cwd(), result.docsJsonPath) || DOCS_JSON_FILE;
+	const configAction = result.configCreated ? "Created" : result.configUpdated ? "Updated" : "Checked";
+	const docsJsonAction = result.docsJsonCreated ? "created" : result.docsJsonUpdated ? "updated" : "checked";
+	console.log(`${pc.green("ok")} ${configAction} ${pc.cyan(relativeConfigPath)}`);
+	console.log(`${pc.green("ok")} ${docsJsonAction} ${pc.cyan(relativeDocsJsonPath)}`);
+	console.log();
+	console.log(pc.bold("Add these env vars"));
+	console.log(`${pc.cyan(result.apiKeyEnv)}=${pc.dim("paste_your_docs_cloud_api_key")}`);
+	console.log(`${pc.cyan(result.analyticsProjectIdEnv)}=${pc.dim("paste_your_docs_cloud_project_id")}`);
+	console.log();
+	console.log(pc.dim("Use the same env vars in production. The API key value is never written to config."));
+	console.log(pc.dim(`Then run ${pc.cyan("pnpm dlx @farming-labs/docs deploy")}.`));
+	return result;
+}
 async function runCloudDeployment(options = {}) {
 	const rootDir = options.rootDir ?? process.cwd();
 	const spinner = createSpinner("Preparing Docs Cloud deployment", options);
@@ -625,6 +964,7 @@ function printCloudHelp() {
 ${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 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")}
@@ -633,6 +973,7 @@ ${pc.dim("Usage:")}
 
 ${pc.dim("Options:")}
   ${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 Docs Cloud API base URL
   ${pc.cyan("--api-key <key>")}           Use an API key directly; prefer ${pc.dim("cloud.apiKey.env")}
   ${pc.cyan("--json")}                    Print machine-readable output
@@ -644,10 +985,11 @@ ${pc.dim("Config example:")}
   cloud: {
     apiKey: { env: "DOCS_CLOUD_API_KEY" },
     deploy: { enabled: true },
+    analytics: { enabled: true, console: false, includeInputs: false },
     publish: { mode: "draft-pr", baseBranch: "main" },
   }
 `);
 }
 
 //#endregion
-export { printCloudHelp, runCloudDeploy, runCloudPreview, syncCloudConfig };
+export { printCloudHelp, runCloudDeploy, runCloudInit, runCloudPreview, syncCloudConfig };

package/package.json

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