@farm.js/cli 0.1.0-beta.5 → 0.1.0-beta.51

package/dist/index.js

@@ -1,52 +1,174 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_add_integration = require("./add-integration-Xc0p-k-m.js");
+const require_rolldown_runtime = require("./rolldown-runtime-VH7oDXx4.js");
+const require_add_integration = require("./add-integration-Bz7WjUfh.js");
 const require_build = require("./build.js");
+const require_telemetry = require("./telemetry.js");
 let _farm_js_core_server = require("@farm.js/core/server");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
-node_path = require_add_integration.__toESM(node_path);
+node_path = require_rolldown_runtime.__toESM(node_path);
 let child_process = require("child_process");
 let fs = require("fs");
 let path = require("path");
-path = require_add_integration.__toESM(path);
+path = require_rolldown_runtime.__toESM(path);
 let _farm_js_core = require("@farm.js/core");
 let node_child_process = require("node:child_process");
 let node_timers_promises = require("node:timers/promises");
 let picocolors = require("picocolors");
-picocolors = require_add_integration.__toESM(picocolors);
+picocolors = require_rolldown_runtime.__toESM(picocolors);
 let croner = require("croner");
+let node_module = require("node:module");
+let node_url = require("node:url");
 //#region src/deploy.ts
+var FarmDeployError = class extends Error {
+	constructor(code, platform, message, options) {
+		super(message);
+		this.name = "FarmDeployError";
+		this.code = code;
+		this.platform = platform;
+		this.cause = options?.cause;
+	}
+};
 /**
 * Deploy Farm.js application
 */
 async function deployFarm(options = {}) {
-	const root = options.root || process.cwd();
+	const { plan, deployConfig } = await resolveFarmDeployContext(options);
+	if (options.plan) {
+		_farm_js_core.logger.info(formatFarmDeployPlan(plan));
+		return plan;
+	}
+	_farm_js_core.logger.info(`🚀 Building with ${plan.preset} preset...`);
+	await require_build.buildFarm({
+		root: plan.root,
+		preset: plan.preset,
+		target: plan.target
+	});
+	if (!(0, fs.existsSync)(plan.outputDir)) throw new FarmDeployError("INVALID_BUILD_OUTPUT", plan.target, `Build output not found at ${plan.outputDir}. Please run 'farm build' first.`);
+	await deployPlatform(plan.target, plan.root, plan.outputDir, deployConfig, options.prod);
+	return plan;
+}
+async function createFarmDeployPlan(options = {}) {
+	return (await resolveFarmDeployContext(options)).plan;
+}
+function formatFarmDeployPlan(plan) {
+	return [
+		"FARM / DEPLOY PLAN",
+		"",
+		`Target:     ${plan.target}`,
+		`Preset:     ${plan.preset}`,
+		`Runtime:    ${plan.runtime}`,
+		`Output:     ${plan.outputDir}`,
+		`Production: ${plan.production ? "yes" : "no"}`,
+		"",
+		`1. ${plan.build.command}`,
+		`   cwd: ${plan.build.cwd}`,
+		`2. ${plan.deploy.command}`,
+		`   cwd: ${plan.deploy.cwd}`,
+		...plan.cloudflareAgent ? ["", `Cloudflare Agent config: ${plan.cloudflareAgent.configPath}${plan.cloudflareAgent.generated ? " (generated during build)" : ""}`] : []
+	].join("\n");
+}
+async function resolveFarmDeployContext(options) {
+	const root = path.default.resolve(options.root || process.cwd());
 	const mode = "production";
 	const userConfig = await (0, _farm_js_core.loadConfig)(root, void 0, mode);
-	const config = userConfig ? await (0, _farm_js_core.resolveConfig)(userConfig, mode) : void 0;
+	const config = await (0, _farm_js_core.resolveConfig)({
+		root,
+		...userConfig
+	}, mode);
 	const cliTarget = options.vercel ? "vercel" : options.cloudflare ? "cloudflare" : options.netlify ? "netlify" : void 0;
-	const platform = (0, _farm_js_core.normalizeDeployTarget)(cliTarget || config?.deploy.target);
-	if (platform !== "vercel" && platform !== "cloudflare" && platform !== "netlify") {
-		_farm_js_core.logger.error("Please specify a deployment target with --vercel, --cloudflare, --netlify, or farm.config deploy.target.");
-		process.exit(1);
-	}
+	const platform = (0, _farm_js_core.normalizeDeployTarget)(cliTarget || config.deploy.target);
+	if (platform !== "vercel" && platform !== "cloudflare" && platform !== "netlify") throw new Error("Please specify a deployment target with --vercel, --cloudflare, --netlify, or farm.config deploy.target.");
+	const configuredPreset = userConfig?.deploy?.preset || userConfig?.preset;
+	const configuredPresetTarget = (0, _farm_js_core.getDeployTargetForPreset)(configuredPreset);
+	const configuredTarget = (0, _farm_js_core.normalizeDeployTarget)(userConfig?.deploy?.target);
+	const presetMatchesPlatform = Boolean(configuredPreset) && (configuredPresetTarget === platform || !configuredPresetTarget && configuredTarget === platform);
+	if (cliTarget && configuredPreset && !presetMatchesPlatform) _farm_js_core.logger.warn(`Configured preset "${configuredPreset}" targets ${configuredPresetTarget || "an unknown platform"}; using the "${(0, _farm_js_core.getPresetForDeployTarget)(platform)}" preset because --${cliTarget} was passed.`);
 	const deployConfig = (0, _farm_js_core.resolveDeployConfig)(userConfig || {}, {
 		target: platform,
-		preset: cliTarget ? userConfig?.deploy?.preset || userConfig?.preset || (0, _farm_js_core.getPresetForDeployTarget)(platform) : void 0
+		preset: cliTarget ? presetMatchesPlatform ? configuredPreset : (0, _farm_js_core.getPresetForDeployTarget)(platform) : void 0
 	});
 	const preset = deployConfig.preset || (0, _farm_js_core.getPresetForDeployTarget)(platform) || "node-server";
-	_farm_js_core.logger.info(`🚀 Building with ${preset} preset...`);
-	await require_build.buildFarm({
-		root,
-		preset
-	});
 	const nitroOutput = (0, _farm_js_core.resolveDeployOutputPath)(root, deployConfig.outputDir);
-	if (!(0, fs.existsSync)(nitroOutput)) {
-		_farm_js_core.logger.error(`Build output not found at ${nitroOutput}. Please run 'farm build' first.`);
-		process.exit(1);
+	const cloudflareAgent = platform === "cloudflare" ? resolveCloudflareAgentDeployPlan(root) || resolveConfiguredCloudflareAgentDeployPlan(root, config.integrations) : void 0;
+	const deploy = createDeployCommand(platform, root, nitroOutput, deployConfig, options.prod, cloudflareAgent);
+	return {
+		plan: {
+			root: path.default.resolve(root),
+			target: platform,
+			preset,
+			runtime: (0, _farm_js_core.getFarmPresetRuntime)(preset),
+			outputDir: nitroOutput,
+			production: platform === "netlify" || Boolean(options.prod),
+			build: {
+				command: `farm build --preset ${preset}`,
+				cwd: path.default.resolve(root)
+			},
+			deploy,
+			...cloudflareAgent ? { cloudflareAgent } : {}
+		},
+		deployConfig
+	};
+}
+function createDeployCommand(platform, root, outputDir, deployConfig, prod, cloudflareAgent) {
+	if (platform === "vercel") {
+		const args = [
+			"deploy",
+			"--prebuilt",
+			"--yes",
+			...prod ? ["--prod"] : []
+		];
+		return {
+			command: formatCommand$1("vercel", args),
+			cwd: path.default.resolve(root),
+			executable: "vercel",
+			args
+		};
+	}
+	if (platform === "netlify") {
+		const args = createNetlifyDeployArgs(deployConfig.netlify?.site);
+		return {
+			command: formatCommand$1("netlify", args),
+			cwd: outputDir,
+			executable: "netlify",
+			args
+		};
+	}
+	if (cloudflareAgent) {
+		const args = [
+			"deploy",
+			"--config",
+			cloudflareAgent.configPath,
+			...cloudflareAgent.environment ? ["--env", cloudflareAgent.environment] : []
+		];
+		return {
+			command: formatCommand$1("wrangler", args),
+			cwd: path.default.resolve(root),
+			executable: "wrangler",
+			args
+		};
 	}
-	await deployPlatform(platform, root, nitroOutput, deployConfig, options.prod);
+	const args = [
+		"pages",
+		"deploy",
+		".",
+		`--project-name=${deployConfig.cloudflare?.projectName || deployConfig.projectName || "farm-app"}`
+	];
+	return {
+		command: formatCommand$1("wrangler", args),
+		cwd: outputDir,
+		executable: "wrangler",
+		args
+	};
+}
+function createNetlifyDeployArgs(site) {
+	return [
+		"deploy",
+		"--prod",
+		"--dir=.",
+		...site ? [`--site=${site}`] : []
+	];
 }
 /**
 * Deploy using platform's native CLI (user credentials)
@@ -68,19 +190,20 @@ async function deployPlatform(platform, root, outputDir, deployConfig, prod) {
 async function deployVercel(root, outputDir, prod) {
 	_farm_js_core.logger.info("🚀 Deploying to Vercel...");
 	try {
-		(0, child_process.execSync)("vercel --version", { stdio: "ignore" });
-	} catch {
-		_farm_js_core.logger.error("❌ Vercel CLI is not installed.");
-		_farm_js_core.logger.info("💡 Install it with: npm i -g vercel");
-		process.exit(1);
+		(0, child_process.execFileSync)("vercel", ["--version"], {
+			stdio: "ignore",
+			cwd: root
+		});
+	} catch (error) {
+		throw new FarmDeployError("CLI_NOT_INSTALLED", "vercel", "Vercel CLI is not installed. Install it with: npm i -g vercel", { cause: error });
 	}
 	try {
-		(0, child_process.execSync)("vercel whoami", { stdio: "ignore" });
-	} catch {
-		_farm_js_core.logger.warn("⚠️  Not logged in to Vercel.");
-		_farm_js_core.logger.info("💡 Please run: vercel login");
-		_farm_js_core.logger.info("   Then run: farm deploy --vercel");
-		process.exit(1);
+		(0, child_process.execFileSync)("vercel", ["whoami"], {
+			stdio: "ignore",
+			cwd: root
+		});
+	} catch (error) {
+		throw new FarmDeployError("CLI_NOT_AUTHENTICATED", "vercel", "Vercel CLI is not authenticated. Run 'vercel login', then retry the deployment.", { cause: error });
 	}
 	try {
 		const { existsSync, statSync, readdirSync } = await import("fs");
@@ -89,14 +212,8 @@ async function deployVercel(root, outputDir, prod) {
 		const configFile = path.default.join(outputDir, "config.json");
 		const serverIndex = path.default.join(functionsDir, "index.mjs");
 		_farm_js_core.logger.info("🔍 Verifying deployment structure...");
-		if (!existsSync(functionsDir)) {
-			_farm_js_core.logger.error(`❌ Functions directory not found at ${functionsDir}`);
-			process.exit(1);
-		}
-		if (!existsSync(serverIndex)) {
-			_farm_js_core.logger.error(`❌ Server entry point not found at ${serverIndex}`);
-			process.exit(1);
-		}
+		if (!existsSync(functionsDir)) throw new FarmDeployError("INVALID_BUILD_OUTPUT", "vercel", `Functions directory not found at ${functionsDir}.`);
+		if (!existsSync(serverIndex)) throw new FarmDeployError("INVALID_BUILD_OUTPUT", "vercel", `Server entry point not found at ${serverIndex}.`);
 		_farm_js_core.logger.info(`✅ Functions directory: ${functionsDir}`);
 		if (!existsSync(staticDir)) _farm_js_core.logger.warn(`⚠️  Static directory not found at ${staticDir}`);
 		else {
@@ -177,14 +294,19 @@ async function deployVercel(root, outputDir, prod) {
 		_farm_js_core.logger.info(`   Static: ${staticDir}`);
 		_farm_js_core.logger.info(`   Config: ${configFile}`);
 		_farm_js_core.logger.info("📤 Uploading to Vercel...");
-		(0, child_process.execSync)(`vercel deploy --prebuilt --yes${prod ? " --prod" : ""}`, {
+		(0, child_process.execFileSync)("vercel", [
+			"deploy",
+			"--prebuilt",
+			"--yes",
+			...prod ? ["--prod"] : []
+		], {
 			stdio: "inherit",
 			cwd: root
 		});
 		_farm_js_core.logger.success("✅ Deployed to Vercel successfully!");
 	} catch (error) {
-		_farm_js_core.logger.error(`❌ Failed to deploy to Vercel: ${error.message}`);
-		process.exit(1);
+		if (error instanceof FarmDeployError) throw error;
+		throw new FarmDeployError("DEPLOY_FAILED", "vercel", `Failed to deploy to Vercel: ${getErrorMessage(error)}`, { cause: error });
 	}
 }
 /** Deploy to a composed Worker or fall back to Cloudflare Pages. */
@@ -205,8 +327,7 @@ async function deployCloudflare(root, outputDir, projectName) {
 			});
 			_farm_js_core.logger.success("✅ Deployed Farm and Cloudflare Agents successfully!");
 		} catch (error) {
-			_farm_js_core.logger.error(`❌ Failed to deploy to Cloudflare: ${error.message}`);
-			process.exit(1);
+			throw new FarmDeployError("DEPLOY_FAILED", "cloudflare", `Failed to deploy to Cloudflare: ${getErrorMessage(error)}`, { cause: error });
 		}
 		return;
 	}
