@farm.js/cli 0.1.0-beta.4 → 0.1.0-beta.40

package/dist/index.mjs

@@ -1,52 +1,172 @@
-import { n as listFarmIntegrationProviders, t as addFarmIntegration } from "./add-integration-CdVfiPjG.mjs";
+import { n as listFarmIntegrationProviders, t as addFarmIntegration } from "./add-integration-7hf9WI7e.mjs";
 import { buildFarm } from "./build.mjs";
+import { getFarmTelemetryConfigFile, getFarmTelemetryStatus, resolveFarmTelemetryCommand, setFarmTelemetryEnabled, showFarmTelemetryNotice, trackFarmCommand, trackFarmProjectCreated } from "./telemetry.mjs";
 import { createRequire } from "node:module";
 import { createServer, startDevServer } from "@farm.js/core/server";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { execFileSync, execSync } from "child_process";
+import { execFileSync } from "child_process";
 import { existsSync as existsSync$1, readFileSync as readFileSync$1 } from "fs";
 import path$1 from "path";
-import { APITypeGenerator, generateEnvTypes, generateFarmI18nTypes, generateRouteTypes, getFarmDocsRouteTypeEntries, getFarmSourceRoots, getIntegrationSchemas, getPresetForDeployTarget, loadConfig, logger, normalizeDeployTarget, resolveConfig, resolveDeployConfig, resolveDeployOutputPath } from "@farm.js/core";
+import { farmRouteRuleMatches, generateFarmTypeArtifacts, getDeployTargetForPreset, getFarmDocsRouteTypeEntries, getFarmPresetRuntime, getFarmSourceRoots, getIntegrationSchemas, getPresetForDeployTarget, loadConfig, logger, mergeFarmRouteRuntimeConfigs, normalizeDeployTarget, resolveConfig, resolveDeployConfig, resolveDeployOutputPath, resolveFarmRouteRuleRuntimeConfig, resolveFarmRouteRuntimeConfig, resolveRouteRenderingConfig, scanProgrammaticPagePaths } from "@farm.js/core";
 import { spawn, spawnSync } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import pc from "picocolors";
 import { Cron } from "croner";
+import { pathToFileURL } from "node:url";
 //#region \0rolldown/runtime.js
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 //#endregion
 //#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) {