@@ -224,8 +345,7 @@ async function deployCloudflare(root, outputDir, projectName) {
 		});
 		_farm_js_core.logger.success("✅ Deployed to Cloudflare Pages successfully!");
 	} catch (error) {
-		_farm_js_core.logger.error(`❌ Failed to deploy to Cloudflare: ${error.message}`);
-		process.exit(1);
+		throw new FarmDeployError("DEPLOY_FAILED", "cloudflare", `Failed to deploy to Cloudflare: ${getErrorMessage(error)}`, { cause: error });
 	}
 }
 /** Read the trusted Workers deployment handoff emitted by @farm.js/cf-agent. */
@@ -251,16 +371,34 @@ function resolveCloudflareAgentDeployPlan(root) {
 		...typeof environment === "string" ? { environment: environment.trim() } : {}
 	};
 }
+function resolveConfiguredCloudflareAgentDeployPlan(root, integrations) {
+	const integration = Object.values(integrations || {}).find((value) => isRecord(value) && value.category === "agent" && value.type === "cloudflare" && value.serverRuntime === false);
+	if (!isRecord(integration) || !isRecord(integration.instance)) return void 0;
+	const configuredPath = integration.instance.config;
+	if (typeof configuredPath !== "string" || !configuredPath.trim()) return void 0;
+	const projectRoot = path.default.resolve(root);
+	const sourceConfigPath = path.default.resolve(projectRoot, configuredPath);
+	assertPathInsideProject(projectRoot, sourceConfigPath, "Cloudflare Agents source config");
+	const configPath = path.default.join(path.default.dirname(sourceConfigPath), ".farm-cf-agent.wrangler.jsonc");
+	const environment = integration.instance.environment;
+	return {
+		configPath,
+		...typeof environment === "string" && environment.trim() ? { environment: environment.trim() } : {},
+		generated: true
+	};
+}
+function assertPathInsideProject(projectRoot, candidate, label) {
+	const relativePath = path.default.relative(projectRoot, candidate);
+	if (relativePath === ".." || relativePath.startsWith(`..${path.default.sep}`) || path.default.isAbsolute(relativePath)) throw new Error(`${label} must stay inside the Farm project root.`);
+}
 function assertWranglerInstalled(root) {
 	try {
 		(0, child_process.execFileSync)("wrangler", ["--version"], {
 			stdio: "ignore",
 			cwd: root
 		});
-	} catch {
-		_farm_js_core.logger.error("❌ Wrangler CLI is not installed.");
-		_farm_js_core.logger.info("💡 Install it in this project with: npm i -D wrangler");
-		process.exit(1);
+	} catch (error) {
+		throw new FarmDeployError("CLI_NOT_INSTALLED", "cloudflare", "Wrangler CLI is not installed. Install it in this project with: npm i -D wrangler", { cause: error });
 	}
 }
 function isRecord(value) {
@@ -272,22 +410,33 @@ function isRecord(value) {
 async function deployNetlify(root, outputDir, site) {
 	_farm_js_core.logger.info("🚀 Deploying to Netlify...");
 	try {
-		(0, child_process.execSync)("netlify --version", { stdio: "ignore" });
-	} catch {
-		_farm_js_core.logger.error("❌ Netlify CLI is not installed.");
-		_farm_js_core.logger.info("💡 Install it with: npm i -g netlify-cli");
-		process.exit(1);
+		(0, child_process.execFileSync)("netlify", ["--version"], {
+			stdio: "ignore",
+			cwd: root
+		});
+	} catch (error) {
+		throw new FarmDeployError("CLI_NOT_INSTALLED", "netlify", "Netlify CLI is not installed. Install it with: npm i -g netlify-cli", { cause: error });
 	}
 	try {
-		process.chdir(outputDir);
-		const siteFlag = site ? ` --site=${site}` : "";
-		(0, child_process.execSync)(`netlify deploy --prod --dir=.${siteFlag}`, { stdio: "inherit" });
+		(0, child_process.execFileSync)("netlify", createNetlifyDeployArgs(site), {
+			stdio: "inherit",
+			cwd: outputDir
+		});
 		_farm_js_core.logger.success("✅ Deployed to Netlify successfully!");
 	} catch (error) {
-		_farm_js_core.logger.error(`❌ Failed to deploy to Netlify: ${error.message}`);
-		process.exit(1);
+		throw new FarmDeployError("DEPLOY_FAILED", "netlify", `Failed to deploy to Netlify: ${getErrorMessage(error)}`, { cause: error });
 	}
 }
+function formatCommand$1(executable, args) {
+	return [executable, ...args].map(formatCommandArgument).join(" ");
+}
+function formatCommandArgument(argument) {
+	if (/^[A-Za-z0-9_./:=@+-]+$/.test(argument)) return argument;
+	return `'${argument.replace(/'/g, `'"'"'`)}'`;
+}
+function getErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 //#endregion
 //#region src/preview-gateway.ts
 const DEFAULT_GATEWAY_URL = "https://preview.farming-labs.dev";
@@ -310,10 +459,12 @@ const HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
 function createPreviewGatewayPlan(target, options = {}) {
 	const requestedName = sanitizePreviewName$1(options.name || process.env.FARM_PREVIEW_NAME) || randomPreviewName$1();
 	const gatewayUrl = normalizeGatewayUrl(options.gatewayUrl || process.env.FARM_PREVIEW_GATEWAY_URL || DEFAULT_GATEWAY_URL);
+	const relayUrl = normalizeRelayUrl(process.env.FARM_PREVIEW_RELAY_URL || gatewayUrl);
 	const requestedHostname = `${requestedName}.${normalizePreviewDomain$1(process.env.FARM_PREVIEW_DOMAIN || DEFAULT_PREVIEW_DOMAIN)}`;
 	return {
 		provider: "farm-gateway",
 		gatewayUrl,
+		relayUrl,
 		target,
 		requestedName,
 		requestedHostname,
@@ -478,6 +629,7 @@ async function closeGatewaySession(plan, session) {
 function formatGatewayPlan(plan) {
 	return [
 		`Gateway: ${plan.gatewayUrl}`,
+		`Relay:   ${plan.relayUrl}`,
 		`Local:   ${plan.target.localUrl}`,
 		`Public:  ${plan.requestedPublicUrl}`
 	].join("\n");
@@ -489,6 +641,17 @@ function formatRequestPath(path) {
 function normalizeGatewayUrl(value) {
 	return value.replace(/\/+$/, "");
 }
+function normalizeRelayUrl(value) {
+	const url = new URL(value);
+	if (url.protocol === "http:") url.protocol = "ws:";
+	if (url.protocol === "https:") url.protocol = "wss:";
+	if (url.protocol !== "ws:" && url.protocol !== "wss:") throw new Error(`Preview relay must use ws or wss, received ${url.protocol}`);
+	const pathname = url.pathname.replace(/\/+$/, "");
+	url.pathname = pathname.endsWith("/agent") ? pathname : `${pathname}/agent`;
+	url.search = "";
+	url.hash = "";
+	return url.toString();
+}
 function normalizePreviewDomain$1(value) {
 	return value.replace(/^https?:\/\//, "").replace(/^\.*/, "").replace(/\/*$/, "");
 }
@@ -500,6 +663,39 @@ function randomPreviewName$1() {
 	return `farm-${Math.random().toString(36).slice(2, 8)}`;
 }
 //#endregion
+//#region src/preview-native.ts
+async function runNativePreviewTunnel(plan, options = {}) {
+	const runtime = options.runtime || await loadNativeTunnel();
+	const session = await runtime.startPreviewAgent(plan.relayUrl, plan.requestedName, plan.target.localUrl);
+	let stopping = false;
+	const stop = () => {
+		if (stopping) return;
+		stopping = true;
+		runtime.stopPreviewAgent(session.sessionId);
+	};
+	process.once("SIGINT", stop);
+	process.once("SIGTERM", stop);
+	_farm_js_core.logger.success("Preview URL ready.");
+	_farm_js_core.logger.info(`Public: ${session.publicUrl}`);
+	_farm_js_core.logger.info("Forwarding requests through the native tunnel until Ctrl+C.");
+	try {
+		if (!await runtime.waitPreviewAgent(session.sessionId)) throw new Error("The native preview tunnel stopped before its lifecycle could be observed.");
+		return session;
+	} finally {
+		process.removeListener("SIGINT", stop);
+		process.removeListener("SIGTERM", stop);
+		await runtime.stopPreviewAgent(session.sessionId).catch(() => false);
+	}
+}
+async function loadNativeTunnel() {
+	try {
+		return await import("@farm.js/tunnel");
+	} catch (error) {
+		const reason = error instanceof Error ? ` ${error.message}` : "";
+		throw new Error(`Could not load @farm.js/tunnel for this platform. Reinstall @farm.js/cli so its native platform package is restored.${reason}`);
+	}
+}
+//#endregion
 //#region src/preview.ts
 const DEFAULT_PREVIEW_PORTS = [
 	3e3,
@@ -523,15 +719,26 @@ async function previewFarm(options = {}) {
 				plan
 			};
 		}
-		_farm_js_core.logger.info(`Gateway: ${plan.gatewayUrl}`);
-		_farm_js_core.logger.info("Opening Farm preview gateway session...");
-		const session = await runPreviewGateway(plan, { timeoutMs: options.timeoutMs });
-		return {
-			target,
-			plan,
-			publicUrl: session.publicUrl,
-			session
-		};
+		_farm_js_core.logger.info(`Relay: ${plan.relayUrl}`);
+		_farm_js_core.logger.info("Opening native Farm preview tunnel...");
+		try {
+			const session = await runNativePreviewTunnel(plan);
+			return {
+				target,
+				plan,
+				publicUrl: session.publicUrl,
+				session
+			};
+		} catch (error) {
+			_farm_js_core.logger.warn(`Native preview relay unavailable; using compatibility gateway polling.${formatPreviewError(error)}`);
+			const session = await runPreviewGateway(plan, { timeoutMs: options.timeoutMs });
+			return {
+				target,
+				plan,
+				publicUrl: session.publicUrl,
+				session
+			};
+		}
 	}
 	const plan = createPreviewTunnelPlan(target, options);
 	if (options.dryRun) {
@@ -549,6 +756,9 @@ async function previewFarm(options = {}) {
 		publicUrl: await runPreviewTunnel(plan, options.timeoutMs ?? 3e4)
 	};
 }
+function formatPreviewError(error) {
+	return error instanceof Error && error.message ? ` ${error.message}` : "";
+}
 function shouldUseManagedGateway(options) {
 	if (options.provider === "farm" || process.env.FARM_PREVIEW_PROVIDER === "farm") return true;
 	if (options.provider === "local" || process.env.FARM_PREVIEW_PROVIDER === "local") return false;
@@ -799,10 +1009,20 @@ function normalizePreviewDomain(value) {
 }
 //#endregion
 //#region src/generate.ts
+var FarmGeneratedArtifactsStaleError = class extends Error {
+	constructor(root, stalePaths) {
+		const normalizedPaths = [...new Set(stalePaths)].sort();
+		const relativePaths = normalizedPaths.map((filePath) => node_path.default.relative(root, filePath));
+		super(`Generated types are stale:\n${relativePaths.map((filePath) => `  - ${filePath}`).join("\n")}\nRun farm generate and commit the updated files.`);
+		this.name = "FarmGeneratedArtifactsStaleError";
+		this.stalePaths = normalizedPaths;
+	}
+};
 const PRISMA_GENERATED_START = "// Farm.js integrations generated schema: start";
 const PRISMA_GENERATED_END = "// Farm.js integrations generated schema: end";
 async function generateFarmArtifacts(options = {}) {
 	const root = node_path.default.resolve(options.root || process.cwd());
+	if (options.check && hasSchemaOptions(options)) throw new Error("--check verifies generated framework types and cannot be combined with schema output options.");
 	const userConfig = await (0, _farm_js_core.loadConfig)(root, options.configPath, "development");
 	if (!userConfig && hasSchemaOptions(options)) throw new Error("No Farm config found. Please create farm.config.ts or config.ts.");
 	const resolvedConfig = await (0, _farm_js_core.resolveConfig)({
@@ -810,34 +1030,28 @@ async function generateFarmArtifacts(options = {}) {
 		...userConfig
 	}, "development");
 	const extraRoutes = [...resolvedConfig.openapi?.enabled && resolvedConfig.openapi.route ? [resolvedConfig.openapi.route] : [], ...(0, _farm_js_core.getFarmDocsRouteTypeEntries)(resolvedConfig.docs)];
-	await (0, _farm_js_core.generateRouteTypes)({
+	const typeArtifacts = await (0, _farm_js_core.generateFarmTypeArtifacts)({
 		root: resolvedConfig.root,
 		srcDir: resolvedConfig.srcDir,
+		configPath: options.configPath,
+		layers: resolvedConfig.layers,
 		extraRoutes,
-		suppressLintOnLink: resolvedConfig.suppressLintOnLink
-	});
-	await (0, _farm_js_core.generateEnvTypes)({
-		root: resolvedConfig.root,
-		srcDir: resolvedConfig.srcDir,
-		configPath: options.configPath
-	});
-	const appDir = node_path.default.join(resolvedConfig.root, resolvedConfig.srcDir, "app");
-	const apiGenerator = new _farm_js_core.APITypeGenerator(appDir);
-	const apiRoutes = apiGenerator.scanAPIRoutes();
-	const apiTypesPath = node_path.default.join(resolvedConfig.root, resolvedConfig.srcDir, "lib", "api.generated.ts");
-	await (0, node_fs_promises.mkdir)(node_path.default.dirname(apiTypesPath), { recursive: true });
-	await (0, node_fs_promises.writeFile)(apiTypesPath, apiGenerator.generateAPIRouter(apiRoutes), "utf8");
-	if (resolvedConfig.i18n.enabled) await (0, _farm_js_core.generateFarmI18nTypes)({
-		root: resolvedConfig.root,
-		srcDir: resolvedConfig.srcDir,
-		config: resolvedConfig.i18n
+		suppressLintOnLink: resolvedConfig.suppressLintOnLink,
+		componentExtensions: resolvedConfig.renderer.componentExtensions,
+		i18nConfig: resolvedConfig.i18n,
+		check: options.check
 	});
-	_farm_js_core.logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types (${apiRoutes.length} API route${apiRoutes.length === 1 ? "" : "s"}).`);
+	if (options.check) {
+		if (typeArtifacts.stalePaths.length) throw new FarmGeneratedArtifactsStaleError(root, typeArtifacts.stalePaths);
+		_farm_js_core.logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types are up to date.`);
+		return typeArtifacts;
+	}
+	_farm_js_core.logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types (${typeArtifacts.apiRoutes.length} API route${typeArtifacts.apiRoutes.length === 1 ? "" : "s"}).`);
 	const schemas = (0, _farm_js_core.getIntegrationSchemas)(resolvedConfig.integrations);
 	const schemaEntries = Object.entries(schemas);
 	if (!schemaEntries.length) {
 		if (hasSchemaOptions(options)) _farm_js_core.logger.warn("No integration schemas were found in the current Farm config.");
-		return;
+		return typeArtifacts;
 	}
 	const packageManifest = await readPackageManifest(root);
 	const schemaOptionsExplicit = hasSchemaOptions(options);
@@ -847,12 +1061,12 @@ async function generateFarmArtifacts(options = {}) {
 	} catch (error) {
 		if (schemaOptionsExplicit) throw error;
 		_farm_js_core.logger.warn(`Integration schemas were found, but Farm could not choose a schema target automatically: ${error.message}`);
-		return;
+		return typeArtifacts;
 	}
 	if (!orm) {
 		if (!schemaOptionsExplicit) {
 			_farm_js_core.logger.warn("Integration schemas were found, but no data layer was detected. Pass --orm prisma|drizzle|postgres|mysql|sqlite|mongodb to generate schema artifacts.");
-			return;
+			return typeArtifacts;
 		}
 		throw new Error("Could not auto-detect a schema target. Pass one explicitly with --orm prisma|drizzle|postgres|mysql|sqlite|mongodb.");
 	}
@@ -863,7 +1077,7 @@ async function generateFarmArtifacts(options = {}) {
 			if (!(0, node_fs.existsSync)(schemaPath)) throw new Error(`Prisma target was selected but no schema file was found at ${schemaPath}. Create prisma/schema.prisma or pass --output.`);
 			await writePrismaSchema(schemaPath, collectedModels);
 			_farm_js_core.logger.success(`Generated Prisma integration schema in ${node_path.default.relative(root, schemaPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "drizzle": {
 			const dialect = options.dialect ?? await detectDrizzleDialect(root, packageManifest) ?? void 0;
@@ -871,7 +1085,7 @@ async function generateFarmArtifacts(options = {}) {
 			const outputPath = options.output ? node_path.default.resolve(root, options.output) : node_path.default.join(root, "farm-integrations.generated.ts");
 			await writeGeneratedFile(outputPath, generateDrizzleSchema(collectedModels, dialect));
 			_farm_js_core.logger.success(`Generated Drizzle integration schema in ${node_path.default.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "postgres":
 		case "mysql":
@@ -879,13 +1093,13 @@ async function generateFarmArtifacts(options = {}) {
 			const outputPath = options.output ? node_path.default.resolve(root, options.output) : node_path.default.join(root, `farm-integrations.generated.${orm}.sql`);
 			await writeGeneratedFile(outputPath, generateSqlSchema(collectedModels, orm));
 			_farm_js_core.logger.success(`Generated ${orm} integration schema in ${node_path.default.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "mongodb": {
 			const outputPath = options.output ? node_path.default.resolve(root, options.output) : node_path.default.join(root, "farm-integrations.generated.mongodb.ts");
 			await writeGeneratedFile(outputPath, generateMongoBootstrap(collectedModels));
 			_farm_js_core.logger.success(`Generated MongoDB integration bootstrap in ${node_path.default.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 	}
 }
@@ -1070,7 +1284,7 @@ function cloneSchemaModel(model) {
 async function writePrismaSchema(schemaPath, models) {
 	const source = await (0, node_fs_promises.readFile)(schemaPath, "utf8");
 	const generated = createPrismaGeneratedBlock(generatePrismaSchema(models));
-	const pattern = new RegExp(`${escapeRegExp(PRISMA_GENERATED_START)}[\\s\\S]*?${escapeRegExp(PRISMA_GENERATED_END)}`, "m");
+	const pattern = new RegExp(`${escapeRegExp$1(PRISMA_GENERATED_START)}[\\s\\S]*?${escapeRegExp$1(PRISMA_GENERATED_END)}`, "m");
 	const nextSource = pattern.test(source) ? source.replace(pattern, generated) : `${source.trimEnd()}\n\n${generated}\n`;
 	await (0, node_fs_promises.writeFile)(schemaPath, nextSource, "utf8");
 }
@@ -1398,16 +1612,17 @@ function toCamelCase(value) {
 function escapeString(value) {
 	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/'/g, "''");
 }
-function escapeRegExp(value) {
+function escapeRegExp$1(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //#endregion
 //#region src/doctor.ts
-const ROUTE_EXTENSIONS = [
+const ROUTE_EXTENSIONS$1 = [
 	"ts",
 	"tsx",
 	"js",
 	"jsx",
+	"vue",
 	"md",
 	"mdx"
 ];
@@ -1425,7 +1640,7 @@ async function runFarmDoctor(options = {}) {
 	const root = node_path.default.resolve(options.root || process.cwd());
 	const liveTarget = resolveLiveTarget(options);
 	let liveError;
-	if (!options.offline) try {
+	if (!options.offline && !options.fix) try {
 		return createLiveReport(await fetchLiveSnapshot(liveTarget, options), liveTarget, options.now);
 	} catch (error) {
 		liveError = formatError$2(error);
@@ -1472,6 +1687,13 @@ function formatFarmDoctorReport(report, options = {}) {
 		`${report.summary.fail} failed`,
 		`${report.summary.info} info`
 	].join(" / ");
+	if (report.fixes?.length) {
+		lines.push("", color.bold("FIXED"));
+		for (const fix of report.fixes) {
+			lines.push(`  ${color.green("✓")} ${fix.title}`);
+			lines.push(`    ${color.dim(fix.filePath)}`);
+		}
+	}
 	lines.push("", `${color.bold("SUMMARY")}  ${summary}`);
 	if (report.target?.devtoolsUrl) lines.push(`${color.bold("DEVTOOLS")} ${report.target.devtoolsUrl}`);
 	return lines.join("\n");
@@ -1571,9 +1793,10 @@ async function createProjectReport(root, options) {
 			action: "Add farm.config.ts and export defineConfig({...})."
 		});
 		else {
+			const configRoot = node_path.default.resolve(root, userConfig.root || ".");
 			config = await (0, _farm_js_core.resolveConfig)({
-				root,
-				...userConfig
+				...userConfig,
+				root: configRoot
 			}, "development");
 			const configFile = findConfigFile(root, options.configPath);
 			checks.push({
@@ -1597,9 +1820,41 @@ async function createProjectReport(root, options) {
 		report.target = collectDeploymentChecks(config, userConfig, checks);
 		collectCronChecks(config, options.env || process.env, checks);
 	}
+	if (config && options.fix) {
+		const fixes = applySafeProjectFixes(root, config, checks);
+		if (fixes.length) {
+			const refreshed = await createProjectReport(root, {
+				...options,
+				fix: false
+			});
+			refreshed.fixes = fixes;
+			return refreshed;
+		}
+		report.fixes = [];
+	}
 	finalizeReport(report);
 	return report;
 }
+function applySafeProjectFixes(root, config, checks) {
+	const fixes = [];
+	if (checks.some((check) => check.code === "ROOT_LAYOUT_MISSING")) {
+		const rendererExtension = config.renderer.componentExtensions?.[0] || ".tsx";
+		const layoutPath = node_path.default.join(config.root, config.srcDir, "app", `layout${rendererExtension}`);
+		if (!(0, node_fs.existsSync)(layoutPath)) {
+			(0, node_fs.mkdirSync)(node_path.default.dirname(layoutPath), { recursive: true });
+			(0, node_fs.writeFileSync)(layoutPath, config.renderer.name === "vue" ? `<script setup lang="ts">\ndefineOptions({ inheritAttrs: false });\n<\/script>\n\n<template>\n  <slot />\n</template>\n` : config.renderer.name === "solid" ? `import type { ParentProps } from "solid-js";\n\nexport default function RootLayout(props: ParentProps) {\n  return <>{props.children}</>;\n}\n` : `import type { ReactNode } from "react";\n\nexport default function RootLayout({ children }: { children: ReactNode }) {\n  return (\n    <html lang="en">\n      <body>{children}</body>\n    </html>\n  );\n}\n`, {
+				encoding: "utf8",
+				flag: "wx"
+			});
+			fixes.push({
+				code: "ROOT_LAYOUT_CREATED",
+				title: "Created the missing root layout",
+				filePath: node_path.default.relative(root, layoutPath)
+			});
+		}
+	}
+	return fixes;
+}
 function collectNodeCheck(checks) {
 	const major = Number(process.versions.node.split(".")[0]);
 	checks.push(major >= 18 ? {
@@ -1659,8 +1914,8 @@ function collectPackageCheck(root, checks) {
 function collectRouterChecks(config, checks) {
 	const sources = (0, _farm_js_core.getFarmSourceRoots)(config);
 	const appDirectories = sources.map((source) => node_path.default.join(source.root, source.srcDir, "app"));
-	const hasPages = appDirectories.some((directory) => containsFile(directory, /^page\.(?:ts|tsx|js|jsx|md|mdx)$/));
-	const hasProgrammaticRoutes = sources.some((source) => ROUTE_EXTENSIONS.some((extension) => (0, node_fs.existsSync)(node_path.default.join(source.root, source.srcDir, `farm.routes.${extension}`))));
+	const hasPages = appDirectories.some((directory) => containsFile(directory, /^page\.(?:ts|tsx|js|jsx|vue|md|mdx)$/));
+	const hasProgrammaticRoutes = sources.some((source) => ROUTE_EXTENSIONS$1.some((extension) => (0, node_fs.existsSync)(node_path.default.join(source.root, source.srcDir, `farm.routes.${extension}`))));
 	checks.push(hasPages || hasProgrammaticRoutes ? {
 		status: "pass",
 		code: "APP_ROUTER_READY",
@@ -1673,7 +1928,8 @@ function collectRouterChecks(config, checks) {
 		message: `Farm found no page modules under ${config.srcDir}/app.`,
 		action: `Add ${config.srcDir}/app/page.tsx or ${config.srcDir}/farm.routes.tsx.`
 	});
-	const hasRootLayout = appDirectories.some((directory) => ROUTE_EXTENSIONS.some((extension) => (0, node_fs.existsSync)(node_path.default.join(directory, `layout.${extension}`))));
+	const hasRootLayout = appDirectories.some((directory) => ROUTE_EXTENSIONS$1.some((extension) => (0, node_fs.existsSync)(node_path.default.join(directory, `layout.${extension}`))));
+	const suggestedLayoutExtension = config.renderer.componentExtensions?.[0] || ".tsx";
 	checks.push(hasRootLayout ? {
 		status: "pass",
 		code: "ROOT_LAYOUT_READY",
@@ -1684,7 +1940,7 @@ function collectRouterChecks(config, checks) {
 		code: "ROOT_LAYOUT_MISSING",
 		title: "Root layout is missing",
 		message: "The application has no shared root layout.",
-		action: `Add ${config.srcDir}/app/layout.tsx.`
+		action: `Add ${config.srcDir}/app/layout${suggestedLayoutExtension}.`
 	});
 }
 function collectDeploymentChecks(config, userConfig, checks) {
@@ -1743,7 +1999,7 @@ function hasCronRoute(config, job) {
 	const relative = job.path.replace(/^\/+/, "").replace(/^api\//, "");
 	return (0, _farm_js_core.getFarmSourceRoots)(config).some((source) => {
 		const directory = node_path.default.join(source.root, source.srcDir, "app", "api", relative);
-		return ROUTE_EXTENSIONS.some((extension) => (0, node_fs.existsSync)(node_path.default.join(directory, `route.${extension}`)));
+		return ROUTE_EXTENSIONS$1.some((extension) => (0, node_fs.existsSync)(node_path.default.join(directory, `route.${extension}`)));
 	});
 }
 function containsFile(directory, pattern) {
@@ -1811,6 +2067,415 @@ function formatCount$1(value, noun) {
 	return `${value} ${noun}${value === 1 ? "" : "s"}`;
 }
 //#endregion
+//#region src/explain.ts
+const ROUTE_EXTENSIONS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js",
+	"vue",
+	"mdx",
+	"md"
+];
+const MIDDLEWARE_EXTENSIONS = [
+	"ts",
+	"tsx",
+	"js",
+	"jsx",
+	"mjs",
+	"cjs"
+];
+const SOCIAL_IMAGE_EXTENSIONS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js",
+	"png",
+	"jpg",
+	"jpeg",
+	"gif",
+	"webp"
+];
+async function explainFarmRoute(pathname, options = {}) {
+	const root = node_path.default.resolve(options.root || process.cwd());
+	const userConfig = await (0, _farm_js_core.loadConfig)(root, options.configPath, "production");
+	const config = await (0, _farm_js_core.resolveConfig)({
+		root,
+		...userConfig
+	}, "production");
+	const normalizedPathname = normalizePathname(pathname, config.basePath || "/");
+	const page = discoverMatchingPages(config, normalizedPathname).sort((left, right) => right.score - left.score || right.priority - left.priority)[0];
+	if (!page) throw new Error(`No Farm page route matches ${normalizedPathname}.`);
+	const layouts = collectInheritedRouteFiles(config, normalizedPathname, "layout", ROUTE_EXTENSIONS);
+	const middleware = collectMiddleware(root, Boolean(userConfig?.middleware && Object.keys(userConfig.middleware).length), config, normalizedPathname);
+	const pageSource = (0, node_fs.readFileSync)(page.filePath, "utf8");
+	const layoutSources = layouts.map((filePath) => ({
+		filePath,
+		source: (0, node_fs.readFileSync)(filePath, "utf8")
+	}));
+	const runtime = (0, _farm_js_core.resolveFarmRouteRuntimeConfig)((0, _farm_js_core.mergeFarmRouteRuntimeConfigs)((0, _farm_js_core.resolveFarmRouteRuleRuntimeConfig)(normalizedPathname, config.routeRules), ...layoutSources.map(({ source }) => readRuntimeExports(source)), readRuntimeExports(pageSource)), `Route ${page.pattern}`);
+	const matchingRules = Object.entries(config.routeRules).filter(([pattern]) => (0, _farm_js_core.farmRouteRuleMatches)(pattern, normalizedPathname)).sort(([left], [right]) => routeSpecificity(left) - routeSpecificity(right));
+	const rendering = resolveRendering(pageSource, matchingRules);
+	const cache = resolveCaching(pageSource, matchingRules);
+	const metadataSources = [...layoutSources, {
+		filePath: page.filePath,
+		source: pageSource
+	}];
+	const openGraphImage = findNearestSocialImage(config, normalizedPathname, "opengraph-image");
+	const twitterImage = findNearestSocialImage(config, normalizedPathname, "twitter-image");
+	const preset = String(config.deploy.preset || config.preset || "node-server");
+	const presetRuntime = (0, _farm_js_core.getFarmPresetRuntime)(preset);
+	const compatible = rendering.mode === "static" || rendering.mode === "client" || runtime.runtime === "auto" || presetRuntime !== "unknown" && runtime.runtime === presetRuntime;
+	const warnings = [];
+	if (presetRuntime === "unknown" && runtime.runtime !== "auto") warnings.push(`Farm cannot verify the ${runtime.runtime} route requirement because the ${preset} preset runtime is unknown.`);
+	else if (!compatible) warnings.push(`The route requires ${runtime.runtime}, but the ${preset} preset emits ${presetRuntime} functions.`);
+	if (runtime.regions?.length && preset !== "vercel" && preset !== "vercel-edge") warnings.push(`${preset} does not map Farm per-route region hints.`);
+	if (runtime.maxDuration && preset !== "vercel") warnings.push(`${preset} does not map Farm per-route maxDuration.`);
+	return {
+		pathname: normalizedPathname,
+		pattern: page.pattern,
+		params: page.params,
+		filePath: toProjectPath(root, page.filePath),
+		source: page.source,
+		layouts: layouts.map((filePath) => toProjectPath(root, filePath)),
+		middleware,
+		runtime,
+		rendering,
+		cache,
+		metadata: {
+			static: metadataSources.filter(({ source }) => /export\s+const\s+metadata\b/.test(source)).map(({ filePath }) => toProjectPath(root, filePath)),
+			dynamic: metadataSources.filter(({ source }) => /export\s+(?:async\s+)?function\s+generateMetadata\b|export\s+const\s+generateMetadata\b/.test(source)).map(({ filePath }) => toProjectPath(root, filePath)),
+			...openGraphImage ? { openGraphImage: toProjectPath(root, openGraphImage) } : {},
+			...twitterImage ? { twitterImage: toProjectPath(root, twitterImage) } : {}
+		},
+		deployment: {
+			target: String(config.deploy.target || "node"),
+			preset,
+			runtime: presetRuntime,
+			compatible,
+			warnings
+		}
+	};
+}
+function formatFarmRouteExplanation(explanation, options = {}) {
+	const color = options.color === void 0 ? picocolors.default : picocolors.default.createColors(options.color);
+	const lines = [
+		color.bold("FARM / EXPLAIN"),
+		"",
+		`${color.bold("Path")}       ${explanation.pathname}`,
+		`${color.bold("Pattern")}    ${explanation.pattern}`,
+		`${color.bold("File")}       ${explanation.filePath}`,
+		`${color.bold("Source")}     ${explanation.source}`,
+		`${color.bold("Params")}     ${formatParams(explanation.params)}`,
+		`${color.bold("Layouts")}    ${explanation.layouts.length ? explanation.layouts.join(" -> ") : "none"}`,
+		`${color.bold("Middleware")} ${explanation.middleware.length ? explanation.middleware.map((entry) => entry.filePath).join(", ") : "none"}`,
+		`${color.bold("Runtime")}    ${formatRuntime(explanation.runtime)}`,
+		`${color.bold("Rendering")}  ${explanation.rendering.mode} (${explanation.rendering.reason})${explanation.rendering.ppr ? ", PPR" : ""}`,
+		`${color.bold("Caching")}    ${formatCaching(explanation.cache)}`,
+		`${color.bold("Metadata")}   ${formatMetadata(explanation.metadata)}`,
+		`${color.bold("Deployment")} ${explanation.deployment.target} / ${explanation.deployment.preset} — ${explanation.deployment.compatible ? color.green("compatible") : color.red("incompatible")}`
+	];
+	for (const warning of explanation.deployment.warnings) lines.push(`  ${color.yellow("!")} ${warning}`);
+	return lines.join("\n");
+}
+function discoverMatchingPages(config, pathname) {
+	const candidates = [];
+	for (const [priority, source] of (0, _farm_js_core.getFarmSourceRoots)(config).entries()) {
+		const appDirectory = node_path.default.join(source.root, source.srcDir, "app");
+		if ((0, node_fs.existsSync)(appDirectory)) for (const filePath of walkFiles(appDirectory)) {
+			if (!/^page\.(?:tsx?|jsx?|vue|svelte|mdx?)$/.test(node_path.default.basename(filePath))) continue;
+			const relativeDirectory = node_path.default.relative(appDirectory, node_path.default.dirname(filePath));
+			if (relativeDirectory.split(node_path.default.sep).includes("api") || isRouteSlotDirectory(relativeDirectory)) continue;
+			const pattern = directoryToRoutePattern(relativeDirectory);
+			const match = matchRoutePattern(pattern, pathname);
+			if (!match) continue;
+			candidates.push({
+				filePath,
+				pattern,
+				params: match.params,
+				score: match.score,
+				source: source.name,
+				priority
+			});
+		}
+		const sourceDirectory = node_path.default.join(source.root, source.srcDir);
+		if (!(0, node_fs.existsSync)(sourceDirectory)) continue;
+		for (const filePath of walkFiles(sourceDirectory)) {
+			if (!/\.(?:tsx?|jsx?)$/.test(filePath) || filePath.endsWith(".d.ts")) continue;
+			const moduleSource = (0, node_fs.readFileSync)(filePath, "utf8");
+			for (const pattern of (0, _farm_js_core.scanProgrammaticPagePaths)(moduleSource)) {
+				const match = matchRoutePattern(pattern, pathname);
+				if (!match) continue;
+				candidates.push({
+					filePath,
+					pattern,
+					params: match.params,
+					score: match.score,
+					source: source.name,
+					priority
+				});
+			}
+		}
+	}
+	return candidates;
+}
+function isRouteSlotDirectory(relativeDirectory) {
+	return relativeDirectory.split(node_path.default.sep).some((segment) => /^@[A-Za-z][\w-]*$/.test(segment));
+}
+function walkFiles(directory) {
+	const files = [];
+	const pending = [directory];
+	while (pending.length) {
+		const current = pending.pop();
+		for (const entry of (0, node_fs.readdirSync)(current, { withFileTypes: true })) {
+			const entryPath = node_path.default.join(current, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+				pending.push(entryPath);
+				continue;
+			}
+			files.push(entryPath);
+		}
+	}
+	return files;
+}
+function directoryToRoutePattern(relativeDirectory) {
+	const segments = relativeDirectory.split(node_path.default.sep).filter(Boolean).filter((segment) => !/^\(.+\)$/.test(segment) && !segment.startsWith("@")).map((segment) => segment.replace(/^\(\.{1,3}\)/, ""));
+	return segments.length ? `/${segments.join("/")}` : "/";
+}
+function matchRoutePattern(pattern, pathname) {
+	const patternSegments = splitPath(pattern);
+	const pathSegments = splitPath(pathname);
+	const params = {};
+	let score = 0;
+	let pathIndex = 0;
+	for (const segment of patternSegments) {
+		const optionalCatchAll = segment.match(/^\[\[\.\.\.(.+)\]\]$/);
+		if (optionalCatchAll) {
+			params[optionalCatchAll[1]] = pathSegments.slice(pathIndex);
+			pathIndex = pathSegments.length;
+			score += 1;
+			continue;
+		}
+		const catchAll = segment.match(/^\[\.\.\.(.+)\]$/);
+		if (catchAll) {
+			if (pathIndex >= pathSegments.length) return null;
+			params[catchAll[1]] = pathSegments.slice(pathIndex);
+			pathIndex = pathSegments.length;
+			score += 10;
+			continue;
+		}
+		const dynamic = segment.match(/^\[(.+)\]$/);
+		if (dynamic) {
+			if (pathIndex >= pathSegments.length) return null;
+			params[dynamic[1]] = pathSegments[pathIndex++];
+			score += 50;
+			continue;
+		}
+		if (segment !== pathSegments[pathIndex++]) return null;
+		score += 100;
+	}
+	return pathIndex === pathSegments.length ? {
+		params,
+		score
+	} : null;
+}
+function collectInheritedRouteFiles(config, pathname, baseName, extensions) {
+	return collectLayeredRouteFiles(config, baseName, extensions).filter((entry) => matchesRoutePrefix(entry.pattern, pathname)).sort(compareInheritedRouteFiles).map((entry) => entry.filePath);
+}
+function collectMiddleware(root, hasConfigMiddleware, config, pathname) {
+	const rootMiddleware = /* @__PURE__ */ new Map();
+	for (const source of (0, _farm_js_core.getFarmSourceRoots)(config)) {
+		const filePath = findFile(node_path.default.join(source.root, source.srcDir), "middleware", MIDDLEWARE_EXTENSIONS);
+		if (filePath) rootMiddleware.set("root", {
+			filePath,
+			pattern: "/"
+		});
+	}
+	const files = [...rootMiddleware.values(), ...collectLayeredRouteFiles(config, "middleware", MIDDLEWARE_EXTENSIONS).filter((entry) => matchesRoutePrefix(entry.pattern, pathname))].sort(compareInheritedRouteFiles).map((entry) => entry.filePath);
+	return [...hasConfigMiddleware ? [{
+		source: "config",
+		filePath: "farm.config (middleware)"
+	}] : [], ...files.map((filePath) => ({
+		source: "file",
+		filePath: toProjectPath(root, filePath)
+	}))];
+}
+function collectLayeredRouteFiles(config, baseName, extensions) {
+	const files = /* @__PURE__ */ new Map();
+	const filePattern = new RegExp(`^${escapeRegExp(baseName)}\\.(?:${extensions.map(escapeRegExp).join("|")})$`);
+	for (const source of (0, _farm_js_core.getFarmSourceRoots)(config)) {
+		const appDirectory = node_path.default.join(source.root, source.srcDir, "app");
+		if (!(0, node_fs.existsSync)(appDirectory)) continue;
+		for (const filePath of walkFiles(appDirectory)) {
+			if (!filePattern.test(node_path.default.basename(filePath))) continue;
+			const pattern = directoryToRoutePattern(node_path.default.relative(appDirectory, node_path.default.dirname(filePath)));
+			files.set(pattern, {
+				filePath,
+				pattern
+			});
+		}
+	}
+	return [...files.values()];
+}
+function findNearestSocialImage(config, pathname, baseName) {
+	return collectLayeredRouteFiles(config, baseName, SOCIAL_IMAGE_EXTENSIONS).filter((entry) => matchesRoutePrefix(entry.pattern, pathname)).sort((left, right) => compareInheritedRouteFiles(right, left))[0]?.filePath;
+}
+function compareInheritedRouteFiles(left, right) {
+	return splitPath(left.pattern).length - splitPath(right.pattern).length;
+}
+function matchesRoutePrefix(pattern, pathname) {
+	const patternSegments = splitPath(pattern);
+	const pathSegments = splitPath(pathname);
+	if (patternSegments.length > pathSegments.length) return false;
+	return patternSegments.every((segment, index) => {
+		if (/^\[{1,2}(?:\.\.\.)?.+\]{1,2}$/.test(segment)) return true;
+		return segment === pathSegments[index];
+	});
+}
+function findFile(directory, baseName, extensions) {
+	return extensions.map((extension) => node_path.default.join(directory, `${baseName}.${extension}`)).find(node_fs.existsSync);
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function readRuntimeExports(source) {
+	const runtime = readStringExport(source, "runtime");
+	const maxDuration = readNumberOrAutoExport(source, "maxDuration");
+	const regions = readStringArrayOrAutoExport(source, "regions");
+	return {
+		...runtime === "auto" || runtime === "node" || runtime === "edge" ? { runtime } : {},
+		...regions ? { regions } : {},
+		...maxDuration !== void 0 ? { maxDuration } : {}
+	};
+}
+function resolveRendering(pageSource, matchingRules) {
+	const pageRendering = (0, _farm_js_core.resolveRouteRenderingConfig)({
+		...readBooleanExport(pageSource, "ssg") !== void 0 ? { ssg: readBooleanExport(pageSource, "ssg") } : {},
+		...readBooleanExport(pageSource, "ppr") !== void 0 ? { ppr: readBooleanExport(pageSource, "ppr") } : {},
+		...readBooleanExport(pageSource, "experimental_ppr") !== void 0 ? { experimental_ppr: readBooleanExport(pageSource, "experimental_ppr") } : {},
+		...readNumberOrFalseExport(pageSource, "revalidate") !== void 0 ? { revalidate: readNumberOrFalseExport(pageSource, "revalidate") } : {},
+		...readDynamicExport(pageSource) ? { dynamic: readDynamicExport(pageSource) } : {}
+	}, pageSource);
+	let mode = pageRendering.ssg ? "static" : pageRendering.ppr ? "partial" : "dynamic";
+	let reason = pageRendering.directive ? `page directive ${JSON.stringify(pageRendering.directive)}` : pageRendering.ssg ? "page static rendering declaration" : pageRendering.ppr ? "page PPR declaration" : "default server rendering";
+	let ppr = pageRendering.ppr;
+	for (const [pattern, rule] of matchingRules) if (rule.prerender === true || rule.render === "static") {
+		mode = "static";
+		reason = `routeRules ${pattern}`;
+		ppr = false;
+	} else if (rule.prerender === false || rule.render === "dynamic" || rule.ssr === true) {
+		mode = "dynamic";
+		reason = `routeRules ${pattern}`;
+		ppr = false;
+	} else if (rule.ssr === false) {
+		mode = "client";
+		reason = `routeRules ${pattern}`;
+		ppr = false;
+	}
+	return {
+		mode,
+		reason,
+		ppr
+	};
+}
+function resolveCaching(pageSource, matchingRules) {
+	let swr;
+	let isr;
+	for (const [, rule] of matchingRules) {
+		if (typeof rule.swr === "number" || typeof rule.swr === "boolean") swr = rule.swr;
+		if (typeof rule.isr === "number" || typeof rule.isr === "boolean") isr = rule.isr;
+	}
+	return {
+		...readNumberOrFalseExport(pageSource, "revalidate") !== void 0 ? { revalidate: readNumberOrFalseExport(pageSource, "revalidate") } : {},
+		...swr !== void 0 ? { swr } : {},
+		...isr !== void 0 ? { isr } : {},
+		rules: matchingRules.map(([pattern]) => pattern)
+	};
+}
+function readStringExport(source, name) {
+	return source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*["']([^"']+)["']`))?.[1];
+}
+function readDynamicExport(source) {
+	const dynamic = readStringExport(source, "dynamic");
+	return dynamic === "auto" || dynamic === "force-dynamic" || dynamic === "error" || dynamic === "force-static" ? dynamic : void 0;
+}
+function readBooleanExport(source, name) {
+	const value = source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(true|false)`))?.[1];
+	return value === void 0 ? void 0 : value === "true";
+}
+function readNumberOrAutoExport(source, name) {
+	const value = source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(?:["'](auto)["']|(\\d+))`));
+	return value?.[1] === "auto" ? "auto" : value?.[2] ? Number(value[2]) : void 0;
+}
+function readNumberOrFalseExport(source, name) {
+	const value = source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(false|\\d+)`))?.[1];
+	return value === "false" ? false : value ? Number(value) : void 0;
+}
+function readStringArrayOrAutoExport(source, name) {
+	if (source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*["']auto["']`))) return "auto";
+	const array = source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*\\[([^\\]]*)\\]`))?.[1];
+	if (array === void 0) return void 0;
+	return [...array.matchAll(/["']([^"']+)["']/g)].map((match) => match[1]);
+}
+function routeSpecificity(pattern) {
+	return splitPath(pattern).reduce((score, segment) => {
+		if (segment === "**" || segment.startsWith("[[...")) return score + 1;
+		if (segment === "*" || segment.startsWith("[...")) return score + 10;
+		if (segment.startsWith("[") || segment.startsWith(":")) return score + 50;
+		return score + 100;
+	}, 0);
+}
+function normalizePathname(value, basePath) {
+	let pathname;
+	try {
+		pathname = new URL(value, "http://farm.local").pathname;
+	} catch {
+		pathname = value;
+	}
+	pathname = pathname.startsWith("/") ? pathname : `/${pathname}`;
+	const normalizedBase = basePath && basePath !== "/" ? `/${basePath.replace(/^\/+|\/+$/g, "")}` : "";
+	if (normalizedBase && (pathname === normalizedBase || pathname.startsWith(`${normalizedBase}/`))) pathname = pathname.slice(normalizedBase.length) || "/";
+	return pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+}
+function splitPath(value) {
+	return value.split("/").filter(Boolean).map(decodeURIComponent);
+}
+function toProjectPath(root, filePath) {
+	let relativePath = node_path.default.relative(root, filePath);
+	if ((relativePath === ".." || relativePath.startsWith(`..${node_path.default.sep}`)) && (0, node_fs.existsSync)(root) && (0, node_fs.existsSync)(filePath)) relativePath = node_path.default.relative((0, node_fs.realpathSync)(root), (0, node_fs.realpathSync)(filePath));
+	return relativePath.split(node_path.default.sep).join("/");
+}
+function formatParams(params) {
+	const entries = Object.entries(params);
+	return entries.length ? entries.map(([key, value]) => `${key}=${Array.isArray(value) ? value.join("/") : value}`).join(", ") : "none";
+}
+function formatRuntime(runtime) {
+	return [
+		runtime.runtime,
+		runtime.regions?.length ? `regions=${runtime.regions.join(",")}` : "",
+		runtime.maxDuration ? `maxDuration=${runtime.maxDuration}s` : ""
+	].filter(Boolean).join(", ");
+}
+function formatCaching(cache) {
+	const values = [
+		cache.revalidate !== void 0 ? `revalidate=${cache.revalidate}` : "",
+		cache.swr !== void 0 ? `swr=${cache.swr}` : "",
+		cache.isr !== void 0 ? `isr=${cache.isr}` : "",
+		cache.rules.length ? `rules=${cache.rules.join(",")}` : ""
+	].filter(Boolean);
+	return values.length ? values.join("; ") : "request-time / no declared cache";
+}
+function formatMetadata(metadata) {
+	const values = [
+		metadata.static.length ? `static=${metadata.static.join(",")}` : "",
+		metadata.dynamic.length ? `dynamic=${metadata.dynamic.join(",")}` : "",
+		metadata.openGraphImage ? `og=${metadata.openGraphImage}` : "",
+		metadata.twitterImage ? `twitter=${metadata.twitterImage}` : ""
+	].filter(Boolean);
+	return values.length ? values.join("; ") : "none";
+}
+//#endregion
 //#region src/cron.ts
 async function loadFarmCronConfig(options = {}) {
 	const root = node_path.default.resolve(options.root || process.cwd());
@@ -2420,6 +3085,31 @@ function toPosix(value) {
 	return value.split(node_path.default.sep).join("/");
 }
 //#endregion
+//#region src/auth.ts
+async function migrateFarmAuth(options = {}) {
+	const root = node_path.default.resolve(options.root || process.cwd());
+	const userConfig = await (0, _farm_js_core.loadConfig)(root, options.configPath, "production");
+	if (!userConfig) throw new Error(`No farm.config file was found in ${root}.`);
+	if (!(await (0, _farm_js_core.resolveConfig)({
+		...userConfig,
+		root
+	}, "production")).auth.enabled) throw new Error("Farm Auth is disabled. Add `auth: true` to farm.config.ts first.");
+	const resolveFromApp = (0, node_module.createRequire)(node_path.default.join(root, "package.json"));
+	let modulePath;
+	try {
+		modulePath = resolveFromApp.resolve("@farm.js/auth/internal");
+	} catch {
+		throw new Error("Install @farm.js/auth before running `farm auth migrate`.");
+	}
+	const runtime = await import(
+		/* @vite-ignore */
+		(0, node_url.pathToFileURL)(modulePath).href
+);
+	_farm_js_core.logger.info("Applying the Farm Auth database schema...");
+	await runtime.migrateFarmAuth();
+	_farm_js_core.logger.success("Farm Auth database is ready.");
+}
+//#endregion
 //#region src/upgrade.ts
 const DEPENDENCY_SECTIONS = [
 	"dependencies",
@@ -2590,8 +3280,11 @@ function formatError(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
+exports.FarmDeployError = FarmDeployError;
+exports.FarmGeneratedArtifactsStaleError = FarmGeneratedArtifactsStaleError;
 exports.addFarmIntegration = require_add_integration.addFarmIntegration;
 exports.buildFarm = require_build.buildFarm;
+exports.createFarmDeployPlan = createFarmDeployPlan;
 exports.createFarmUpgradePlan = createFarmUpgradePlan;
 exports.createFrameworkMigrationPlan = createFrameworkMigrationPlan;
 exports.createGatewaySession = createGatewaySession;
@@ -2605,23 +3298,33 @@ Object.defineProperty(exports, "createServer", {
 });
 exports.deployFarm = deployFarm;
 exports.detectFarmPackageManager = detectFarmPackageManager;
+exports.explainFarmRoute = explainFarmRoute;
 exports.formatFarmCronJobs = formatFarmCronJobs;
+exports.formatFarmDeployPlan = formatFarmDeployPlan;
 exports.formatFarmDoctorReport = formatFarmDoctorReport;
+exports.formatFarmRouteExplanation = formatFarmRouteExplanation;
 exports.formatFarmUpgradePlan = formatFarmUpgradePlan;
 exports.forwardGatewayRequest = forwardGatewayRequest;
 exports.generateFarmArtifacts = generateFarmArtifacts;
+exports.getFarmTelemetryConfigFile = require_telemetry.getFarmTelemetryConfigFile;
+exports.getFarmTelemetryStatus = require_telemetry.getFarmTelemetryStatus;
 exports.inspectFrameworkMigrations = inspectFrameworkMigrations;
 exports.listFarmCronJobs = listFarmCronJobs;
 exports.listFarmIntegrationProviders = require_add_integration.listFarmIntegrationProviders;
 exports.loadFarmCronConfig = loadFarmCronConfig;
 exports.migrateFarm = migrateFarm;
+exports.migrateFarmAuth = migrateFarmAuth;
 exports.parsePreviewPublicUrl = parsePreviewPublicUrl;
 exports.previewFarm = previewFarm;
 exports.resolveCloudflareAgentDeployPlan = resolveCloudflareAgentDeployPlan;
+exports.resolveFarmTelemetryCommand = require_telemetry.resolveFarmTelemetryCommand;
 exports.resolvePreviewTarget = resolvePreviewTarget;
 exports.runFarmCronJob = runFarmCronJob;
 exports.runFarmDoctor = runFarmDoctor;
+exports.runNativePreviewTunnel = runNativePreviewTunnel;
 exports.runPreviewGateway = runPreviewGateway;
+exports.setFarmTelemetryEnabled = require_telemetry.setFarmTelemetryEnabled;
+exports.showFarmTelemetryNotice = require_telemetry.showFarmTelemetryNotice;
 Object.defineProperty(exports, "startDevServer", {
 	enumerable: true,
 	get: function() {
@@ -2629,6 +3332,8 @@ Object.defineProperty(exports, "startDevServer", {
 	}
 });
 exports.startFarmCronScheduler = startFarmCronScheduler;
+exports.trackFarmCommand = require_telemetry.trackFarmCommand;
+exports.trackFarmProjectCreated = require_telemetry.trackFarmProjectCreated;
 exports.upgradeFarm = upgradeFarm;
 
 //# sourceMappingURL=index.js.map