+		logger.info(formatFarmDeployPlan(plan));
+		return plan;
+	}
+	logger.info(`🚀 Building with ${plan.preset} preset...`);
+	await buildFarm({
+		root: plan.root,
+		preset: plan.preset,
+		target: plan.target
+	});
+	if (!existsSync$1(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$1.resolve(options.root || process.cwd());
 	const mode = "production";
 	const userConfig = await loadConfig(root, void 0, mode);
-	const config = userConfig ? await resolveConfig(userConfig, mode) : void 0;
+	const config = await resolveConfig({
+		root,
+		...userConfig
+	}, mode);
 	const cliTarget = options.vercel ? "vercel" : options.cloudflare ? "cloudflare" : options.netlify ? "netlify" : void 0;
-	const platform = normalizeDeployTarget(cliTarget || config?.deploy.target);
-	if (platform !== "vercel" && platform !== "cloudflare" && platform !== "netlify") {
-		logger.error("Please specify a deployment target with --vercel, --cloudflare, --netlify, or farm.config deploy.target.");
-		process.exit(1);
-	}
+	const platform = 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 = getDeployTargetForPreset(configuredPreset);
+	const configuredTarget = normalizeDeployTarget(userConfig?.deploy?.target);
+	const presetMatchesPlatform = Boolean(configuredPreset) && (configuredPresetTarget === platform || !configuredPresetTarget && configuredTarget === platform);
+	if (cliTarget && configuredPreset && !presetMatchesPlatform) logger.warn(`Configured preset "${configuredPreset}" targets ${configuredPresetTarget || "an unknown platform"}; using the "${getPresetForDeployTarget(platform)}" preset because --${cliTarget} was passed.`);
 	const deployConfig = resolveDeployConfig(userConfig || {}, {
 		target: platform,
-		preset: cliTarget ? userConfig?.deploy?.preset || userConfig?.preset || getPresetForDeployTarget(platform) : void 0
+		preset: cliTarget ? presetMatchesPlatform ? configuredPreset : getPresetForDeployTarget(platform) : void 0
 	});
 	const preset = deployConfig.preset || getPresetForDeployTarget(platform) || "node-server";
-	logger.info(`🚀 Building with ${preset} preset...`);
-	await buildFarm({
-		root,
-		preset
-	});
 	const nitroOutput = resolveDeployOutputPath(root, deployConfig.outputDir);
-	if (!existsSync$1(nitroOutput)) {
-		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$1.resolve(root),
+			target: platform,
+			preset,
+			runtime: getFarmPresetRuntime(preset),
+			outputDir: nitroOutput,
+			production: platform === "netlify" || Boolean(options.prod),
+			build: {
+				command: `farm build --preset ${preset}`,
+				cwd: path$1.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$1.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$1.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 +188,20 @@ async function deployPlatform(platform, root, outputDir, deployConfig, prod) {
 async function deployVercel(root, outputDir, prod) {
 	logger.info("🚀 Deploying to Vercel...");
 	try {
-		execSync("vercel --version", { stdio: "ignore" });
-	} catch {
-		logger.error("❌ Vercel CLI is not installed.");
-		logger.info("💡 Install it with: npm i -g vercel");
-		process.exit(1);
+		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 {
-		execSync("vercel whoami", { stdio: "ignore" });
-	} catch {
-		logger.warn("⚠️  Not logged in to Vercel.");
-		logger.info("💡 Please run: vercel login");
-		logger.info("   Then run: farm deploy --vercel");
-		process.exit(1);
+		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 +210,8 @@ async function deployVercel(root, outputDir, prod) {
 		const configFile = path$1.join(outputDir, "config.json");
 		const serverIndex = path$1.join(functionsDir, "index.mjs");
 		logger.info("🔍 Verifying deployment structure...");
-		if (!existsSync(functionsDir)) {
-			logger.error(`❌ Functions directory not found at ${functionsDir}`);
-			process.exit(1);
-		}
-		if (!existsSync(serverIndex)) {
-			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}.`);
 		logger.info(`✅ Functions directory: ${functionsDir}`);
 		if (!existsSync(staticDir)) logger.warn(`⚠️  Static directory not found at ${staticDir}`);
 		else {
@@ -177,14 +292,19 @@ async function deployVercel(root, outputDir, prod) {
 		logger.info(`   Static: ${staticDir}`);
 		logger.info(`   Config: ${configFile}`);
 		logger.info("📤 Uploading to Vercel...");
-		execSync(`vercel deploy --prebuilt --yes${prod ? " --prod" : ""}`, {
+		execFileSync("vercel", [
+			"deploy",
+			"--prebuilt",
+			"--yes",
+			...prod ? ["--prod"] : []
+		], {
 			stdio: "inherit",
 			cwd: root
 		});
 		logger.success("✅ Deployed to Vercel successfully!");
 	} catch (error) {
-		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 +325,7 @@ async function deployCloudflare(root, outputDir, projectName) {
 			});
 			logger.success("✅ Deployed Farm and Cloudflare Agents successfully!");
 		} catch (error) {
-			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 +343,7 @@ async function deployCloudflare(root, outputDir, projectName) {
 		});
 		logger.success("✅ Deployed to Cloudflare Pages successfully!");
 	} catch (error) {
-		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 +369,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$1.resolve(root);
+	const sourceConfigPath = path$1.resolve(projectRoot, configuredPath);
+	assertPathInsideProject(projectRoot, sourceConfigPath, "Cloudflare Agents source config");
+	const configPath = path$1.join(path$1.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$1.relative(projectRoot, candidate);
+	if (relativePath === ".." || relativePath.startsWith(`..${path$1.sep}`) || path$1.isAbsolute(relativePath)) throw new Error(`${label} must stay inside the Farm project root.`);
+}
 function assertWranglerInstalled(root) {
 	try {
 		execFileSync("wrangler", ["--version"], {
 			stdio: "ignore",
 			cwd: root
 		});
-	} catch {
-		logger.error("❌ Wrangler CLI is not installed.");
-		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 +408,33 @@ function isRecord(value) {
 async function deployNetlify(root, outputDir, site) {
 	logger.info("🚀 Deploying to Netlify...");
 	try {
-		execSync("netlify --version", { stdio: "ignore" });
-	} catch {
-		logger.error("❌ Netlify CLI is not installed.");
-		logger.info("💡 Install it with: npm i -g netlify-cli");
-		process.exit(1);
+		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}` : "";
-		execSync(`netlify deploy --prod --dir=.${siteFlag}`, { stdio: "inherit" });
+		execFileSync("netlify", createNetlifyDeployArgs(site), {
+			stdio: "inherit",
+			cwd: outputDir
+		});
 		logger.success("✅ Deployed to Netlify successfully!");
 	} catch (error) {
-		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 +457,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 +627,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 +639,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 +661,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);
+	logger.success("Preview URL ready.");
+	logger.info(`Public: ${session.publicUrl}`);
+	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 +717,26 @@ async function previewFarm(options = {}) {
 				plan
 			};
 		}
-		logger.info(`Gateway: ${plan.gatewayUrl}`);
-		logger.info("Opening Farm preview gateway session...");
-		const session = await runPreviewGateway(plan, { timeoutMs: options.timeoutMs });
-		return {
-			target,
-			plan,
-			publicUrl: session.publicUrl,
-			session
-		};
+		logger.info(`Relay: ${plan.relayUrl}`);
+		logger.info("Opening native Farm preview tunnel...");
+		try {
+			const session = await runNativePreviewTunnel(plan);
+			return {
+				target,
+				plan,
+				publicUrl: session.publicUrl,
+				session
+			};
+		} catch (error) {
+			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 +754,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 +1007,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) => path.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 = path.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 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 resolveConfig({
@@ -810,34 +1028,28 @@ async function generateFarmArtifacts(options = {}) {
 		...userConfig
 	}, "development");
 	const extraRoutes = [...resolvedConfig.openapi?.enabled && resolvedConfig.openapi.route ? [resolvedConfig.openapi.route] : [], ...getFarmDocsRouteTypeEntries(resolvedConfig.docs)];
-	await generateRouteTypes({
+	const typeArtifacts = await generateFarmTypeArtifacts({
 		root: resolvedConfig.root,
 		srcDir: resolvedConfig.srcDir,
+		configPath: options.configPath,
+		layers: resolvedConfig.layers,
 		extraRoutes,
-		suppressLintOnLink: resolvedConfig.suppressLintOnLink
+		suppressLintOnLink: resolvedConfig.suppressLintOnLink,
+		componentExtensions: resolvedConfig.renderer.componentExtensions,
+		i18nConfig: resolvedConfig.i18n,
+		check: options.check
 	});
-	await generateEnvTypes({
-		root: resolvedConfig.root,
-		srcDir: resolvedConfig.srcDir,
-		configPath: options.configPath
-	});
-	const appDir = path.join(resolvedConfig.root, resolvedConfig.srcDir, "app");
-	const apiGenerator = new APITypeGenerator(appDir);
-	const apiRoutes = apiGenerator.scanAPIRoutes();
-	const apiTypesPath = path.join(resolvedConfig.root, resolvedConfig.srcDir, "lib", "api.generated.ts");
-	await mkdir(path.dirname(apiTypesPath), { recursive: true });
-	await writeFile(apiTypesPath, apiGenerator.generateAPIRouter(apiRoutes), "utf8");
-	if (resolvedConfig.i18n.enabled) await generateFarmI18nTypes({
-		root: resolvedConfig.root,
-		srcDir: resolvedConfig.srcDir,
-		config: resolvedConfig.i18n
-	});
-	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);
+		logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types are up to date.`);
+		return typeArtifacts;
+	}
+	logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types (${typeArtifacts.apiRoutes.length} API route${typeArtifacts.apiRoutes.length === 1 ? "" : "s"}).`);
 	const schemas = getIntegrationSchemas(resolvedConfig.integrations);
 	const schemaEntries = Object.entries(schemas);
 	if (!schemaEntries.length) {
 		if (hasSchemaOptions(options)) 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 +1059,12 @@ async function generateFarmArtifacts(options = {}) {
 	} catch (error) {
 		if (schemaOptionsExplicit) throw error;
 		logger.warn(`Integration schemas were found, but Farm could not choose a schema target automatically: ${error.message}`);
-		return;
+		return typeArtifacts;
 	}
 	if (!orm) {
 		if (!schemaOptionsExplicit) {
 			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 +1075,7 @@ async function generateFarmArtifacts(options = {}) {
 			if (!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);
 			logger.success(`Generated Prisma integration schema in ${path.relative(root, schemaPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "drizzle": {
 			const dialect = options.dialect ?? await detectDrizzleDialect(root, packageManifest) ?? void 0;
@@ -871,7 +1083,7 @@ async function generateFarmArtifacts(options = {}) {
 			const outputPath = options.output ? path.resolve(root, options.output) : path.join(root, "farm-integrations.generated.ts");
 			await writeGeneratedFile(outputPath, generateDrizzleSchema(collectedModels, dialect));
 			logger.success(`Generated Drizzle integration schema in ${path.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "postgres":
 		case "mysql":
@@ -879,13 +1091,13 @@ async function generateFarmArtifacts(options = {}) {
 			const outputPath = options.output ? path.resolve(root, options.output) : path.join(root, `farm-integrations.generated.${orm}.sql`);
 			await writeGeneratedFile(outputPath, generateSqlSchema(collectedModels, orm));
 			logger.success(`Generated ${orm} integration schema in ${path.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "mongodb": {
 			const outputPath = options.output ? path.resolve(root, options.output) : path.join(root, "farm-integrations.generated.mongodb.ts");
 			await writeGeneratedFile(outputPath, generateMongoBootstrap(collectedModels));
 			logger.success(`Generated MongoDB integration bootstrap in ${path.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 	}
 }
@@ -1070,7 +1282,7 @@ function cloneSchemaModel(model) {
 async function writePrismaSchema(schemaPath, models) {
 	const source = await 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 writeFile(schemaPath, nextSource, "utf8");
 }
@@ -1398,16 +1610,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,10 +1638,10 @@ async function runFarmDoctor(options = {}) {
 	const root = path.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$1(error);
+		liveError = formatError$2(error);
 	}
 	const report = await createProjectReport(root, options);
 	if (!options.offline && hasExplicitLiveTarget(options) && liveError) {
@@ -1472,6 +1685,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 +1791,10 @@ async function createProjectReport(root, options) {
 			action: "Add farm.config.ts and export defineConfig({...})."
 		});
 		else {
+			const configRoot = path.resolve(root, userConfig.root || ".");
 			config = await resolveConfig({
-				root,
-				...userConfig
+				...userConfig,
+				root: configRoot
 			}, "development");
 			const configFile = findConfigFile(root, options.configPath);
 			checks.push({
@@ -1588,7 +1809,7 @@ async function createProjectReport(root, options) {
 			status: "fail",
 			code: "CONFIG_INVALID",
 			title: "Farm config could not be resolved",
-			message: formatError$1(error),
+			message: formatError$2(error),
 			action: "Fix the config or environment validation error, then run farm doctor again."
 		});
 	}
@@ -1597,9 +1818,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 = path.join(config.root, config.srcDir, "app", `layout${rendererExtension}`);
+		if (!existsSync(layoutPath)) {
+			mkdirSync(path.dirname(layoutPath), { recursive: true });
+			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: path.relative(root, layoutPath)
+			});
+		}
+	}
+	return fixes;
+}
 function collectNodeCheck(checks) {
 	const major = Number(process.versions.node.split(".")[0]);
 	checks.push(major >= 18 ? {
@@ -1651,7 +1904,7 @@ function collectPackageCheck(root, checks) {
 			status: "fail",
 			code: "PACKAGE_INVALID",
 			title: "package.json is invalid",
-			message: formatError$1(error),
+			message: formatError$2(error),
 			action: "Fix the package manifest JSON."
 		});
 	}
@@ -1659,8 +1912,8 @@ function collectPackageCheck(root, checks) {
 function collectRouterChecks(config, checks) {
 	const sources = getFarmSourceRoots(config);
 	const appDirectories = sources.map((source) => path.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) => existsSync(path.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) => existsSync(path.join(source.root, source.srcDir, `farm.routes.${extension}`))));
 	checks.push(hasPages || hasProgrammaticRoutes ? {
 		status: "pass",
 		code: "APP_ROUTER_READY",
@@ -1673,7 +1926,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) => existsSync(path.join(directory, `layout.${extension}`))));
+	const hasRootLayout = appDirectories.some((directory) => ROUTE_EXTENSIONS$1.some((extension) => existsSync(path.join(directory, `layout.${extension}`))));
+	const suggestedLayoutExtension = config.renderer.componentExtensions?.[0] || ".tsx";
 	checks.push(hasRootLayout ? {
 		status: "pass",
 		code: "ROOT_LAYOUT_READY",
@@ -1684,7 +1938,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 +1997,7 @@ function hasCronRoute(config, job) {
 	const relative = job.path.replace(/^\/+/, "").replace(/^api\//, "");
 	return getFarmSourceRoots(config).some((source) => {
 		const directory = path.join(source.root, source.srcDir, "app", "api", relative);
-		return ROUTE_EXTENSIONS.some((extension) => existsSync(path.join(directory, `route.${extension}`)));
+		return ROUTE_EXTENSIONS$1.some((extension) => existsSync(path.join(directory, `route.${extension}`)));
 	});
 }
 function containsFile(directory, pattern) {
@@ -1804,13 +2058,422 @@ function finalizeReport(report) {
 function asRecord(value) {
 	return value && typeof value === "object" ? value : {};
 }
-function formatError$1(error) {
+function formatError$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 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 = path.resolve(options.root || process.cwd());
+	const userConfig = await loadConfig(root, options.configPath, "production");
+	const config = await 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 = readFileSync(page.filePath, "utf8");
+	const layoutSources = layouts.map((filePath) => ({
+		filePath,
+		source: readFileSync(filePath, "utf8")
+	}));
+	const runtime = resolveFarmRouteRuntimeConfig(mergeFarmRouteRuntimeConfigs(resolveFarmRouteRuleRuntimeConfig(normalizedPathname, config.routeRules), ...layoutSources.map(({ source }) => readRuntimeExports(source)), readRuntimeExports(pageSource)), `Route ${page.pattern}`);
+	const matchingRules = Object.entries(config.routeRules).filter(([pattern]) => 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 = 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 ? pc : pc.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 getFarmSourceRoots(config).entries()) {
+		const appDirectory = path.join(source.root, source.srcDir, "app");
+		if (existsSync(appDirectory)) for (const filePath of walkFiles(appDirectory)) {
+			if (!/^page\.(?:tsx?|jsx?|vue|svelte|mdx?)$/.test(path.basename(filePath))) continue;
+			const relativeDirectory = path.relative(appDirectory, path.dirname(filePath));
+			if (relativeDirectory.split(path.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 = path.join(source.root, source.srcDir);
+		if (!existsSync(sourceDirectory)) continue;
+		for (const filePath of walkFiles(sourceDirectory)) {
+			if (!/\.(?:tsx?|jsx?)$/.test(filePath) || filePath.endsWith(".d.ts")) continue;
+			const moduleSource = readFileSync(filePath, "utf8");
+			for (const pattern of 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(path.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 readdirSync(current, { withFileTypes: true })) {
+			const entryPath = path.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(path.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 getFarmSourceRoots(config)) {
+		const filePath = findFile(path.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 getFarmSourceRoots(config)) {
+		const appDirectory = path.join(source.root, source.srcDir, "app");
+		if (!existsSync(appDirectory)) continue;
+		for (const filePath of walkFiles(appDirectory)) {
+			if (!filePattern.test(path.basename(filePath))) continue;
+			const pattern = directoryToRoutePattern(path.relative(appDirectory, path.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) => path.join(directory, `${baseName}.${extension}`)).find(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 = 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 = path.relative(root, filePath);
+	if ((relativePath === ".." || relativePath.startsWith(`..${path.sep}`)) && existsSync(root) && existsSync(filePath)) relativePath = path.relative(realpathSync(root), realpathSync(filePath));
+	return relativePath.split(path.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 = path.resolve(options.root || process.cwd());
@@ -1861,7 +2524,7 @@ async function startFarmCronScheduler(options = {}) {
 				logger.warn(`Cron ${job.name} skipped an overlapping run.`);
 			},
 			catch: (error) => {
-				logger.error(`Cron ${job.name} failed: ${formatError(error)}`);
+				logger.error(`Cron ${job.name} failed: ${formatError$1(error)}`);
 			}
 		}, async () => {
 			logger.info(`Cron ${job.name} -> ${job.path}`);
@@ -1950,7 +2613,7 @@ function formatResponseDetail(body) {
 	const detail = typeof body === "string" ? body : JSON.stringify(body);
 	return detail ? `: ${detail}` : "";
 }
-function formatError(error) {
+function formatError$1(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
@@ -2420,6 +3083,201 @@ function toPosix(value) {
 	return value.split(path.sep).join("/");
 }
 //#endregion
-export { addFarmIntegration, buildFarm, createFrameworkMigrationPlan, createGatewaySession, createPreviewGatewayPlan, createPreviewTunnelPlan, createServer, deployFarm, formatFarmCronJobs, formatFarmDoctorReport, forwardGatewayRequest, generateFarmArtifacts, inspectFrameworkMigrations, listFarmCronJobs, listFarmIntegrationProviders, loadFarmCronConfig, migrateFarm, parsePreviewPublicUrl, previewFarm, resolveCloudflareAgentDeployPlan, resolvePreviewTarget, runFarmCronJob, runFarmDoctor, runPreviewGateway, startDevServer, startFarmCronScheduler };
+//#region src/auth.ts
+async function migrateFarmAuth(options = {}) {
+	const root = path.resolve(options.root || process.cwd());
+	const userConfig = await loadConfig(root, options.configPath, "production");
+	if (!userConfig) throw new Error(`No farm.config file was found in ${root}.`);
+	if (!(await resolveConfig({
+		...userConfig,
+		root
+	}, "production")).auth.enabled) throw new Error("Farm Auth is disabled. Add `auth: true` to farm.config.ts first.");
+	const resolveFromApp = createRequire(path.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 */
+		pathToFileURL(modulePath).href
+);
+	logger.info("Applying the Farm Auth database schema...");
+	await runtime.migrateFarmAuth();
+	logger.success("Farm Auth database is ready.");
+}
+//#endregion
+//#region src/upgrade.ts
+const DEPENDENCY_SECTIONS = [
+	"dependencies",
+	"devDependencies",
+	"optionalDependencies",
+	"peerDependencies"
+];
+const LOCAL_SPECIFIER_PREFIXES = [
+	"workspace:",
+	"file:",
+	"link:",
+	"portal:",
+	"catalog:"
+];
+async function createFarmUpgradePlan(options) {
+	assertUpgradeChannel(options.channel);
+	const root = path.resolve(options.root || process.cwd());
+	const packageJsonPath = path.join(root, "package.json");
+	let packageJson;
+	try {
+		packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+	} catch (error) {
+		if (!existsSync(packageJsonPath)) throw new Error(`No package.json found at ${packageJsonPath}.`);
+		throw new Error(`Could not read ${packageJsonPath}: ${formatError(error)}`);
+	}
+	const packageManager = options.packageManager || detectFarmPackageManager(root, packageJson.packageManager);
+	const packages = [];
+	const skipped = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const section of DEPENDENCY_SECTIONS) {
+		const dependencies = packageJson[section];
+		if (!dependencies || typeof dependencies !== "object") continue;
+		for (const [name, rawSpecifier] of Object.entries(dependencies)) {
+			if (!name.startsWith("@farm.js/") || seen.has(name)) continue;
+			seen.add(name);
+			const current = typeof rawSpecifier === "string" ? rawSpecifier : String(rawSpecifier);
+			if (isLocalSpecifier(current)) {
+				skipped.push({
+					name,
+					current,
+					section,
+					reason: "local workspace and file dependencies are not published-package upgrades"
+				});
+				continue;
+			}
+			packages.push({
+				name,
+				current,
+				section,
+				target: `${name}@${options.channel}`
+			});
+		}
+	}
+	if (packages.length === 0) {
+		const suffix = skipped.length > 0 ? " The Farm packages in this project use local workspace or file references." : "";
+		throw new Error(`No published @farm.js/* dependencies were found in ${packageJsonPath}.${suffix}`);
+	}
+	packages.sort((left, right) => left.name.localeCompare(right.name));
+	skipped.sort((left, right) => left.name.localeCompare(right.name));
+	return {
+		root,
+		packageJsonPath,
+		packageManager,
+		channel: options.channel,
+		packages,
+		skipped,
+		commands: createUpgradeCommands(root, packageManager, packages)
+	};
+}
+async function upgradeFarm(options) {
+	const plan = await createFarmUpgradePlan(options);
+	if (options.dryRun) return {
+		plan,
+		executed: false
+	};
+	const runCommand = options.runCommand || runFarmUpgradeCommand;
+	for (const command of plan.commands) await runCommand(command);
+	return {
+		plan,
+		executed: true
+	};
+}
+function formatFarmUpgradePlan(plan) {
+	const lines = [
+		`Farm upgrade: ${plan.channel === "latest" ? "latest stable" : "latest beta"}`,
+		`Project: ${plan.root}`,
+		`Package manager: ${plan.packageManager}`,
+		"Packages:"
+	];
+	for (const entry of plan.packages) lines.push(`  ${entry.name} (${entry.section}): ${entry.current} -> ${plan.channel}`);
+	if (plan.skipped.length > 0) {
+		lines.push("Skipped local packages:");
+		for (const entry of plan.skipped) lines.push(`  ${entry.name} (${entry.current})`);
+	}
+	lines.push("Commands:");
+	for (const command of plan.commands) lines.push(`  ${command.command} ${command.args.join(" ")}`);
+	return lines.join("\n");
+}
+function detectFarmPackageManager(root, packageManagerField) {
+	if (typeof packageManagerField === "string") {
+		const name = packageManagerField.split("@", 1)[0];
+		if (isFarmPackageManager(name)) return name;
+	}
+	for (const [packageManager, lockfiles] of [
+		["pnpm", ["pnpm-lock.yaml"]],
+		["yarn", ["yarn.lock"]],
+		["bun", ["bun.lock", "bun.lockb"]],
+		["npm", ["package-lock.json", "npm-shrinkwrap.json"]]
+	]) if (lockfiles.some((lockfile) => existsSync(path.join(root, lockfile)))) return packageManager;
+	return "npm";
+}
+function createUpgradeCommands(root, packageManager, packages) {
+	const command = packageManager === "npm" ? "install" : "add";
+	return DEPENDENCY_SECTIONS.flatMap((section) => {
+		const targets = packages.filter((entry) => entry.section === section).map((entry) => entry.target);
+		if (targets.length === 0) return [];
+		return [{
+			command: packageManager,
+			args: [
+				command,
+				...getDependencySectionFlags(packageManager, section),
+				...targets
+			],
+			cwd: root
+		}];
+	});
+}
+function getDependencySectionFlags(packageManager, section) {
+	if (section === "dependencies") return [];
+	if (packageManager === "yarn" || packageManager === "bun") {
+		if (section === "devDependencies") return ["--dev"];
+		if (section === "optionalDependencies") return ["--optional"];
+		return ["--peer"];
+	}
+	if (section === "devDependencies") return ["--save-dev"];
+	if (section === "optionalDependencies") return ["--save-optional"];
+	return ["--save-peer"];
+}
+function runFarmUpgradeCommand(command) {
+	return new Promise((resolve, reject) => {
+		const executable = process.platform === "win32" ? `${command.command}.cmd` : command.command;
+		const child = spawn(executable, command.args, {
+			cwd: command.cwd,
+			env: process.env,
+			stdio: "inherit"
+		});
+		child.on("error", reject);
+		child.on("close", (code, signal) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			const termination = signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`;
+			reject(/* @__PURE__ */ new Error(`${command.command} ${command.args.join(" ")} failed with ${termination}.`));
+		});
+	});
+}
+function isLocalSpecifier(specifier) {
+	return LOCAL_SPECIFIER_PREFIXES.some((prefix) => specifier.startsWith(prefix));
+}
+function isFarmPackageManager(value) {
+	return value === "npm" || value === "pnpm" || value === "yarn" || value === "bun";
+}
+function assertUpgradeChannel(channel) {
+	if (channel !== "latest" && channel !== "beta") throw new Error("Farm upgrade channel must be \"latest\" or \"beta\".");
+}
+function formatError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+export { FarmDeployError, FarmGeneratedArtifactsStaleError, addFarmIntegration, buildFarm, createFarmDeployPlan, createFarmUpgradePlan, createFrameworkMigrationPlan, createGatewaySession, createPreviewGatewayPlan, createPreviewTunnelPlan, createServer, deployFarm, detectFarmPackageManager, explainFarmRoute, formatFarmCronJobs, formatFarmDeployPlan, formatFarmDoctorReport, formatFarmRouteExplanation, formatFarmUpgradePlan, forwardGatewayRequest, generateFarmArtifacts, getFarmTelemetryConfigFile, getFarmTelemetryStatus, inspectFrameworkMigrations, listFarmCronJobs, listFarmIntegrationProviders, loadFarmCronConfig, migrateFarm, migrateFarmAuth, parsePreviewPublicUrl, previewFarm, resolveCloudflareAgentDeployPlan, resolveFarmTelemetryCommand, resolvePreviewTarget, runFarmCronJob, runFarmDoctor, runNativePreviewTunnel, runPreviewGateway, setFarmTelemetryEnabled, showFarmTelemetryNotice, startDevServer, startFarmCronScheduler, trackFarmCommand, trackFarmProjectCreated, upgradeFarm };
 
 //# sourceMappingURL=index.mjs.map